Skip to main content

Pay-Out · Turkey

TOPPAY TeamAbout 1 min

Request

Pay-Out API for sending funds to recipients in Turkey (country code tr).

  • Amounts are in TRY, positive, with up to 2 decimal places (e.g. 100, 100.50).
  • bankCode is BANK. See Regional Payment Guide — Turkey.
  • bankCard is a Turkey IBAN: uppercase TR plus 24 digits (26 characters). No spaces, no lowercase. Example: TR330006100519786457841326.
  • accountName must be 5 to 50 characters after trimming.

Endpoint

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-tr-openapi.toppayment.com) remains available.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/tr/disbursement/cash
Productionhttps://openapi.toppayment.com/tr/disbursement/cash

Request Headers

FieldRequiredTypeDescription
Content-TypeMStringFixed: application/json

Request Body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
orderNumMString(50)Merchant order number
amountMNumberAmount in TRY, up to 2 decimal places
bankCodeMString(32)Fixed BANK — see Turkey guide
bankCardMString(50)Turkey IBAN: TR + 24 digits, no spaces
accountNameMString(50)Recipient name, length 5–50
descriptionOString(255)Description
feeTypeMNumber(0 or 1)Fee type: 0 deducted from amount, 1 charged separately
downNotifyUrlMString(164)Webhook URL
timestampMString(13)Millisecond timestamp
signMStringRSA signature — see Signature

Request Example

{
    "mchNo": "{{mchNo}}",
    "orderNum": "TRPAYOUT1234561",
    "amount": 100.50,
    "bankCode": "BANK",
    "bankCard": "TR330006100519786457841326",
    "accountName": "MEHMET YILMAZ",
    "description": "test",
    "feeType": 1,
    "downNotifyUrl": "https://example.com/notify",
    "timestamp": "1749451858772",
    "sign": "replace with a signature"
}

Response

HTTP Response

FieldRequiredTypeDescription
Content-TypeMStringHTTP response content type specification
Fixed value: application/json

status values are in Transaction Status Codes.

{
    "success": true,
    "code": "9999",
    "msg": "SUCCESS",
    "timeStamp": 1767772957433,
    "data": {
        "orderNum": "TRPAYOUT1234561",
        "platOrderNum": "TRANS2008811496544403456",
        "amount": 100.50,
        "fee": 2.00,
        "feeType": 1,
        "status": 1,
        "statusMsg": "ORDER_RECEIVED_PROCESSING",
        "bankCode": "BANK",
        "bankCard": "TR330006100519786457841326",
        "accountName": "MEHMET YILMAZ",
        "description": "test"
    }
}

Notification

HTTP Request

FieldRequiredTypeDescription
Content-TypeMStringapplication/json

Notification Body

FieldRequiredTypeDescription
platOrderNumMStringPlatform order number
versionMStringAPI version
orderNumMStringMerchant order number
amountMNumberTransaction amount
feeMNumberFee
feeTypeMNumberFee type
statusMNumberTransaction status; see Transaction Status Codes
statusMsgMStringStatus message
bankCodeMStringBank code; Turkey uses BANK
bankCardMStringBeneficiary IBAN
accountNameMStringBeneficiary name
descriptionOStringTransaction description
signMStringNotification signature

Response

Verify the signature, then return the plain string SUCCESS only.

SUCCESS

Notification Example

{
  "platOrderNum": "TRANS2008811496544403456",
  "version": "v1",
  "orderNum": "TRPAYOUT1234561",
  "amount": 100.50,
  "fee": 2.00,
  "feeType": 1,
  "status": 2,
  "statusMsg": "SUCCESS",
  "bankCode": "BANK",
  "bankCard": "TR330006100519786457841326",
  "accountName": "MEHMET YILMAZ",
  "description": "test",
  "sign": "…"
}