Middle East Payment API

About 1279 wordsAbout 4 min

Warning

Before reading this API documentation, be sure to review API Description Guide

Collection API

Collection Request

Brief Description:

Create a collection order

URL:

Saudi Arabia: /sar/collect/apply
Note: appId SAR, amount SAR, settlement SAR

Kuwait: /kwd/collect/apply
Note: appId KWD, amount KWD, settlement KWD

Bahrain: /bhd/collect/apply
Note: appId BHD, amount BHD, settlement BHD

UAE: /aed/collect/apply
Note: appId AED, amount AED, settlement AED

Oman: /omr/collect/apply
Note: appId OMR, amount OMR, settlement OMR

Qatar: /qar/collect/apply
Note: appId QAR, amount QAR, settlement QAR

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, must pass the corresponding business ID based on the currency in the URL)
orderId	Yes	String	Merchant order number (must be unique, max length 48)
name	Yes	String	Payer’s name, used for risk control
phone	Yes	String	Valid phone number (format reference: Phone Number Format)
email	Yes	String	Valid email address
amount	Yes	String	Transaction amount (unit: local currency, up to 2 decimals; no punctuation symbols such as “,”). Use ≤10 SAR in test env.
currency	No	String	Currency (USD, local currency)
payType	Yes	String	Transaction type
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
goodsName	Yes	String	Product name
goodsQuantity	Yes	String	Product quantity
goodsPrice	Yes	String	Product price
goodsSku	Yes	String	Product unique identifier
goodsAvatar	Yes	String	Product image (https://)
platform	Yes	String	Platform name
subject	No	String	Payment note
body	No	String	Additional description
partnerUserId	Yes	String	Unique user identifier (e.g. userId), required for risk control. Must be valid. Format: digits, letters, or symbols -~!@#$%&*()_.
sign	Yes	String	Signature

request

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

response

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

Return Data Parameters Description

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

Collection Query

Brief Description:

Create a collection order
When “payType = BANK_TRANSFER”, the orderNo is returned synchronously and can be queried directly
For other payment methods, after asynchronous notification, use orderNo for second confirmation

URL:

Saudi Arabia: /sar/collect/query

Kuwait: /kwd/collect/query

Bahrain: /bhd/collect/query

UAE: /aed/collect/query

Oman: /omr/collect/query

Qatar: /qar/collect/query

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in the URL)
orderId	Yes	String	Merchant Order Number
orderNo	No	String	Platform Order Number (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=="
  }
}

Return Data Parameters Description

Parameter	Type	Description
orderId	String	Merchant Order Number (must be unique)
orderNo	String	Platform Order Number
amount	String	Transaction Amount
actualAmount	String	Received Amount
fee	String	Fee
status	Integer	Status (0 Not Started, 1 In Progress, 2 Success (final), 3 Failed (final), -1 Exception Pending Confirmation)
payTime	String	Payment Success Time (available when status=2) (Saudi Time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Failure Reason (available when status=3)
sign	String	Signature

Payment Methods

Region	Payment Type	Institution	payType (Technical)	inBankCode (Technical)	Supported Currency
Saudi Arabia	Debit cards	MADA	PAYMENT_GATEWAY	CARD	SAR
	Local credit cards	VISA/MC	PAYMENT_GATEWAY	CARD	SAR
	E-wallets	STCPAY	PAYMENT_GATEWAY	STCPAY	SAR
	E-wallets	Apple Pay	EWALLET	APPLE_PAY	SAR
UAE	Local credit cards	VISA/MC	PAYMENT_GATEWAY	CARD	AED
	E-wallets	Apple Pay	EWALLET	APPLE_PAY	AED
Kuwait	Debit cards	KNET	PAYMENT_GATEWAY	CARD	KWD
	Local credit cards	VISA/MC	PAYMENT_GATEWAY	CARD	KWD
	E-wallets	Apple Pay	EWALLET	APPLE_PAY	KWD
Qatar	Debit cards	NAPS	PAYMENT_GATEWAY	CARD	QAR
	Local credit cards	VISA/MC	PAYMENT_GATEWAY	CARD	QAR
	E-wallets	Apple Pay	EWALLET	APPLE_PAY	QAR
Oman	Local credit cards	VISA/MC	PAYMENT_GATEWAY	CARD	OMR
	E-wallets	Apple Pay	EWALLET	APPLE_PAY	OMR
Bahrain	Debit cards	BENEFIT	PAYMENT_GATEWAY	CARD	BHD
	Local credit cards	VISA/MC	PAYMENT_GATEWAY	CARD	BHD
	E-wallets	Apple Pay	EWALLET	APPLE_PAY	BHD

Disbursement API

Disbursement Apply

Brief Description:

Create a disbursement order

URL:

Saudi Arabia: /sar/pay/apply

Kuwait: /kwd/pay/apply

UAE: /aed/pay/apply

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in the URL)
orderId	Yes	String	Merchant Order Number (must be unique, max length 48)
amount	Yes	String	Transaction Amount (local currency, accurate to two decimals; no punctuation such as “,” allowed). For testing, please use ≤10 SAR
accountType	Yes	String	Account Type: EWALLET (E-wallet), BANK_ACCOUNT (Bank)
bankCode	Yes	String	Bank code or wallet code, see Wallet Codes and Bank Codes
accountNo	No	String	User account number (required if accountType = EWALLET)
ibanAccount	No	String	IBAN account number (required if accountType = BANK_ACCOUNT)
name	Yes	String	Beneficiary Name (Format: English letters, case-insensitive, spaces allowed, 1-30 chars, "firstName middleName lastName"; middleName optional; supports characters '.-')
phone	Yes	String	Valid phone number
email	Yes	String	Valid email
notifyUrl	No	String	Callback URL
subject	No	String	Payment Note (transaction title, product name, or payment reason)
body	No	String	Additional Remarks
partnerUserId	Yes	String	Unique user identifier (e.g., userId). Must be valid for risk control; allowed format: digits, letters, or symbols -~!@#$%&*()_
sign	Yes	String	Signature

request（When 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=="
  }
}

Return Data Parameters Description

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

Disbursement Query

Brief Description:

Query disbursement order

URL:

Saudi Arabia: /sar/pay/query

Kuwait: /kwd/pay/query

UAE: /aed/pay/query

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must match the currency in the URL)
orderId	Yes	String	Merchant Order Number
orderNo	No	String	Platform Order Number (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=="
  }
}

Return Data Parameters Description

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

Wallet Codes and Bank Codes

Wallet Codes (EWALLET)

bankCode	bankName
STCPAY	StcPay Wallet (only supported for SAR)

Bank Codes (BANK_ACCOUNT)

Supported Banks List for Middle East Payments