Overview
Statement service provides a couple of useful inquiry services about your anb account. These services expand to include balance inquiry, general statement, and end-of-day statements. General statement service supports MT942 and JSON formats. End-of-day (EOD) statements will be provided in MT940 format only.
Prerequisites
To use the Account Statement 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.
Balance Service
This service can be used to get the currency and the cleared balance of an anb account.
| Field | Description |
|---|---|
| Account number | anb account number |
| Field | Description |
|---|---|
| Account number | anb account number |
| Currency | The currency of the account (ISO format) |
| Cleared balance | The cleared balance of the account |
General Statement Service
This service can be used to get the account's statement between two periods. Additionally, the account's opening and closing balance between these two periods will be provided.
| Field | Description | Required | Note |
|---|---|---|---|
| Account number | anb account number | Yes | |
| From date | From date (YYYY-MM-DD) | Yes | Pass today date to inquire about intra-day statement |
| To date | To date (YYYY-MM-DD) | Yes | Pass today date to inquire about intra-day statement |
| Max | Maximum records per page to be returned in the response. | No. Default: 20. |
Maximum accepted value: 20 |
| Type | The format to be returned in the response |
No. MT942. |
Enum [JSON, MT942] |
| Offset | Used for pagination | No |
| Field | Description | Always | Note |
|---|---|---|---|
| Account number | anb account number | Yes | |
| From date | From date (YYYY-MM-DD) | Yes | |
| To date | To date (YYYY-MM-DD) | Yes | |
| Number of records | Number of transactions returned in the page | Yes | |
| Completed | Boolean flag to mark if statement between the passed two periods is complete | Yes | Enum [JSON, MT940] |
| Offset | Offset to be used for pagination | No | Re-send it in the next request to fetch the next page of transactions |
| Brought forward balance | Amount and currency code for brought forward balance | No | |
| Opening cleared balance | Amount for brought opening clearance balance | No | |
| Closing balance | Amount for brought closing clearance balance of the page | No | Note that this value doesn't represent the closing balance of the account on "to-date" passed in the request. It represents the closing balance on that page. In case "completed" flag is marked as true, then it does reflect the real closing balance. |
| Statement | Data of statement (either in MT942 or JSON format) | No | |
| Statement/Data | Data of statement in string for MT942 format | No | Returned only in case the format is MT942 |
| Statement/Transactions | Array of statements for JSON format | No | Returned only in case the format is JSON |
| Field | Description | Always | Versions |
|---|---|---|---|
| Unique Id | Transaction unique ID | No | All |
| Post date | Transaction posting date | No | All |
| Posting time | Transaction posting time | No | All |
| Value date | Transaction value date | No | All |
| Type | Transaction type. Refer to appendix A | No | All |
| Amount | Amount and currency code for transaction amount | No | All |
| Narrative | Transaction narratives | No | All |
| Reference number | Transaction reference number | No | All |
| Counter | Transaction counter | No | All |
| Statement flag | Transaction statement flag | No | All |
| Source account number | Source account number | No | All |
| POI number | Personnel Office Identifier (National Id, CR number, etc ..) | No | All |
| Particular transaction type | Transaction part type (CREDIT, DEBIT) | No | All |
| Particular transaction serial number | Transaction serial number | No | All |
| Running balance | Amount and currency code for running balance | No | All |
| Ordering Party | Originator Name | No | V2 |
| Beneficiary Name | Beneficiary Name | No | V2 |
| Bank | Originator Bank | No | V2 |
| Iban | Beneficiary/Originator IBAN | No | V2 |
| SAMA narrative | SAMA narrative | No | All |
| Network | Network 01: ANB 02: Local (SARIE or IPS) 03: SWIFT |
No | All |
| Channel | Channel (ANB-SARIE-IPS-SWIFT) | No | V2 |
| Network account number | Source account number in case network is not ANB | No | All |
| Particulars code | Transaction particulars code | No | All |
| Category | Transaction category | No | All |
| Subcategory | Transaction sub-category | No | All |
| Tag | Description | Sample |
|---|---|---|
| :20: | Statement reference number | :20:RPMS-210530144352 |
| :25: | anb account number | :25:0108050053560021 |
| :28C: | Statement sequence number | :28C:150/001 |
| :60F: | Opening balance [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:60F:C210101SAR1000,50 The opening balance on 2021-01-01 is 1000.50 SAR :60F:D210223USD1000,50 The opening balance on 2021-02-23 is -1000.50 USD |
| :61: | Statement line [YYMMDD(value date)][MMDD(posting date)][1!a(C for credit, D for debit)][15d (amount)][1!a3!c(4-char transaction code in appendix B)][35!a(narrative 2)]//[35!a(narrative 1)] |
:61:2101020101D910,00NTRF21003551//anb transfer A debit transfer with value date 2021-01-02 posted on 2021-01-01 with narrative 1 (anb transfer) and narrative 2 (21003551) :61:2102030101C110,15NTRN123456//Credit transfer A credit fee transfer with value date 2021-02-03 posted on 2021-01-01 with narrative 1 (Credit transfer) and narrative 2 (123456) |
| :86: | Statement enrichment line | :86:SDC123456 |
| :62F: | Closing balance [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:62F:D210528SAR97500,00 the closing balance on 2021-05-28 is 97500,00 SAR |
| Tag | Description | Sample |
|---|---|---|
| :20: | Statement reference number | :20:RPMS-210530144352 |
| :25: | anb account number | :25:0108050053560021 |
| :28C: | Statement sequence number | :28C:150/001 |
| :60F: | Opening balance [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:60F:C210101SAR1000,50 The opening balance on 2021-01-01 is 1000.50 SAR :60F:D210223USD1000,50 The opening balance on 2021-02-23 is -1000.50 USD |
| :61: | Statement line [YYMMDD(value date)][MMDD(posting date)][1!a(C for credit, D for debit)][15d (amount)][1!a3!c(4-char transaction code in appendix B)][35!a(narrative 2)]//[35!a(narrative 1)] |
:61:2101020101D910,00NTRF21003551//anb transfer A debit transfer with value date 2021-01-02 posted on 2021-01-01 with narrative 1 (anb transfer) and narrative 2 (21003551) :61:2102030101C110,15NTRN123456//Credit transfer A credit fee transfer with value date 2021-02-03 posted on 2021-01-01 with narrative 1 (Credit transfer) and narrative 2 (123456) |
| :86: |
Statement enrichment line |
:86:/ORDP/Khaled Saeed |
| :62F: | Closing balance [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:62F:D210528SAR97500,00 the closing balance on 2021-05-28 is 97500,00 SAR |
Statement Pagination In Depth
The response of the general statement service returns an offset to be used to fetch the next page. In case offset is not sent, the service will always return the first 20 transactions posted between from-date and to-date specified in the request. This is because account transactions will always be sorted in ascending order.
Scenario 1: From-date and to-date are before today date
The first request sent from the customer will have no offset. The service will return the first 20 transactions along with the offset and completion flag. If the list is not complete, you need to send another request with the same from-date and to-date with the offset provided in the last response. The service will return the following 20 transactions. Repeat that until completion flag is marked as true.
Scenario 2: From-date and to-date are today date
The first request sent from the customer will have no offset, and the service will return the first 20 transactions along with the offset and completion flag. If the list is not complete, follow the same procedure mentioned in scenario 1. If the list is complete, store the returned offset. Now, to inquire about new transactions posted on today-date, use the stored offset to fetch them. In case there are no new transactions, the service will respond with "no record exists".
Since "offset" is a query parameter and contains some spaces, make sure to encode the URL before conducting the request.
End of Day Statement Service
End-of-day (EOD) statement service provides more details about all transactions occurred on a certain account on a particular date. Also, it provides the opening and closing balance of the account on that date. EOD statement supports MT940 standard format as of now. As part of Notification service, EOD statements can be pushed to your system once generated.
In case your ERP system supports English characters only, you need to inform anb to configure that for your accounts. This is because some EOD statements' content might contain Arabic characters (narrative 1, 2, or 3).
| Tag | Description | Sample |
|---|---|---|
| :20: | Statement reference number | :20:RPMS-210530144352 |
| :25: | anb account number | :25:0108050053560021 |
| :28C: | Statement sequence number | :28C:150/001 |
| :60F: | Opening balance [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:60F:C210101SAR1000,50 The opening balance on 2021-01-01 is 1000.50 SAR :60F:D210223USD1000,50 The opening balance on 2021-02-23 is -1000.50 USD |
| :61: | Statement line [YYMMDD(value date)][MMDD(posting date)][1!a(C for credit, D for debit)][15d (amount)][1!a3!c(4-char transaction code in appendix B)][35!a(narrative 2)]//[35!a(narrative 1)] |
:61:2101020101D910,00NTRF21003551//anb transfer A debit transfer with value date 2021-01-02 posted on 2021-01-01 with narrative 1 (anb transfer) and narrative 2 (21003551) :61:2102030101C110,15NTRN123456//Credit transfer A credit fee transfer with value date 2021-02-03 posted on 2021-01-01 with narrative 1 (Credit transfer) and narrative 2 (123456) |
| :86: | Statement enrichment line Supports a couple of key-value pairs: ORDP: ordering party BENM: beneficiary name IBAN: source IBAN NTWRK: payment network (ANB, SARIE, IPS, SWIFT, SADAD .. etc) BANK: ordering bank NAR3: narrative 3 EXCH: exchange rate CBS: core banking system ID TNXT: transaction type. Refer to appendix A |
:86:/ORDP/XYZ company\n/BENM/Ahmad Abdullah\n/IBAN/SA71300000123456789123456\n/NAR3/this is narrative 3\n/NTWRK/ANB/EXCH/1/CBS/SDC1234567/TNXT/59 |
| :62F: | Closing balance as of transaction date [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:62F:D210528SAR97500,00 the closing balance on 2021-05-28 is 97500,00 SAR |
| :64: | Closing balance as of value date [1!a(C for credit, D for debit)][YYMMDD(from date)][3!a(currency)][15d (amount)] |
:64F:D210528SAR97500,00 the closing balance on 2021-05-28 is 97500,00 SAR |
In case you are not subscribed to EOD webhook and you want to inquire about your generated EOD statements via the API, we recommend inquiring about yesterday's EOD statement at 12:00 PM.
All EOD Statements Service
You may use this service to inquire about all EOD statements generated for your accounts. The service supports a couple of filter and sort options.
The actual MT940 content won't be returned in this API due to its large size. You need to use this service to get the MT940 content using the unique UUID.
| Field | Description | Required |
|---|---|---|
| Order | Order generated EOD statements by created date | No. Default: ASC Values: ASC, DESC |
| Page | Page number. Used for pagination | No |
| Take | The number of statements to be returned in the response | No |
| Date | Fetch only EOD statements generated for the passed date | No Format: YYYY-MM-DD |
| Field | Description | Always |
|---|---|---|
| Data | List of all returned EOD statements | Yes |
| Meta | Meta object | Yes |
| Field | Description | Always |
|---|---|---|
| Id | Unique UUID for the generated EOD statement | Yes |
| Created at | Date of creation (ISO format) | Yes |
| Updated at | Last update date (ISO format) | Yes |
| Account number | anb account number | Yes |
| Date | Date of EOD statement Format: YYYY-MM-DD |
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 |
Specific EOD Statement Service
Use this service to get a specific end of day statements report in MT940 format
| Field | Description | Always |
|---|---|---|
| Id | Unique UUID for the generated EOD statement | Yes |
| Created at | Date of creation (ISO format) | Yes |
| Updated at | Last update date (ISO format) | Yes |
| Account number | anb account number | Yes |
| Date | Date of EOD statement Format: YYYY-MM-DD |
Yes |
| Data | MT940 content | Yes |
The response of this service might exceed 5 MB depending on the size of the MT940.
Handling Incoming transfer to Virtual IBAN (RMS)
When a company’s client initiate a transfer via SARIE, IPS, SWIFT or ANB channels to a virtual IBAN, the below steps to be followed:
- ANB will immediately credit this transaction to the corresponding company collection account.
- Company should call the Intraday account statement (JSON) every 30 minutes or call the end of day statement of a specific day to fetch the new transactions.
- The company can identify the virtual account in the account statement which is the last 15 digits of the Virtual IBAN where it will be presented in narrative 2.
- Company then will need to map the credited transaction to the owner of virtual IBAN in their system.
Appendix A: Transaction Types
| Transaction Type | Description |
|---|---|
| 0 | Multi Transaction |
| 1 | Credit Voucher |
| 2 | Cash Deposit |
| 3 | Cash Withdrawal |
| 4 | Debit Clearing |
| 5 | Clearing Credit |
| 6 | Settlement of Certified Cheque-Treasury |
| 7 | Draft Cheques |
| 8 | Foreign Currencies |
| 9 | Brought Forward Balance |
| 10 | CHEQUE CLEARING DR |
| 11 | Time Deposit |
| 12 | Time Deposit Renewal |
| 13 | Time Deposit Breakage |
| 14 | Reversal of Deposit |
| 15 | Returned Cheques |
| 16 | Interest Calculation |
| 17 | Settlement of Matured Interest |
| 18 | Interest Capitalization |
| 19 | Draft Cheque Deposit |
| 20 | Arab Fund |
| 21 | Accrued Interest |
| 22 | Special Voucher |
| 23 | Interest Rate Change |
| 24 | DIVIDEND DISTRIBUTION |
| 25 | TRAVEL CHQ. PURCHASE |
| 26 | Outgoing Cheques |
| 27 | Selling and Buying Currencies |
| 28 | Issued Draft |
| 29 | Posting 0 Amount TRNS. |
| 30 | Scheduling Loan Settlement |
| 31 | Direct Transfer |
| 32 | Direct Transfer |
| 33 | Cheque Deposit |
| 34 | Visa Payment |
| 35 | Reversal Transaction |
| 36 | Voucher Debit/Credit |
| 37 | Issued Transfer |
| 38 | Pension Payment |
| 39 | Single Side Transaction |
| 40 | Open Loan |
| 41 | Discounted Bills |
| 42 | Loans Payment |
| 43 | Loans Payment Reversal |
| 44 | B/F Balance |
| 45 | Reversal Transaction |
| 46 | ATM DR TRS. Electron card |
| 47 | Time Deposit |
| 48 | B/F Balance |
| 49 | Uncleared Amount |
| 50 | Telemoney Transaction |
| 51 | Debit Voucher |
| 52 | Unmatured Interest |
| 53 | Covering Voucher |
| 54 | Incoming Transfer |
| 55 | Issued Draft |
| 56 | Outgoing Transfer |
| 57 | Settlement of Incoming Transfer |
| 58 | Issued Transfer |
| 59 | Incoming Transfer |
| 60 | Issued Draft |
| 61 | Placement- Others |
| 62 | Placement Renewal |
| 63 | Certified Cheque |
| 64 | Certified Cheque Settlement |
| 65 | Placement Breakage |
| 66 | BTS Interface Transaction |
| 67 | Voucher |
| 68 | Settlement of Unpaid Issued Draft |
| 69 | Settlement of Unpaid Issued Draft |
| 70 | Unpaid Issued Draft |
| 71 | EBS Debit |
| 72 | EBS Credit |
| 73 | Traveller Cheques Sales |
| 74 | Traveller Cheques Sales |
| 75 | Sale of Foreign Currencies |
| 76 | Buying Foreign Currencies |
| 77 | POS Debit |
| 78 | POS Credit |
| 79 | ATM Transaction |
| 80 | Automatic Time Deposit Maturity |
| 81 | Accrued Interest Reversal |
| 82 | Branch Net Credit |
| 83 | Monthly Charge for POS service |
| 84 | Issued Transfer Fixed Assets |
| 85 | SADAD PAYMENT |
| 86 | Cheque Withdrawal |
| 87 | Settlement of Service Bills |
| 88 | Incoming Clearing |
| 89 | Cash Transaction Form Branchpower |
| 90 | Standing Order Credit |
| 91 | Standing Order Debit |
| 92 | S/O Charge Credit |
| 93 | S/O Charge Debit |
| 94 | Credit Charges on Cheques |
| 95 | Debit Charges on Cheques |
| 96 | Credit Transfer |
| 97 | Draft Cheques Charges |
| 98 | Unpaid Charges on Accounts |
| 99 | Credit Clearing |
Appendix B: Transaction Codes
| Code | Description |
|---|---|
| NBNK | Bank fees |
| NBOE | Bill of exchange |
| NBRF | Brokerage fee |
| NCAS | Securities Related Item Cash in Lieu |
| NCHG | Charges and other expenses |
| NCHK | Cheques |
| NCLR | Cash letters/Cheques remittance |
| NCMI | Cash management item No detail |
| NCMN | Cash management item National pooling |
| NCMP | Compensation claims |
| NCMS | Cash management item Sweeping |
| NCMT | Cash management item -Topping |
| NCMZ | Cash management item Zero-Balancing |
| NCOL | Collections (used when entering a principal amount) |
| NCOM | Commission |
| NCPN | Securities Related Item Coupon payments |
| NDCR | Documentary credit (used when entering a principal amount) |
| NDDT | Direct Debit Item |
| NDIS | Securities Related Item Gains disbursement |
| NDIV | Securities Related Item Dividends |
| NEQA | Equivalent amount |
| NEXT | Securities Related Item External transfer for own account |
| NFEX | Foreign exchange |
| NINT | Interest |
| NLBX | Lock box |
| NLDP | Loan deposit |
| NMAR | Securities Related Item Margin payments/Receipts |
| NMAT | Maturity |
| NMGT | Management fees |
| NMSC | Miscellaneous |
| NNWI | New issues distribution |
| NODC | Overdraft charge |
| NOPT | Options |
| NPCH | Securities Purchase |
| NPOP | Securities Related Item pair-off proceeds |
| NPRN | Securities Related Item Principal pay-down/pay-up |
| NREC | Securities Related Item Tax reclaim |
| NRED | Securities Related Item Redemption/Withdrawal |
| NRIG | Securities Related Item Rights |
| NRTI | Returned item |
| NSAL | Securities Related Item |
| NSEC | Securities (used when entering a principal amount) |
| NSLE | Securities Related Item Securities lending related |
| NSTO | Standing order |
| NSTP | Stamp duty |
| NSUB | Subscription |
| NSWP | SWAP payment |
| NTAX | Withholding tax payment |
| NTCK | Travellers cheques |
| NTCM | Securities Related Item |
| NTRA | Internal transfer for own account |
| NTRF | Transfer |
| NTRN | Transaction fee |
| NUWC | Underwriting commission |
| NWAR | Warrant |
Appendix C: IPS Return and Rejection Codes
IPS Return Payments from local banks will be automatically posted to your initiating account within 1 business day and narratives will appear as follows in MT940 and Intraday:
Narrative 2: Original TransactionReferenceNumber
Narrative 3: IPS rejection code
| Error Code | Error Description | Error Description Ar |
|---|---|---|
| AC03 | Invalid Creditor Account Number | رقم حساب دائن غير صالح |
| AC04 | Closed Account Number | رقم حساب مغلق |
| AC06 | Blocked Account | حساب مجمد |
| AC07 | Closed Creditor Account Number | رقم حساب دائن مغلق |
| AC11 | Invalid Creditor Account Currency | عمله حساب دائن غير صالحه |
| AC14 | Invalid Creditor Account Type | نوع حساب دائن غير صالح |
| AC15 | Account Details Changed | تفاصيل الحساب تغيرت |
| BE04 | Missing Creditor Address | عنوان الدائن مفقود |
| BE06 | Unknown End Customer | عميل نهائي غير معروف |
| BE07 | Missing Debtor Address | عنوان المدين مفقود |
| BE10 | Invalid Debtor Country | بلد مدين غير صالح |
| BE11 | Invalid Creditor Country | بلد دائن غير صالح |
| BE13 | Invalid Debtor Country Of Residence | بلد الإقامة المدين غير صالح |
| BE14 | Invalid Creditor Country Of Residence | بلد الإقامة الدائن غير صالح |
| BE16 | Invalid Debtor Identification Code | رمز تعريف المدين غير صالح |
| BE17 | Invalid Creditor Identification Code | رمز تعريف الدائن غير صالح |
| MD07 | End Customer Deceased | العميل النهائي متوفي |
| NARR | Narrative | وصف |
| DS24 | Creditor Participant timeout | انتهت مهله المشترك الدائن |
| AM04 | Insufficient Funds | رصيد غير كاف |
| DT04 | Future Date Not Supported | التاريخ المستقبلي غير معتمد |
| DUPL | Duplicate Payment | دفعه مكرره |