Create Withdrawal Order (Saudi Arabia)
API for creating Saudi Riyal (SAR) withdrawal orders, supporting IBAN bank transfers and STC Pay / urpay / Barq wallets.
Request Information
- Request URL:
/gateway/api/v2/payouts - Method:
POST - Content-Type:
application/json;charset=utf-8
Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| platform_id | Yes | String(6) | Merchant ID |
| service_id | Yes | String(7) | Service ID, fixed value SVC0004 |
| payout_cl_id | Yes | String(64) | Merchant Order ID |
| amount | Yes | Integer(10) | Amount (in halalas) |
| notify_url | No | String(256) | Callback URL for transaction results |
| bank_name | Yes | String(16) | Bank/wallet code, the English bank name is also accepted, Bank List |
| name | Yes | String(64) | Beneficiary name |
| number | Yes | String(64) | Beneficiary account: the IBAN for bank transfers, the wallet account for wallets |
| iban | Conditional | String(34) | Saudi IBAN (starting with SA, 24 characters). Required for bank transfers; when omitted, number is validated as the IBAN |
| phone_number | Conditional | String(11) | Beneficiary mobile number (e.g. 0512345678). Required for bank transfers; for wallets, number is used when omitted |
| currency | Yes | String(3) | Fixed value: sar |
| request_time | Yes | Integer(10) | Request time (seconds) |
| sign_type | No | String(16) | Signature type, fixed value HMAC-SHA256 |
| sign | Yes | String(32|64) | Order Signature |
"Conditional" means the requirement depends on the payout method; see the remarks below.
Service ID
SVC0004Bank Card Withdrawal (bank_namedetermines bank transfer or wallet)
Response Example
{
"error_code": "0000",
"data": { "payout_id": "POT00000001" }
}
Remarks
Important
In case of a timeout or HTTP 500 error, rely on the order query interface for the status; do not treat it as a failed order.
- Transaction amount is in Saudi Riyal (halalas)
- Bank transfer: pass the bank code or English bank name in
bank_name,ibanmust be a valid Saudi IBAN (SA+ 22 characters), andphone_numberis required - Wallets (STC Pay / urpay / Barq): pass
STC,URPAYorBARQinbank_name, and the wallet account (the mobile number) innumber - If the beneficiary details fail validation, the error is returned at creation time and no order is created
- "0000" only means the API call succeeded; call the query interface to confirm the result
- Per-transaction limits are subject to commercial confirmation