Pay-In · Turkey
Overview
Pay-in API for collecting payments from customers in Turkey (country code tr). Two order modes are supported:
| Mode | Path | Description |
|---|---|---|
| Cashier | /pay/prePay | Default. Returns cashierUrl; the customer completes payment on the platform H5 cashier |
| API | /pay/transOrder | method is required. Returns payData / payDataType directly |
- Amounts are in TRY, positive, with at most 2 decimal places (e.g.
100,100.50;100.555is rejected). methodisBANK(bank transfer) only. See Regional Payment Guide — Turkey.customerNameandcustomerPhoneare required.
Integration
Cashier mode is enabled by default. Contact support to whitelist the merchant before integrating API mode.
Request Headers
Shared by both modes:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed: application/json |
Cashier (prePay)
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/pay/prePay |
| Production | https://openapi.toppayment.com/tr/pay/prePay |
Request Body
| Field | Required | Type | Description |
|---|---|---|---|
| mchNo | M | String(32) | Merchant number |
| orderNum | M | String(64) | Merchant order number |
| amount | M | Number | Amount in TRY, up to 2 decimal places |
| productDetail | O | String(100) | Product detail |
| method | O | String(16) | Optional; if omitted, the customer chooses at the cashier. BANK only. See Turkey guide |
| timestamp | M | String(13) | Millisecond timestamp |
| customerName | M | String(64) | Customer name |
| customerEmail | O | String(64) | Customer email |
| customerPhone | M | String(32) | Customer phone |
| downNotifyUrl | M | String(255) | Webhook URL |
| redirectUrl | O | String(512) | Redirect URL after payment |
| sign | M | String | RSA signature — see Signature |
Request Example
{
"mchNo": "{{mchNo}}",
"orderNum": "TR1234561",
"amount": 100.50,
"productDetail": "test",
"method": "BANK",
"timestamp": "1749451858772",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "replace with a signature"
}
HTTP Response
Shared by both modes:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP response content type specification Fixed value: application/json |
Response Fields
| Field | Required | Type | Description |
|---|---|---|---|
| success | M | Boolean | Whether the request succeeded |
| code | M | String | 9999 success; otherwise failure |
| msg | O | String | Message; null on success |
| timeStamp | M | Number | Response timestamp in milliseconds |
| data | M | Object | Payload |
| orderNum | M | String | Merchant order number |
| platOrderNum | M | String | Platform order number |
| amount | M | Number | Amount |
| fee | M | Number | Fee |
| method | O | String | Payment method |
| productDetail | O | String | Product detail |
| customerName | M | String | Customer name |
| customerEmail | O | String | Customer email |
| customerPhone | M | String | Customer phone |
| validTime | M | Number | Expiry time, millisecond timestamp |
| cashierUrl | M | String | Platform cashier URL |
Response
Cashier mode does not return payData or payDataType. Those fields appear only in API mode.
Response Example
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "TR1234561",
"platOrderNum": "TRPTJ2009093829059153920",
"amount": 100.50,
"fee": 2.00,
"method": "BANK",
"productDetail": "test",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
API (transOrder)
Endpoint
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/tr/pay/transOrder |
| Production | https://openapi.toppayment.com/tr/pay/transOrder |
Request Body
Difference from cashier mode:
| Field | Required | Type | Description |
|---|---|---|---|
| method | M | String(16) | Required in API mode. BANK only — see Turkey guide |
Other fields match cashier mode.
Request Example
{
"mchNo": "{{mchNo}}",
"orderNum": "TRPAYINAPI1234561",
"amount": 100.50,
"productDetail": "test",
"method": "BANK",
"timestamp": "1749451858772",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "replace with a signature"
}
Response Fields
Shared fields match cashier mode. API mode returns payment data by these rules:
| Field | Required | Type | Description |
|---|---|---|---|
| payData | M | String | Account number when payDataType is VA; checkout URL when payDataType is CASHIER_URL |
| payDataType | M | String | VA when an account number is present; otherwise CASHIER_URL |
| cashierUrl | O | String | Checkout URL. For VA, set only when a checkout URL is also returned, otherwise null. For CASHIER_URL, the same value as payData |
The example below is the checkout-URL-only case. When an account number is present, payDataType is VA and payData is that account number.
Response Example
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "TRPAYINAPI1234561",
"platOrderNum": "TRPTJ2009093829059153920",
"amount": 100.50,
"fee": 2.00,
"method": "BANK",
"productDetail": "test",
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay",
"payData": "https://example.cashier/pay",
"payDataType": "CASHIER_URL"
}
}
Notification
Both modes use the same webhook.
HTTP Request (callback)
| 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, e.g. v1 |
| orderNum | M | String | Merchant order number |
| amount | M | Number | Amount |
| fee | M | Number | Fee |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| status | M | String | Status — see Transaction Status Codes |
| sign | M | String | Callback signature |
Response
Verify the signature, then return the plain string SUCCESS only.
SUCCESS
Notification Example
{
"platOrderNum": "TRPTJ2009093829059153920",
"version": "v1",
"orderNum": "TR1234561",
"amount": 100.50,
"fee": 2.00,
"customerName": "MEHMET YILMAZ",
"customerEmail": "[email protected]",
"customerPhone": "905551112233",
"status": "SUCCESS",
"sign": "…"
}
