Pay-Out · Turkey
About 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).
bankCodeisBANK. See Regional Payment Guide — Turkey.bankCardis a Turkey IBAN: uppercaseTRplus 24 digits (26 characters). No spaces, no lowercase. Example:TR330006100519786457841326.accountNamemust 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.
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/tr/disbursement/cash |
| Production | https://openapi.toppayment.com/tr/disbursement/cash |
Request Headers
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed: application/json |
Request Body
| Field | Required | Type | Description |
|---|---|---|---|
| mchNo | M | String(32) | Merchant number |
| orderNum | M | String(50) | Merchant order number |
| amount | M | Number | Amount in TRY, up to 2 decimal places |
| bankCode | M | String(32) | Fixed BANK — see Turkey guide |
| bankCard | M | String(50) | Turkey IBAN: TR + 24 digits, no spaces |
| accountName | M | String(50) | Recipient name, length 5–50 |
| description | O | String(255) | Description |
| feeType | M | Number(0 or 1) | Fee type: 0 deducted from amount, 1 charged separately |
| downNotifyUrl | M | String(164) | Webhook URL |
| timestamp | M | String(13) | Millisecond timestamp |
| sign | M | String | RSA 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
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP 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
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | application/json |
Notification Body
| Field | Required | Type | Description |
|---|---|---|---|
| platOrderNum | M | String | Platform order number |
| version | M | String | API version |
| orderNum | M | String | Merchant order number |
| amount | M | Number | Transaction amount |
| fee | M | Number | Fee |
| feeType | M | Number | Fee type |
| status | M | Number | Transaction status; see Transaction Status Codes |
| statusMsg | M | String | Status message |
| bankCode | M | String | Bank code; Turkey uses BANK |
| bankCard | M | String | Beneficiary IBAN |
| accountName | M | String | Beneficiary name |
| description | O | String | Transaction description |
| sign | M | String | Notification 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": "…"
}
