Overview
The Virtual IBAN Management System enables corporate to manage Virtual IBANs (VIBANs) for digital payments, collections, and account management. The system provides functionalities such as creating and updating VIBANs, making payments, retrieving statements, and monitoring status. Additionally, the system supports push notifications for payment events and payment inquiries for transparency and tracking.
The solution streamlines digital banking by offering flexibility, automation, and real-time updates, reducing manual intervention.
Prerequisites
To use the VIBAN Management System, you need to do the following:
- Collection Account: used for consolidating funds.
- 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.
Features & Use Cases
VIBAN Create
- Description: Creates a new VIBAN linked to a client’s profile.
- Use Case: A corporate wants to assign unique VIBANs to multiple customers for easy reconciliation of collections.
- Benefit: Simplifies tracking of incoming funds, reduces reconciliation errors.
Update VIBAN
- Description: Updates personal information or details linked to an existing VIBAN.
- Use Case: A client changes contact info or business details that must reflect in their VIBAN profile.
- Benefit: Keeps VIBAN information accurate and up-to-date.
VIBAN Inquiry
- Description: Retrieves VIBAN details including user info, balance, and status (Active/Inactive).
- Use Case: A client wants to check the current balance or confirm if a VIBAN is still active.
- Benefit: Provides transparency and real-time information.
VIBAN Payment
- Description: Enables payments from a remitter VIBAN.
- Scenarios:
- VIBAN → ANB: Transfer to ANB account.
- VIBAN → LOCAL: Transfer to a local bank.
- VIBAN → VIBAN: Wallet-to-wallet transfers within the system.
- Benefit: Flexible payment options covering internal, local, and peer-to-peer transfers.
VIBAN Payment Inquiry
- Description: Inquiry service to track and confirm payment status.
- Use Case: A client wants confirmation whether a VIBAN payment was processed successfully.
- Benefit: Reduces uncertainty, improves trust, supports reconciliation.
VIBAN Statement
- Description: Generates a transaction statement for a VIBAN.
- Use Case: A corporate requires monthly transaction reports for accounting.
- Benefit: Provides clear audit trail and financial reporting.
VIBAN Status Update
- Description: Allows changing a VIBAN status to Active or Inactive.
- Use Case: A business wants to temporarily suspend a VIBAN assigned to an inactive customer.
- Benefit: Provides control and security over VIBAN usage.
Push Notifications
- Description: Sends real-time alerts to clients for payment and system events.
- Use Case: A client receives an instant notification when a payment is credited.
- Benefit: Improves transparency, customer experience, and reduces manual checks.
Request and Response Parameters
Field | Description | Required | Format |
---|---|---|---|
clientId | Client ID as onboarded in TSMS. | Yes | string |
schemeId | Scheme ID as onboarded in TSMS. | Yes | string |
remitterId | Debitor ID. | Yes | string |
poiNumber | National Id of the debitor. | No | string |
langCode | Language Code. | Yes | Enum: [{0: 'English'}, {1: 'Arabic'}] |
nickName | Debitor nickname. | No | string |
remitterNameEnglish | Debitor English Name; mandtaory if LangCode is 0. | No | string |
remitterNameArabic | Debitor Arabic Name; mandtaory if LangCode is 1. | No | string |
remitterAddressLine1 | Debitor Address Line 1. | Yes | string |
remitterAddressLine2 | Debitor Address Line 2. | No | string |
remitterAddressLine3 | Debitor Address Line 3. | No | string |
remitterAddressLine4 | Debitor Address Line 4. | No | string |
Debitor Email. | Yes | string | |
startDate | Debitor Start Date. | Yes | string |
mobileNumber | Debitor Mobile Number. | Yes | string |
invoiceNotificationFlag | No | Enum: [{'E': 'EMAIL'}, {'S': 'SMS'}, {'B': 'BOTH'}, {'N': 'No Notification'}] | |
idExpiryDate | Expiry Date for the Debitor ID "YYYY-MM-DD" | No | string |
vaLimit | Total Credit Limit for VIBAN | Yes | string |
Field | Description | Required | Format |
---|---|---|---|
statusDetails | Status Details. | No | string |
clientId | Client ID as onboarded in TSMS. | No | string |
schemeId | Scheme ID as onboarded in TSMS. | No | string |
remitterId | Debitor ID. | No | string |
remitterBBANAcctNum | Debitor BBAN Account Number. | No | string |
remitterIBANAcctNum | Debitor IBAN Account Number. | No | string |
errorDetails | No | object |
Field | Description | Required | Format |
---|---|---|---|
clientId | Client ID as onboarded in TSMS. | Yes | string |
schemeId | Scheme ID as onboarded in TSMS. | Yes | string |
remitterId | Debitor ID. | Yes | string |
poiNumber | National Id of the debitor. | No | string |
langCode | Language Code. | No | Enum: [{0: 'English'}, {1: 'Arabic'}] |
nickName | Debitor nickname. | No | string |
remitterNameEnglish | Debitor English Name; mandtaory if LangCode is 0. | No | string |
remitterNameArabic | Debitor Arabic Name; mandtaory if LangCode is 1. | No | string |
remitterAddressLine1 | Debitor Address Line 1. | Yes | string |
remitterAddressLine2 | Debitor Address Line 2. | No | string |
remitterAddressLine3 | Debitor Address Line 3. | No | string |
remitterAddressLine4 | Debitor Address Line 4. | No | string |
remitterBBANAcctNum | Debitor BBAN Account Number. | Yes | string |
remitterIBANAcctNum | Debitor IBAN Account Number. | Yes | string |
Debitor Email. | No | string | |
startDate | Debitor Start Date. | No | string |
mobileNumber | Debitor Mobile Number. | No | string |
invoiceNotificationFlag | No | Enum: [{'E': 'EMAIL'}, {'S': 'SMS'}, {'B': 'BOTH'}, {'N': 'No Notification'}] | |
idExpiryDate | Expiry Date for the Debitor ID "YYYY-MM-DD" | No | string |
vaLimit | Total Credit Limit for VIBAN | No | string |
Field | Description | Required | Format |
---|---|---|---|
statusDetails | Status Details. | No | string |
clientId | Client ID as onboarded in TSMS. | No | string |
schemeId | Scheme ID as onboarded in TSMS. | No | string |
remitterId | Debitor ID. | No | string |
remitterBBANAcctNum | Debitor BBAN Account Number. | No | string |
remitterIBANAcctNum | Debitor IBAN Account Number. | No | string |
errorDetails | No | object |
Field | Description | Required | Format |
---|---|---|---|
remitterIBANAcctNumber | Remitter IBAN Account Number (Mandatory if Sending request with remitterIBANAcctNumber only) | Yes | string |
remitterId | Remitter ID Number (Mandatory if Sending request with RemitterID, SchemeId, ClientId) | No | string |
schemeId | Scheme ID Number (Mandatory if Sending request with RemitterID, SchemeId, ClientId) | No | string |
clientId | Client ID Number (Mandatory if Sending request with RemitterID, SchemeId, ClientId) | No | string |
Field | Description | Required | Format |
---|---|---|---|
code | Response Code | No | string |
message | Response Code | No | string |
clientId | Client ID as onboarded in TSMS. | No | string |
schemeId | Scheme ID as onboarded in TSMS. | No | string |
remitterNameEnglish | Debitor English Name; mandtaory if LangCode is 0. | No | string |
remitterNameArabic | Debitor Arabic Name; mandtaory if LangCode is 1. | No | string |
remitterAddressLine1 | Debitor Address Line 1. | No | string |
remitterAddressLine2 | Debitor Address Line 2. | No | string |
remitterAddressLine3 | Debitor Address Line 3. | No | string |
remitterAddressLine4 | Debitor Address Line 4. | No | string |
Debitor Email. | No | string | |
mobileNumber | Debitor Mobile Number. | No | string |
poiNumber | National Id of the debitor. | No | string |
remitterIBANAcctNum | Debitor IBAN Account Number. | No | string |
remitterBBANAcctNum | Debitor BBAN Account Number. | No | string |
startDate | Debitor Start Date. | No | string |
accountBalance | Current Virtual Account Balance | No | number |
closingBalance | Current Virtual Account Closing Balance | No | number |
openingBalance | Current Virtual Account Open Balance | No | number |
status | Account Status | No | string |
nickName | Debitor nickname. | No | string |
vaLimit | Total Credit Limit for VIBAN | No | string |
Field | Description | Required | Format |
---|---|---|---|
clientId | Client ID as onboarded in TSMS. | Yes | string |
schemeId | Scheme ID as onboarded in TSMS. | Yes | string |
remitterId | Debitor ID. | Yes | string |
remitterIBANAcctNum | Debit Account | Yes | string |
trnType | Yes | Enum: ['INTERNAL', 'SARIE'] | |
beneficiaryName | Beneficiary Name | Yes | string |
customerReferenceNumber | Customer Reference Number | No | string |
beneficiaryAccount | Credit Account | Yes | string |
beneficiaryBankBIC | Destination Bank BIC | Yes | string |
beneficiaryAddressLine1 | Beneficiary Address Line 1 | Yes | string |
beneficiaryAddressLine2 | Beneficiary Address Line 2 | No | string |
beneficiaryAddressLine3 | Beneficiary Address Line 3 | No | string |
beneficiaryAddressLine4 | Beneficiary Address Line 4 | No | string |
transactionAmount | Transaction Amount <17>.<2> | Yes | number |
paymentDetails1 | Payemnt Details English Line 1 | Yes | string |
paymentDetails2 | Payemnt Details English Line 2 | No | string |
remarks | Payemnt Remarks | No | string |
paymentDetailsArabic1 | Payemnt Details Arabic Line 1 | Yes | string |
paymentDetailsArabic2 | Payemnt Details Arabic Line 2 | No | string |
Field | Description | Required | Format |
---|---|---|---|
statusDescription | Status Description | No | string |
code | Response Code | No | number |
referenceNumber | Unique reference number for the transaction. | No | string |
uti | unique transaction reference number | No | string |
errorDetails | Validation Error List | No | object |
Field | Description | Required | Format |
---|---|---|---|
referenceNumber | Unique reference number for the transaction. | Yes | string |
valueDate | Date Of Payment Creation (YYYY-MM-DD) | Yes | string |
Field | Description | Required | Format |
---|---|---|---|
clientId | Client ID as onboarded in TSMS. | No | string |
remitterId | Debitor ID. | No | string |
schemeId | Scheme ID as onboarded in TSMS. | No | string |
remitterIBANAcctNum | Debit Account | No | string |
referenceNumber | Unique reference number for the transaction. (Starts with "RM") | No | string |
code | Response Code | No | string |
statusDescription | Payment Description | No | string |
trnType | No | Enum: ['INTERNAL', 'SARIE'] | |
valueDate | Date Of Payment Creation (YYYY-MM-DD) | No | string |
Field | Description | Required | Format |
---|---|---|---|
remitterIBANAcctNum | remitter IBAN Account Number | No | string |
clientId | Client ID as onboarded from ALFARI. | No | string |
schemeId | Scheme ID as onboarded from ALFARI. | No | string |
remitterId | Dremitter ID as onboarded from ALFARIS | No | string |
status | No | Enum: [{'ACTIVATE': 'Activate Account'}, {'DEACTIVATE': 'Deactivate Account'}] | |
statusUpdateReason | Status Update Description based on status () | No | string |
Field | Description | Required | Format |
---|---|---|---|
remitterIBANAcctNum | remitter IBAN Account Number | No | string |
clientId | Client ID as onboarded from ALFARI. | No | string |
schemeId | Scheme ID as onboarded from ALFARI. | No | string |
remitterId | Dremitter ID as onboarded from ALFARIS | No | string |
status | No | Enum: [{'ACTIVATE': 'Activate Account'}, {'DEACTIVATE': 'Deactivate Account'}] | |
errorDtls | only shown when errors are present | No | object |
Field | Description | Required | Format |
---|---|---|---|
remitterIBANAcctNum | remitterIBANAccNumber should be available in TSMS | Yes | string |
PageNo | Specifies the page number of the account statement to retrieve, enabling pagination. | No | string |
From Dt | The starting date of the transaction period | Yes | date |
To Dt | The ending date of the transaction period | Yes | date |
Field | Description | Required | Format |
---|---|---|---|
fromDt | YYYY-mm-DD | No | string |
toDt | YYYY-mm-DD | No | string |
totalRecord | total number of records in statement for the date period | No | integer |
completionFlag | indicator for completion of statement for current batch YES/NO | No | string |
PageNo | Specifies the page number of the page. | No | string |
totalPageNum | total numbers of statements for the account number | No | string |
recordDisplayed | total number of records displayed per batch | No | integer |
trnList | List of transactions | No | object |
errorDtls | only shown when errors are present | No | object |
Services Error codes
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501001 | Failed |
E501002 | Customer is not registered on TSMS |
E501003 | VA Scheme is not defined on TSMS |
E501004 | No matching Remitter details found on TSMS |
E501005 | Validation failed |
E501006 | Internal Server Error |
E501007 | Service is unavailable or down |
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501001 | Failed |
E501002 | Customer is not registered on TSMS |
E501003 | VA Scheme is not defined on TSMS |
E501004 | No matching Remitter details found on TSMS |
E501005 | Validation failed |
E501006 | Internal Server Error |
E501007 | Service is unavailable or down |
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501008 | SEND |
E501009 | RETURNED |
E501010 | REFUNDED |
E501011 | REJECTED |
E501012 | Invalid request message. |
E501013 | Remitter details can only be retrieved using either the IBAN account number or a combination of Client ID, Scheme ID, and Remitter ID |
E501014 | Invalid Remitter IBAN Account number. |
E501015 | Remitter details does not exists in the system |
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501008 | SEND |
E501009 | RETURNED |
E501010 | REFUNDED |
E501011 | REJECTED |
E501012 | Invalid request message. |
E501013 | Remitter details can only be retrieved using either the IBAN account number or a combination of Client ID, Scheme ID, and Remitter ID |
E501014 | Invalid Remitter IBAN Account number. |
E501015 | Remitter details does not exists in the system |
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501008 | SEND |
E501009 | RETURNED |
E501010 | REFUNDED |
E501011 | REJECTED |
E501012 | Invalid request message. |
E501013 | Remitter details can only be retrieved using either the IBAN account number or a combination of Client ID, Scheme ID, and Remitter ID |
E501014 | Invalid Remitter IBAN Account number. |
E501015 | Remitter details does not exists in the system |
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501008 | SEND |
E501009 | RETURNED |
E501010 | REFUNDED |
E501011 | REJECTED |
E501012 | Invalid request message. |
E501013 | Remitter details can only be retrieved using either the IBAN account number or a combination of Client ID, Scheme ID, and Remitter ID |
E501014 | Invalid Remitter IBAN Account number. |
E501015 | Remitter details does not exists in the system |
Error Code | Error Description |
---|---|
I000000 | Successful Operation |
E501008 | SEND |
E501009 | RETURNED |
E501010 | REFUNDED |
E501011 | REJECTED |
E501012 | Invalid request message. |
E501013 | Remitter details can only be retrieved using either the IBAN account number or a combination of Client ID, Scheme ID, and Remitter ID |
E501014 | Invalid Remitter IBAN Account number. |
E501015 | Remitter details does not exists in the system |