Skip to main content

Pay-In · Turkey

TOPPAY TeamAbout 3 min

Overview

Pay-in API for collecting payments from customers in Turkey (country code tr). Two order modes are supported:

ModePathDescription
Cashier/pay/prePayDefault. Returns cashierUrl; the customer completes payment on the platform H5 cashier
API/pay/transOrdermethod is required. Returns payData / payDataType directly
  • Amounts are in TRY, positive, with at most 2 decimal places (e.g. 100, 100.50; 100.555 is rejected).
  • method is BANK (bank transfer) only. See Regional Payment Guide — Turkey.
  • customerName and customerPhone are required.

Integration

Cashier mode is enabled by default. Contact support to whitelist the merchant before integrating API mode.

Request Headers

Shared by both modes:

FieldRequiredTypeDescription
Content-TypeMStringFixed: 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.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/tr/pay/prePay
Productionhttps://openapi.toppayment.com/tr/pay/prePay

Request Body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
orderNumMString(64)Merchant order number
amountMNumberAmount in TRY, up to 2 decimal places
productDetailOString(100)Product detail
methodOString(16)Optional; if omitted, the customer chooses at the cashier. BANK only. See Turkey guide
timestampMString(13)Millisecond timestamp
customerNameMString(64)Customer name
customerEmailOString(64)Customer email
customerPhoneMString(32)Customer phone
downNotifyUrlMString(255)Webhook URL
redirectUrlOString(512)Redirect URL after payment
signMStringRSA 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:

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

Response Fields

FieldRequiredTypeDescription
successMBooleanWhether the request succeeded
codeMString9999 success; otherwise failure
msgOStringMessage; null on success
timeStampMNumberResponse timestamp in milliseconds
dataMObjectPayload
orderNumMStringMerchant order number
platOrderNumMStringPlatform order number
amountMNumberAmount
feeMNumberFee
methodOStringPayment method
productDetailOStringProduct detail
customerNameMStringCustomer name
customerEmailOStringCustomer email
customerPhoneMStringCustomer phone
validTimeMNumberExpiry time, millisecond timestamp
cashierUrlMStringPlatform 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

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/tr/pay/transOrder
Productionhttps://openapi.toppayment.com/tr/pay/transOrder

Request Body

Difference from cashier mode:

FieldRequiredTypeDescription
methodMString(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:

FieldRequiredTypeDescription
payDataMStringAccount number when payDataType is VA; checkout URL when payDataType is CASHIER_URL
payDataTypeMStringVA when an account number is present; otherwise CASHIER_URL
cashierUrlOStringCheckout 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)

FieldRequiredTypeDescription
Content-TypeMStringapplication/json

Notification Body

FieldRequiredTypeDescription
platOrderNumMStringPlatform order number
versionMStringAPI version, e.g. v1
orderNumMStringMerchant order number
amountMNumberAmount
feeMNumberFee
customerNameMStringCustomer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
statusMStringStatus — see Transaction Status Codes
signMStringCallback 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": "…"
}