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 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
email 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

 

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

 

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

 

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

 

Virtual Account Inquiry Request
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

 

Virtual Account Inquiry Response
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
email 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

 

VA Payment Transfer Request
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

 

VA Payment Transfer Response
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

 

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

 

VA Payment Inquiry Response
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

 

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

 

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

 

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

 

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

 

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