Turkey Payment API

About 1299 wordsAbout 4 min

Warning

Before reading this API document, please make sure to check API Description Guide

Collection API

Collection Application

Brief Description:

Create a collection order

URL：/try/collect/apply
Note: appId TRY, amount TRY, settlement TRY

Parameters:

Parameter Name	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, must pass the corresponding business ID according to the currency in the URL)
orderId	Yes	String	Merchant Order Number (must be unique, max length 48)
name	Yes	String	Payee Name
phone	Yes	String	Real mobile number (format reference Phone Number Format )
email	Yes	String	Real email
amount	Yes	String	Transaction Amount (unit: local currency, accurate to two decimal places; punctuation such as “,” is prohibited)
currency	No	String	Currency (TRY)
payType	Yes	String	Transaction Type PAYMENT_GATEWAY
inBankCode	Yes	String	Payment Method
callBackUrl	Yes	String	Redirect URL after successful payment
callBackFailUrl	Yes	String	Redirect URL after failed payment
notifyUrl	No	String	Callback URL
subject	No	String	Payment Remark
body	No	String	Remark Details
partnerUserId	Yes	String	Unique user identifier (e.g., user ID userId), used for risk control, must be real and valid, otherwise it may affect the transaction. Format: numbers, uppercase/lowercase letters, or commonly used symbols -~!@#$%&*()_.
sign	Yes	String	Signature

request

{
    "appId": 1054,
    "orderId": "M233323000059",
    "amount": "300",
    "phone": "09230219312",
    "email": "23423@qq.com",
    "name": "test",
    "inBankCode": "GPay",
    "payType": "PAYMENT_GATEWAY",
    "partnerUserId": "149597870",
    "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}

va-response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M233323000059",
        "orderNo": "6023071013539074",
        "payUrl": "",
        "sign": "YEoA8Y2JzQFGVzwJSqmemm1Kfv/bfyIfCqv2dp7RNzT5B72AQvdD+nt2nR4sL1HWscvmNHyVt5ovAi7MMhy3ziih/sMph+wPx4YjH3W1h5DyBvSlWvaKfKrK5ViomZ0pPYWydwRHnnRnicxToHK9S6qtSy7Q73O0hdz4hJ9p41Th3ycBl2Q9SeqSZYSY1ohcPDhdyRf2y0prb8rHgpBKzxZ5BKX/1bsE9OmsSEHAEYT8OGgko6aNe8XPAhr4G48cpWTftvnGQuzh0O65nuZRI/PF+Axt2zJCVbFHDDSREI9NlAT82ebDqhlVdxQzKE67D1nxgjb3dPmDUYHOBpmwxQ=="
    }
}

title: Turkey Payment API permalink: /api/version2/Turkey/

Turkey Payment API

Warning

Before reading this API documentation, please check API Description Guide

Collection API

Collection Apply

Brief Description:

Create a collection order

URL: /try/collect/apply
Note: appId in TRY, amount in TRY, settlement in TRY

Response Data Parameters

Parameter	Type	Description
orderId	String	Merchant Order ID (must be unique)
orderNo	String	Platform Order ID
payUrl	String	Payment URL
sign	String	Signature

Collection Order Query

Brief Description:

Query a collection order
When payType=BANK_TRANSFER, the orderNo is returned synchronously and can be queried directly
For other payment methods, after asynchronous notification, confirm the status again through orderNo

URL: /try/collect/query

Parameters

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend; must match the currency in the URL)
orderId	Yes	String	Merchant Order ID
orderNo	No	String	Platform Order ID (faster response)
sign	Yes	String	Signature

request

{
    "appId": 1054,
    "orderId": "M22222000028",
    "sign": "EmyJGm3ELzG4FsOd0Krs9ncbSjo4oTGuXWML+7djYla3+VAwd9wS17z38p/7U2ZAjroO04XrE7YXcB1o76Dtyipj3h3bJzs7FYma1QNkMUdt9hh7m8U6hMsMQX7vIWHtXNwz4pbTSC75+kQWXaCew7KoE6LXECdJU8AISgNgeki2TK9R0pCfshr0Z2SZBPeuT6OvIH5LdmqgdZhuqnffGU2qnXk4KMkO848e6/WALLBR+LE1wyKHfPnYVcuKSMVYxkvKyyIL5JIPEgW0o5bh4RCbaUn3NZtyYwrU1uQ3ZDFRThm9j6XAQP+LBlmq3nOePqBtp/VDVarRaV+7FbQg3A=="
}

response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M22222000028",
        "orderNo": "6023042811314347",
        "amount": "50.00",
        "actualAmount": "0.00",
        "fee": "0.00",
        "status": 1,
        "sign": "fP433ygWVDLVGxYkVnIJj7riGq0U3vyVX+MbBAImxfGLZkZcEAHVEoVYuULZSmXAAXKRSyd67WlDNm+24pougM54ofAoH4HMtCL2tfCoBReFyz3z02AGKkrKE2xWhSpWoqfQoBvzwuN5iGMMu0s9Q1YvqiwJ8WDVIENnmiIyD8qDJN7caHTW2US14/faG+69AvnuIgJ/nu7/jogOlgEYdZdVYU7gcRDE+d47KjlFGswQkJ/h/uzV7cWtUqrtOO7ZnZ3/z33Xx8awokX36QoYcPSWAU0h+Ij9O9402HNhm1eTbYcLU0uI/z8xCAtyAI/tTyiFijpiNlxUKQj+zKsILw=="
    }
}

Response Data Parameters

Parameter	Type	Description
orderId	String	Merchant Order ID (must be unique)
orderNo	String	Platform Order ID
amount	String	Transaction amount
actualAmount	String	Received amount
fee	String	Transaction fee
status	Integer	Status (0 Not Started, 1 Collecting, 2 Collection Success, 3 Collection Failed, -1 Exception Pending Confirmation)
payTime	String	Payment success time (available when status=2), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Failure reason (available when status=3)
sign	String	Signature

Payment Methods

payType	inBankCode	Description
PAYMENT_GATEWAY	PAPARA	Papara Wallet

Disbursement API

Disbursement Apply

Brief Description:

Create a disbursement order

URL: /try/pay/apply

Parameters

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend; must match the currency in the URL)
orderId	Yes	String	Merchant Order ID (must be unique, maximum length 48)
amount	Yes	String	Transaction amount (in local currency)
accountType	Yes	String	Account type: `BANK_ACCOUNT`, `EWALLET`
bankCode	Yes	String	Bank Code
identifyType	No	String	Required when `bankCode=PAPARA`: `PAPARA_NUMBER` (Papara ID) `PHONE` (registered Papara phone) `EMAIL` (registered Papara email) `TURKISH_ID` (registered Papara ID number)
accountNo	Yes	String	User account (IBAN if `BANK_ACCOUNT`)
name	Yes	String	Recipient name
phone	Yes	String	Valid phone number
email	Yes	String	Valid email
notifyUrl	No	String	Callback URL
subject	No	String	Payment remark (transaction title, product name, or payment reason)
body	No	String	Remark details
partnerUserId	Yes	String	Unique user identifier (e.g., userId), required for risk control. Must be valid; otherwise it may affect the transaction. Format: numbers, letters, or symbols `-~!@#$%&*()_`.
sign	Yes	String	Signature

request（accountType为BANK_ACCOUNT类型时）

{
    "appId": 1054,
    "orderId": "M100000450012",
    "amount": "500",
    "accountType": "BANK_ACCOUNT",
    "bankCode": "BDO",
    "accountNo": "09876543210",
    "ibanAccount": "09876543210",
    "name": "john doe",
    "phone": "09876543210",
    "email": "johndoe@cashfree.com",
    "subject": "iphone13",
    "body": "ProMotion technology with adaptive refresh rates up to 120Hz",
    "partnerUserId": "149597870",
    "sign": "I1PeK3eJOVsFFNowxVRqMXpeWm1lr/BcRpBi8WsW4wVo1+5CC3JsrFq/m/L2O69NzKHvtDWi4zia3DL3dPut0yMyUyqL91LNCSaeISbGsQPlhEsQpyTOryS/RKOfsrn2Xo37SCF/phAvndOk2jwwGwqM5xLz1ms9Ukl85wv27QFNrXIMxK2p18oe7MpMYrgf+xvEBE/VqCtKMtN9pO449wWwXzHWNPbZ76s4pAvKwRE9yXQDr7Iw14Dktcnl1FoLM4gWM/obkO+mz6SyAGDuXhVh/+OD/IGNiCyTCNq6ciQY28UnCFV6ZIP40gxsFhfBJKbK+Raw7y1Bh912ifYfug=="
}

response

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M100000450013",
        "orderNo": "3023062014149637",
        "sign": "LmhUnkw5j0pMiimsG8rKwdNNZGvXH5MpSmD6mdHZwq1SQwuK5BohmdEoqKB/jkMk28o3da4Cxh6Q+tW97+yTCemRrF+dMaHA73rpOeUuujKQl/UcFvJuMhfLBa2tp09L71NzoBqpPD6aXf37mYAz8E1HmERwFPpac5FVxIYanHG8cqmMLJYsVmHTSxWavgWU03ys9UczBePkBiR8sl2FSOhFABB0wAP28lswrV/ABS68IsLKtyd1fyI3GBfSbIK5nDEEnlE+EdElFdLs9taAxJImeVF1x4eT47+bkPJ2qS8z3K8QGzKLF3W+8SiRZGfSwDTsLKH+2Vycvy5auRl+ag=="
    }
}

Response Data Parameters

Parameter	Required	Type
orderId	String	Merchant Order ID (must be unique)
orderNo	String	Platform Order ID
sign	String	Signature

Disbursement Query

Brief Description:

Query a disbursement order

URL: /try/pay/query

Parameters

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend; must match the currency in the URL)
orderId	Yes	String	Merchant Order ID
orderNo	No	String	Platform Order ID (faster response)
sign	Yes	String	Signature

request

{
    "appId": 1000,
    "orderId": "M1234567111",
    "orderNo": "3022111516571436",
    "sign": "ZxkVZL+GAyv0VhvWn4IvuYahTzxgQuthkuV2ONWiqIfIDb2avvHlFOUJVzqZi1q8CPHXZm1ltanRTRVTxfsuftLvGeDioUHglWt46/RU6c1OPznpLGsZ35Q3n5tW2y1EnOsxPynXBFLuDQy+aZ3l9u6AQ30T0zQexMGT+IxuFkmUp02g/6juaHa5ZgNMv7lN67ixIp162wrM7OJuaOif872QijSceRdZhzaMGImAwB0D4MosRV4WMBOKkwgPdmS7GuZN66YUidXk3wTGqX3MYRw6M0kj4eNegSUwPXvp4q4p0KO8Y3xUMld54GY2ApX3WN3CBtC/vpJqEszjGBbbGg=="
}

response — Order Failed

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M1234567111",
        "orderNo": "3022111516571436",
        "amount": "100000.00",
        "fee": "0.00",
        "status": 3,
        "errorMsg": "Đơn hàng không tồn tại",
        "sign": "KKuvCl0SuNANJs+l2ogDaJm8pmV+Hi+Xa7q27vJ6D1Ehs4aOp13kRbITfJAhczh3T81BE9qwHeJaYwf+r0EypKM9TL6pMwfG8Az4gRy1D57wiUaVjl2PWcvbEqrn1hL0b+btkjvAM9I+CcSv+wuOW3/uku17Ws3FhgJLj9sFsQUBAPjDO+758VnwBytCOLBmljLBXyKgNgpmFQ1/DNkqWl0UNzyLK45Zw3yf5NiwhEFbvW0jlOWlfu/ql4hluISUQG573jEoFCBEnQLb2tQoRZj1QYNRCXPf5lbej0vzqbEwvR9h+ZOf255t1MocJkdIe463DTV5U3KZdVT87HMagw=="
    }
}

response — Order Successful

{
    "status": "1",
    "error": "00000000",
    "msg": "",
    "data": {
        "orderId": "M1234567112",
        "orderNo": "3022111517401574",
        "amount": "100000.00",
        "fee": "1003.00",
        "status": 2,
        "payTime": "2024-03-01 23:59:59",
        "sign": "khPtOmGq+cpKX0HFAI/lbP0dx4oVyNAnL5oLsdmhDJdASlQm0yg5I3o+MhImYggEsL6c2bo5fP29t54OZFqSdQDfIuNDvGbAMAr4mRBxc0hoHLkBLyyagfVPBLyQA1JY8XV3ZL4ySzQ3ZQnMCfrh2K39ueUuz6HpZ03Hj0KYijVRCXAZaio/L5jfLBT12QXmvIfAHa8s/k9flhK05ENHPep3zjj/MZGOEaX7jkEJLfjK0duypDCa61BRQjM+oePOdVsgleIl1Yf98UAxMDZ/A3912KFHEb+/jvmdnulNbiJFyuT1fEe+j2teUgw3vFsZAtwNWAgxhC7UO+N0Q5z4EA=="
    }
}

Response Data Parameters

Parameter	Type	Description
orderId	String	Merchant Order ID (must be unique)
orderNo	String	Platform Order ID
amount	String	Transaction Amount
fee	String	Service Fee
status	Integer	Order Status (0: Not Started, 1: Processing, 2: Disbursement Success [final], 3: Disbursement Failed [final], -1: Exception Pending Confirmation)
payTime	String	Payment Success Time (only present when status = 2), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Error Message (only present when status = 3)
sign	String	Signature

Bank Code

bankCode	bankName
TCMB	T.C.MERKEZ BANKASI A.Ş.
KUVEYT_TURK	KUVEYT TÜRK KATILIM BANKASI A.Ş.
ILB	İLLER BANKASI
ZIRAAT_BANK	T.C. ZİRAAT BANKASI A.Ş.
HALK_BANK	T. HALK BANKASI A.Ş.
TSKB	T.SINAİ KALK. BANKASI A.S.
VAKIF_BANK	T. VAKIFLAR BANKASI
TURK_EXIMB	T.IHRACAT KREDI BANKASI A.S
KALKINMA_BANK	T.KALKINMA BANKASI A.S.
BAYINDIR_BANK	BAYINDIRBANK A.S.
EKONOMI_BANK	T.EKONOMİ BANKASI A.S.
AKB	AKBANK T.A.Ş
SEKER_BANK	ŞEKERBANK T.A.Ş
GARANTI_BANK	T. GARANTİ BANKASI A.Ş.
ISB	T. İŞ BANKASI A.Ş.
YAPI_KREDI	YAPI ve KREDİ BANKASI A.Ş.
TURK_TICARET	T.DIŞ TICARET_BANKASI A.S.
ROMA_BANK	BANCA DI ROMA S.P.A.
ABN_AMRO	ABN AMRO BANK N.V.
ATB	ARAP TÜRK BANKASI A.S.
CITI_BANK	CITIBANK A.Ş.
KOC_BANK	KOÇBANK A.S
TURKISH_BANK	TURKISH BANK A.Ş.
JPMORGAN_BANK	JP MORGAN CHASE BANK NA MERK C
ING_BANK	ING BANK A.Ş.
ADA_BANK	ADABANK A.S.
MING_BANK	MNG BANK A.S.
FINANS_BANK	FİNANS BANK A.Ş.
DEUTSCHE_BANK	DEUTSCHE BANK A.S.
CALYON_BANK	CALYON BANK T.A.S
HSBC_BANK	HSBC BANK A.Ş
ALTERNATIF_BANK	ALTERNATİFBANK A.S.
TEKFEN_BANK	TEKFENBANK A.S.
DENIZ_BANK	DENİZBANK A.Ş.
ANADOLU_BANK	ANADOLUBANK A.Ş.
DILER_BANK	DİLER YATIRIM BANKASI A.S.
GSD_BANK	GSD YATIRIM BANKASI A.S.
NUROL_BANK	NUROL YATIRIM BANKASI A.S.
CALIK_BANK	ÇALIK YATIRIM BANKASI A.S
FIBA_BANK	FIBABANKA A.Ş
TURKLAND_BANK	TURKLAND BANK A.Ş.
URGAN_BANK	URGAN BANK A.Ş.
AKTIF_BANK	AKTİF YATIRIM BANKASI A.Ş
ODEA_BANK	ODEA BANK A.Ş.
ALBARAKA_TURK	ALBARAKA TÜRK KATILIM BANKASI A.Ş.
ASYA_BANK	ASYA KATILIM BANKASI A.Ş.
PTT	PTT
QNB	QNB Finansbank
TURKIYE_FINANS	TÜRKİYE FİNANS KATILIM BANKASI A.Ş.
ININAL	Ininal