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:
    1. VIBAN ? ANB: Transfer to ANB account.
    2. VIBAN ? LOCAL: Transfer to a local bank.
    3. 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

Virtual Account Create Request
Field Description Required Length Format
clientId Client ID as onboarded in TSMS. Yes 12 string
schemeId Scheme ID as onboarded in TSMS. Yes 35 string
remitterId Debitor ID. Yes 8 string
poiNumber National Id of the debitor. No 15 string
langCode Language Code. Yes 1 Enum: [{0: 'English'}, {1: 'Arabic'}]
nickName Debitor nickname. No 35 string
remitterNameEnglish Debitor English Name; mandtaory if LangCode is 0. No 100 string
remitterNameArabic Debitor Arabic Name; mandtaory if LangCode is 1. No 100 string
remitterAddressLine1 Debitor Address Line 1. Yes 100 string
remitterAddressLine2 Debitor Address Line 2. No 100 string
remitterAddressLine3 Debitor Address Line 3. No 100 string
remitterAddressLine4 Debitor Address Line 4. No 100 string
email Debitor Email. Yes 60 string
startDate Debitor Start Date. Yes   string
mobileNumber Debitor Mobile Number. Yes 12 string
invoiceNotificationFlag   No 1 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 19 string

 

Virtual Account Create Response
Field Description Required Length Format
statusDetails Status Details. No 100 string
clientId Client ID as onboarded in TSMS. No 12 string
schemeId Scheme ID as onboarded in TSMS. No 35 string
remitterId Debitor ID. No 8 string
remitterBBANAcctNum Debitor BBAN Account Number. No 15 string
remitterIBANAcctNum Debitor IBAN Account Number. No 24 string
errorDetails   No 100 object

 

Virtual Account Update Request
Field Description Required Length Format
clientId Client ID as onboarded in TSMS. Yes 12 string
schemeId Scheme ID as onboarded in TSMS. Yes 35 string
remitterId Debitor ID. Yes 8 string
poiNumber National Id of the debitor. No 15 string
langCode Language Code. No 1 Enum: [{0: 'English'}, {1: 'Arabic'}]
nickName Debitor nickname. No 35 string
remitterNameEnglish Debitor English Name; mandtaory if LangCode is 0. No 100 string
remitterNameArabic Debitor Arabic Name; mandtaory if LangCode is 1. No 100 string
remitterAddressLine1 Debitor Address Line 1. Yes 100 string
remitterAddressLine2 Debitor Address Line 2. No 100 string
remitterAddressLine3 Debitor Address Line 3. No 100 string
remitterAddressLine4 Debitor Address Line 4. No 100 string
remitterBBANAcctNum Debitor BBAN Account Number. Yes 15 string
remitterIBANAcctNum Debitor IBAN Account Number. Yes 24 string
email Debitor Email. No 60 string
startDate Debitor Start Date. No   string
mobileNumber Debitor Mobile Number. No 12 string
invoiceNotificationFlag   No 1 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 19 string

 

Virtual Account Update Response
Field Description Required Length Format
statusDetails Status Details. No 100 string
clientId Client ID as onboarded in TSMS. No 12 string
schemeId Scheme ID as onboarded in TSMS. No 35 string
remitterId Debitor ID. No 8 string
remitterBBANAcctNum Debitor BBAN Account Number. No 15 string
remitterIBANAcctNum Debitor IBAN Account Number. No 24 string
errorDetails   No 100 object

 

Virtual Account Inquiry Request
Field Description Required Length Format
remitterIBANAcctNumber Remitter IBAN Account Number (Mandatory if Sending request with remitterIBANAcctNumber only) Yes 24 string
remitterId Remitter ID Number (Mandatory if Sending request with RemitterID, SchemeId, ClientId) No 8 string
schemeId Scheme ID Number (Mandatory if Sending request with RemitterID, SchemeId, ClientId) No 35 string
clientId Client ID Number (Mandatory if Sending request with RemitterID, SchemeId, ClientId) No 12 string

 

Virtual Account Inquiry Response
Field Description Required Length Format
code Response Code No   string
message Response Code No   string
clientId Client ID as onboarded in TSMS. No 12 string
schemeId Scheme ID as onboarded in TSMS. No 35 string
remitterId Debitor ID. No 8 string
remitterNameEnglish Debitor English Name; mandtaory if LangCode is 0. No 100 string
remitterNameArabic Debitor Arabic Name; mandtaory if LangCode is 1. No 100 string
remitterAddressLine1 Debitor Address Line 1. No 100 string
remitterAddressLine2 Debitor Address Line 2. No 100 string
remitterAddressLine3 Debitor Address Line 3. No 100 string
remitterAddressLine4 Debitor Address Line 4. No 100 string
email Debitor Email. No 60 string
mobileNumber Debitor Mobile Number. No 12 string
poiNumber National Id of the debitor. No 15 string
remitterIBANAcctNum Debitor IBAN Account Number. No 24 string
remitterBBANAcctNum Debitor BBAN Account Number. No 15 string
startDate Debitor Start Date. No   string
accountBalance Current Virtual Account Balance No 19 number
closingBalance Current Virtual Account Closing Balance No 19 number
openingBalance Current Virtual Account Open Balance No 19 number
status Account Status No 12 string
nickName Debitor nickname. No 35 string
vaLimit Total Credit Limit for VIBAN No 19 string

 

VA Payment Transfer Request
Field Description Required Length Format
clientId Client ID as onboarded in TSMS. Yes 12 string
schemeId Scheme ID as onboarded in TSMS. Yes 35 string
remitterId Debitor ID. Yes 8 string
remitterIBANAcctNum Debit Account Yes 15 string
trnType   Yes 12 Enum: ['INTERNAL', 'SARIE']
beneficiaryName Beneficiary Name Yes 35 string
customerReferenceNumber Customer Reference Number No 35 string
beneficiaryAccount Credit Account Yes 24 string
beneficiaryBankBIC Destination Bank BIC Yes 10 string
beneficiaryAddressLine1 Beneficiary Address Line 1 Yes 100 string
beneficiaryAddressLine2 Beneficiary Address Line 2 No 100 string
beneficiaryAddressLine3 Beneficiary Address Line 3 No 100 string
beneficiaryAddressLine4 Beneficiary Address Line 4 No 100 string
transactionAmount Transaction Amount <17>.<2> Yes 19 number
paymentDetails1 Payemnt Details English Line 1 Yes 35 string
paymentDetails2 Payemnt Details English Line 2 No 30 string
remarks Payemnt Remarks No 35 string
paymentDetailsArabic1 Payemnt Details Arabic Line 1 Yes 35 string
paymentDetailsArabic2 Payemnt Details Arabic Line 2 No 30 string

 

VA Payment Transfer Response
Field Description Required Length Format
statusDescription Status Description No   string
code Response Code No   number
referenceNumber Unique reference number for the transaction. No 10 string
uti unique transaction reference number No 16 string
errorDetails Validation Error List No 100 object

 

VA Payment Inquiry Request
Field Description Required Length Format
referenceNumber Unique reference number for the transaction. Yes 35 string
valueDate Date Of Payment Creation (YYYY-MM-DD) Yes 10 string

 

VA Payment Inquiry Response
Field Description Required Length Format
clientId Client ID as onboarded in TSMS. No 12 string
remitterId Debitor ID. No 8 string
schemeId Scheme ID as onboarded in TSMS. No 35 string
remitterIBANAcctNum Debit Account No 24 string
referenceNumber Unique reference number for the transaction. (Starts with "RM") No 35 string
code Response Code No   string
statusDescription Payment Description No   string
trnType   No 12 Enum: ['INTERNAL', 'SARIE']
valueDate Date Of Payment Creation (YYYY-MM-DD) No 10 string

 

Virtual Account Status Update Request
Field Description Required Length Format
remitterIBANAcctNum remitter IBAN Account Number No 24 string
clientId Client ID as onboarded from ALFARI. No 12 string
schemeId Scheme ID as onboarded from ALFARI. No 35 string
remitterId Dremitter ID as onboarded from ALFARIS No 8 string
status   No 15 Enum: [{'ACTIVATE': 'Activate Account'}, {'DEACTIVATE': 'Deactivate Account'}]
statusUpdateReason Status Update Description based on status () No 35 string

 

Virtual Account Status Update Response
Field Description Required Length Format
remitterIBANAcctNum remitter IBAN Account Number No 24 string
clientId Client ID as onboarded from ALFARI. No 12 string
schemeId Scheme ID as onboarded from ALFARI. No 35 string
remitterId Dremitter ID as onboarded from ALFARIS No 8 string
status   No   Enum: [{'ACTIVATE': 'Activate Account'}, {'DEACTIVATE': 'Deactivate Account'}]
errorDtls only shown when errors are present No   object

 

Virtual Account Statement Inquiry Request
Field Description Required Length Format
remitterIBANAcctNum remitterIBANAccNumber should be available in TSMS Yes 24 string
PageNo Specifies the page number of the account statement to retrieve, enabling pagination. No 5 string
From Dt The starting date of the transaction period Yes   date
To Dt The ending date of the transaction period Yes   date

 

Virtual Account Statement Inquiry Response
Field Description Required Length 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 8 integer
completionFlag indicator for completion of statement for current batch YES/NO No 3 string
PageNo Specifies the page number of the page. No 5 string
totalPageNum total numbers of statements for the account number No 5 string
recordDisplayed total number of records displayed per batch No 8 integer
trnList List of transactions No   object
errorDtls only shown when errors are present No   object

 

Services Error codes

 

Virtual Account Create 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

 

Virtual Account Update 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

 

Virtual Account Inquiry Error codes
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

 

VA Payment Transfer Error codes
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

 

VA Payment Inquiry Error codes
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

 

Virtual Account Status Update Error codes
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

 

Virtual Account Statement Inquiry Error codes
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