Overview
Single payment collection enables you to initiate and post normal transfers from your anb account to any other bank. The API supports anb to anb transfer, anb to local banks “via SARIE network” and international banks “via SWIFT network”. Also, the collection provides a couple of other services to inquire and manage previously initiated payments.
| Channel | Description |
|---|---|
| ANB | anb to anb |
| SWIFT | International payments through SWIFT network |
| SARIE | Local payments through SARIE RTGS network |
| IPS |
Instant local transfer via the new SARIE network (STL IBAN only) |
Single payment service accepts only JSON format.
Prerequisites
To use the Single Payment service, you need to do the following:
- Register/Login to the anb Developer Portal.
- Create an app.
- You should now have a client id and secret associated with your app.
- Get an access token from our auth service using your client id and secret.
Posting Single Payment Service
JSON format
| Field | Description | Required | Format | Min Length | Max Length | Note |
|---|---|---|---|---|---|---|
| Sequence number | A unique number used to avoid duplication. The sequence number should be unique | Yes | Number string | 1 | 16 | Appears in “narrative 3” or “tag 86” in intra-day and end-of-day statements |
| Value date | Date of payment execution. | Yes | YYMMDD (String) | 6 | 6 | 220102 (2nd Jan, 2022). 210420 (20th Apr, 2021) |
| Currency | Currency of the payment. In case of local transfers, it must be SAR | Yes | Enum (As per the list of currencies defined below in the appendices) | 3 | 3 | SAR |
| Amount | Amount to be paid | Yes | Number string | > 0 | 10 | |
| Fee included | If true, payment fee will be deducted from the original amount sent | No. Default (if not sent) is false | Boolean (true, false) | |||
| Ordering party | Ordering party name | Yes | String | 2 | 35 |
Name of the sender Must not be empty. Must not contain Numbers & Characters Must be b/w 2 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Ordering party address 1 | Ordering party address 1 | Yes | String | 2 | 35 |
Must not be empty. Must be b/w 2 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Ordering party address 2 | Ordering party address 2 | Yes | String | 2 | 35 |
Must not be empty. Must be b/w 2 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Ordering party address 3 | Ordering party address 3 | Yes | String | 2 | 35 |
Must not be empty. Must be b/w 2 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Debit account | anb account to be debited. In case of local transfers, the currency of the account must be SAR | Yes | String | 16 | 24 | Accepts both normal anb account number or IBAN |
| Channel | As per channels defined above. When omitted, channel will be derived from destination bank BIC field. | Yes | Enum string [ANB, SARIE, IPS, SWIFT] | In case not sent and the destination bank BIC belongs to a local bank, the channel will be defaulted to SARIE regardless of the amount. | ||
| Destination bank BIC | Destination account BIC code. | Yes | String | 8 | 11 | For ANB transfers, “ARNBSARI” code must be sent. |
| Credit account | Credit account number. In case of local transfers, it must be IBAN | Yes | String | 16 | 35 | |
| Beneficiary Name | Beneficiary name | Yes | String | 2 | 35 |
Must not be empty. Must not contain Numbers & Characters Must be b/w 5 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Beneficiary address 1 | Beneficiary address 1 | Yes | String | 2 | 35 |
Must not be empty Must be b/w 2 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Beneficiary address 2 | Beneficiary address 2 | Yes | String | 2 | 35 |
Must not be empty. Must be b/w 2 to 35 alphabets. Must not exceed maximum limit of 35 Tag is removed. |
| Narrative | Narrative to be sent with payment | No | String | 1 | 35 | Appears in “narrative 2” or “tag 61” in intra-day and end-of-day statements |
| Transaction comment | Internal comment that can be fetched from GET payment API | No | String | 1 | 105 | |
| Purpose of transfer | As per the purpose of transfer codes defined below in the appendices | Yes | Enum string |
Sequence number must be unique to assure idempotency. In case a duplicate sequence number is sent from the same B2B partner, the payment request will be rejected and the original payment UUID will be provided in the response.
| Channel | Cutoff |
|---|---|
| ANB | Accepts payment 24/7 |
| IPS | Accepts payment 24/7 |
| SWIFT | Accepts payment 24/7 |
| SARIE (RTGS) | Accepts payment only during weekdays (Fridays and Saturdays excluded). The cutoff time is 15:58. Note that this time can change depending on the availability of RTGS network |
Queued Payments
Payment requests with a future value date will be queued at B2B system. In case of SARIE and SWIFT, payments will be queued if the value date is two days ahead of today’s date, and they will be released a day before their value date. anb payments, on the other hand, will be queued if the value date is one day ahead of today’s date and they will be processed and released on the same day of value date. IPS doesn’t support queuing and its payments will always be processed immediately.
A payment can be canceled only if it is queued. Once released, it can no longer be canceled.
It is important to provide accurate ordering party and beneficiary details to avoid any rejection from the destination bank.
Payment Processing In Depth
Apart from IPS, other channels’ payments will be processed asynchronously. Once B2B system receives a payment request, it will validate its parameters against a couple of static validations (format, length, data types .. etc). If it is not valid, the payment will be rejected. If valid, the payment will be initiated in B2B system, a unique UUID number will be generated and a response will be sent back to the client. Then, dynamic validations will be running to assure the validity of other parameters. Once validated, the payment will be sent to core systems to post the payment and mark it as either successful or failed.
| Status | Description |
|---|---|
| INITIATED | Payment's schema is valid and is ready to be processed |
| QUEUED | Payment's value date is future, so it is currently queued |
| CANCELED | Queued payments are canceled |
| PENDING | Payment is pending processing |
| FAILED | Payment is failed |
| PROCESSED | SARIE/SWIFT payments are now completed IPS payments are under processing. |
| PAID | anb/IPS payments are now completed |
| RETURNED | Local payment is returned from beneficiary banks |
Due to the nature of the way payments are processed in B2B system, a couple of useful webhooks will be provided as part of Notification product (link) to notify the customer about the status of the payment without the need to manually inquire about it.
As per the sequence diagram, the payment cycle will finish only after posting it to anb core systems. Initiating the payment doesn't mean the payment will always be sucessful as it might fail to meet some dynamic conditions and validations.
Payment Inquiry Service
You can inquire about the status of previously posted payments using several parameters. You may inquire using the unique UUID, sequence number, or transaction reference number.
It is important to always check the payment's status again after 5 min to get the final status.
| Field | Description | Always |
|---|---|---|
| Id | Unique UUID of the payment to be used to inquire about payment status | Yes |
| Transaction reference number | Unique transaction reference number generated by B2B system | Yes |
| External reference number | UTI Reference Number (in case of local payment) | No |
| UETR number | UETR Number for SWIFT payments | No |
| Sequence number | The sequence number submitted in the request | Yes |
| Exchange rate | Exchange rate used to post the transfer | Yes |
| Status | Payment status | Yes |
| Reason of failure | Failure details (returned in case payment status is FAILED) | No |
| Created at | Payment creation date (ISO format) | Yes |
| Updated at | Payment last update date (ISO format) | Yes |
List of Payments Service
You can inquire about multiple payments at once based on different filters. The service supports looking for single payments based on a certain status and between specific periods.
| Field | Description | Always |
|---|---|---|
| data | An array list of Payment objects | Yes |
| meta | Meta information to help with pagination | Yes |
| Field | Description | Always |
|---|---|---|
| id | Unique UUID of the payment to be used to inquire about payment status | Yes |
| Transaction reference number | Unique transaction reference number generated by B2B system | Yes |
| External reference number | UTI Reference Number (in case of local payment) | No |
| UETR number | UETR Number for SWIFT payments | No |
| Sequence number | The sequence number submitted in the request | Yes |
| status | Payment status | Yes |
| Reason of failure | Failure details (returned in case payment status is FAILED) | No |
| Created at | Payment creation date (ISO format) | Yes |
| Updated at | Payment last update date (ISO format) | Yes |
| Field | Description | Always |
|---|---|---|
| Page | Current page | Yes |
| Take | Number of data objects to be returned in a single response | Yes |
| Item count | Number of all objects available in all pages | Yes |
| Page count | Number of available pages | Yes |
| Has previous page | Boolean to indicate if there is a previous page | Yes |
| Has next page | Boolean to indicate if there is a next page | Yes |
Cancel Payment Service
This service can be used to cancel queued payments only. You need to provide the unique payment UUID.
Channel Service
This service can be used to determine which channel should be used when sending new local transfers (IPS or SARIE). The service will ask for the desired value date along with the amount and destination bank BIC
IPS channel requires the destination bank to be active and ready to receive payments. Upon receiving any new IPS payment, anb will check the current active banks. In case the desired destination bank is not currently active, the payment will be rejected immediately.
Appendix A: Purpose of Transfer Codes
| Code | Description | Arabic Description |
|---|---|---|
| 20 | Bills or rent | فواتير أو ايجار |
| 21 | Expenses services | مصاريف أو خدمات |
| 22 | Purchase assets | شراء بضائع أو أصول |
| 23 | Saving investment | مدخرات واستثمارات |
| 24 | Government dues | دفع مستحقات حكومية و ضرائب |
| 25 | Money exchange | مدفوعات لصرف عملات |
| 26 | Credit card loan | مدفوعات تمويل أو بطاقات ائتمانية |
| 27 | Gift or reward | هدايا أو مكافئات |
| 28 | Personal loan assistance | سلفة أو قرض شخصي |
| 29 | Investment transaction | تحويلات مرتبطة بالاستثمار |
| 30 | Family assistance | دعم ومساعدات عائلية |
| 31 | Donation | تبرعات |
| 32 | Payroll benefits | أجور ورواتب وحوافز ومكافئات |
| 33 | Online purchase | شراء من مواقع الكترونية أو استيراد |
| 34 | Hajj and Umra | مصاريف حج وعمرة |
| 35 | Dividend payment | دفع أرباح |
| 36 | Government payment | مدفوعات حكومية |
| 37 | Investment house | مدفوعات لشركات استثمارية |
| 38 | Payment to merchant | مدفوعات للتجار |
| 39 | Own account transfer | حوالات لحسابي |
Appendix B: Local Bank BICs
| BIC | Institution Name (English) | Institution Name (Arabic) | Bank Clearing Code |
|---|---|---|---|
| AAALSARI | SAUDI HOLLANDI BANK | بنك الأول | 50 |
| BSFRSARI | BANQUE SAUDI FRANSI | البنك السعودي الفرنسي | 55 |
| INMASARI | AL INMA BANK | بنك الإنماء | 05 |
| ARNBSARI | ARAB NATIONAL BANK | البنك العربي الوطني | 30 |
| RJHISARI | AL RAJHI BANK | مصرف الراجحي | 80 |
| BJAZSAJE | BANK AL-JAZIRA | بنك الجزيرة | 60 |
| BMUSSARI | BANKMUSCAT | بنك مسقط | 76 |
| EBILSARI | EMIRATES BANK INTERNATIONAL PJSC | بنك الإمارات الدولي | 95 |
| FABMSARI | FIRST ABU DHABI BANK | بنك أبوظبي الأول | 73 |
| CHASSARI | JPMORGAN CHASE BANK, N.A. RIYADH | بنك تشيز | 86 |
| BNPASARI | BNP PARIBAS SAUDI ARABIA | بي ان بي ارابيا | 85 |
| GULFSARI | GULF INTERNATIONAL BANK B.S.C., RIYADH | بنك الخليج الدولي | 90 |
| ALBISARI | BANK AL BILAD | بنك البلاد | 15 |
| NBOBSARI | NATIONAL BANK OF BAHRAIN | بنك البحرين الوطني | 71 |
| NBOKSAJE | NATIONAL BANK OF KUWAIT | بنك الكويت الوطني | 75 |
| NCBKSAJE | SAUDI NATIONAL BANK | البنك الأهلي السعودي | 10 |
| RIBLSARI | RIYAD BANK | بنك الرياض | 20 |
| SABBSARI | SAUDI BRITISH BANK | البنك السعودي البريطاني | 45 |
| SAMASARI | SAUDI ARABIAN MONETARY AGENCY | البنك المركزي السعودي | 01 |
| SIBCSARI | SAUDI INVESTMENT BANK | البنك السعودي للإستثمار | 65 |
| STCJSARI | STC Bank | بنك اس تي سي | 78 |
| DBAKSARI | D360 Bank | دال ثلاثمائة وستون | 36 |
| SCBLSAR2 | Standard chartered bank | بنك ستاندر شارتر | 91 |
| QNBASARI | Qatar National Bank | بنك قطر الوطني | 72 |
| NBIQSARI | National Bank of Iraq | بنك العراق الوطني | 79 |
| DEUTSARI | Deutsche Bank | بنك دويتشه | 81 |
| TCZBSARI | T.C.ZIRAAT BANKASI A.S. | بنك زراعات | 84 |
| BOTKSARI | MUFG Bank | بنك إم يو أف جي | 88 |
| CRESSARY | Credit Suisse AG | كريدي سويس | 89 |
| VIIOSARI | VISION BANK | بنك فيجن | 93 |
| BSHRSARI | Sohar International Bank | بنك صحار الدولي | 92 |
Appendix C: Error Codes
| Code | Description |
|---|---|
| E650001 | Duplicate payment |
| E650002 | Payment not found |
| E650003 | Cancel payment not allowed |
| E650006 | Payment not found |
| E650011 | Payment validation |
| E650012 | Amount zero |
| E650014 | Amount round |
| E650015 | Amount NAN |
| E650016 | Channel invalid |
| E650017 | Only SAR |
| E650018 | IPS max amount |
| E650019 | IBAN invalid |
| E650020 | Bic invalid |
| E650021 | Sarie not working day |
| E650022 | Sarie cut off |
| E650023 | Credit currency not match |
| E650024 | Currency conversion invalid |
| E650025 | Value date invalid |
| E650026 | Past value date |
| E650027 | Future value date |
| E650028 | Credit debit match |
| E650029 | Credit invalid |
| E650030 | POT invalid |
| E650032 | IPS bank not found |