Corporate
Virtual Account Management
Description
These APIs allow corporate clients to assign unique virtual account numbers to their customers or transactions, simplifying the reconciliation process and enhancing financial management.
- Overview
- APIs Offered
- Use Cases
- This API provides 3 operation types namely, initiate, view and enquiry
- Applications must get the token using the “Get Token API," which will provide the access token details. This token must be used for the subsequent interactions of RESTful APIs. Tokens will be valid for 180s
- Please use View and Inquiry APIs as parameters in POSTMAN for testing purposes.
- “Finalstatus” It can be Y or N. if "Y,” it means no further status of transaction is expected, i.e. either Transaction is completed or rejected. If "N,” it means transaction is still in transit and status update is expected to change. Finalstatus field will be available soon in future.
Virtual Account Management API
View API Specifications
This API is used to initiate, view and inquire about virtual accounts for the corporate; both bulk and single requests are supportive through this API.
NOTE:
Flow Chart
Image
What operations can be performed?
1. initiate: This service will be used to initiate virtual accounts for the corporate; both bulk and single requests are supportive through this API. This is a POST method
Request Headers:
Fields
Description
Mandatory/Optional
Data Type
Length
Sample Value
clientId
Unique client ID provided by Mashreq to corporate.
Mandatory
STRING
Authorization
Bearer Token received from get token API with respect to Scope
Mandatory
STRING
Request Parameters:
Fields
Description
Mandatory/Optional
Data Type
Length
Sample Value
reqType
This is requesting type which should always be prefixed as "CREATE"
Mandatory
STRING
Max 9
CREATE
batchId
Unique reference number which client can input in the field.
Mandatory
STRING
Max 16
Batchtest1234567
vaRequestList
Contains array of requests with CIF level list, should have at least one request to process.
Mandatory
cif
CIF number provided by the bank to be mapped for Virtual account.
Mandatory
STRING
Max 9
010150123
virtualAccounts
Array requests for list of virtual accounts to be created
Mandatory
STRING
Min 1 - Max 100
virtualEntityId
This is entity level title which is also populated for Virtual accounts configured by the bank.
Mandatory
STRING
Max 12
001010150123
product
Product can be COBO or COLV
Mandatory
STRING
Max 4
COBO
virtualAccNumber
This field can remain blank or any specific number which becomes part of VA IBAN\Account number
Mandatory
STRING
Max 12
010101012
realAccNumber
Physical account number underneath which VA gets created.
Mandatory
STRING
12
12345678912
payerId
Payer Id is optional field.
Optional
STRING
Max 105
TESTID
remarks
It contains any information that may be required to be part of VAs.
Optional
STRING
Max 100
1000
expiryDate
This refers to expiry of Virtual accounts. Format is YYYY-MM-DD
Optional
STRING
Max 10
2025-12-31
Response Parameters:
Fields
Description
Mandatory/Optional
Data type
Length
Sample value
status
VA creation status
STRING
Max 20
description
Description of virtual account status
STRING
statusCode
This http status is at the batch level.
STRING
finalStatus
This attribute contains "Y" or "N", this can help to automate the inquiry calls to retrieve the final status
STRING
batchID
Unique reference number which is generated as the part of response at batch level.
Mandatory
STRING
Max 16
Batchtest1234567
msBatchReference
Batch reference number will be generated by the system
STRING
Max 16
channelReference
Initially when transaction gets initiated it this field remains blank.
STRING
Max 16
responseList
Contains the response of VA creation request submitted
STRING
Max 16
cif
CIF number provided by the bank.
Mandatory
STRING
Max 16
010150123
virtualAccounts
Block starts for virtual account starts here, please refer sample below
Mandatory
STRING
Max 16
virtualEntityId
This is entity level title which is also populated for Virtual accounts.
Mandatory
STRING
Max 12
001010150123
product
Product can be COBO or COLV
Mandatory
STRING
Max 4
COBO
virtualAccNumber
Whatever is input as part of initiation will be displayed in the initiation response. It can be single or array of request.
Mandatory
STRING
Max 12
010101012
realAccNumber
Physical account number underneath which VA gets created.
Mandatory
STRING
12
12345678912
payerId
Payer Id is optional field.
Optional
STRING
Max 105
TESTID
remarks
It contains any information that may be required to be part of VAs.
Optional
STRING
Max 100
1000
expiryDate
This refers to expiry of Virtual accounts.
Optional
STRING
Max 10
2025-12-31
status
Initial request is always "INITIATED"
STRING
statusCode
This is http status code, which occurs as part of response at record level.
STRING
description
Displays the description of the status
STRING
Status Code at Batch Level:
Status code
Status
Description
200
COMPLETED
ALL_TRANSACTIONS_COMPLETED
201
INITIATED
ALL_TRANSACTIONS_INITIATED
400
REJECTED
ALL_TRANSACTIONS_REJECTED
500
FAILED
ALL_TRANSACTIONS_FAILED
200
IN_PROGRESS
ALL_IN_PROGRESS
500
FAILED
ALL_TRANSACTIONS_FAILED_OR_REJECTED
200
COMPLETED
PARTIAL_TRANSACTIONS_COMPLETED
200
INITIATED
PARTIAL_TRANSACTIONS_COMPLETED
201
INITIATED
PARTIAL_TRANSACTIONS_INITIATED
Status Code at Record Level:
Status code
Status
Description
400
REJECTED
Batch Id should be unique for each request
400
REJECTED
INVALID EXPIRY DATE
400
REJECTED
Should have at least one record to process request
400
REJECTED
Valid physical account number under the given cif
400
REJECTED
Value should be numeric And Unique
401
REJECTED
Unauthorized
500
REJECTED
Internal server error
2. view: This is a GET method used to view the virtual accounts at CIF level with filters such as IBAN, virtual account number and date range.
Request Headers:
Fields
Description
Mandatory/Optional
Data Type
Length
Sample Value
clientId
Unique client ID provided by Mashreq to corporate.
Mandatory
STRING
Authorization
Bearer Token received from get token API with respect to Scope
Mandatory
STRING
Request Parameters:
Fields
Description
Mandatory/Optional
Data Type
Length
Sample Value
reqType
Unique client ID provided by mashreq to corporate"VIEW"
Mandatory
STRING
9
VIEW
accOpeningFromDate
Starting date range for Account opening date
Conditional
STRING((yyyy-MM-dd)
10
2024-02-22
accOpeningToDate
Ending date range for Account opening date
Conditional
STRING((yyyy-MM-dd)
10
2024-02-22
cif
Unique CIF number
Mandatory
STRING
Max 9
010150123
virtualAccNumber
Virtual account created in the system under a entity
Conditional
STRING
Max 12
123456789012
iban
IBAN of the virtual account
Conditional
STRING
Max 23
AE15033xxx0008000000xxx
Response Parameters:
Fields
Description
Mandatory/Optional
Data type
Length
Sample value
reqType
This is requesting type which should always be prefixed as "VIEW"
Max 20
statusCode
This http status is at the batch level.
Status
VA view status
description
Description of virtual account status
responseList
Contains array of requests with CIF level list, should have at least one request to process.
STRING
Max 16
cif
CIF number provided by the bank.
STRING
Max 16
virtualAccounts
Block starts for virtual account starts here, please refer sample below
STRING
virtualEntityId
This is entity level title which is also populated for Virtual accounts.
STRING
product
A constant value "COLV"
STRING
virtualAccNumber
Whatever is input as part of initiation will be displayed in the initiation response. It can be single or array of request.
STRING
accountTitle
Retrieves the account title of virtual account
STRING
iban
Retrieves the VA IBAN
STRING
currency
Currency of the virtual account
STRING
linkageType
Constant value "Real account"
STRING
linkageAccNumber
Physical account number underneath which VA gets created.
STRING
payerId
Payer Id is optional field.
STRING
accStatus
Gives the status of Virtual account.
STRING
OPEN/CLOSED
Status Code at Batch Level:
Status code
Status
Description
200
SUCCESS
SUCCESSFULLY FETCHED RECORDS
401
REJECTED
API_BANKING_DISABLED
400
REJECTED
CIF REQUIRED
400
REJECTED
Maximum length exceeds for CIF
400
REJECTED
CIF_SHOULD_BE_NUMERIC
400
REJECTED
REQUEST TYPE is Mandatory,Can't be null or empty
400
REJECTED
Maximum length exceeds for REQUEST TYPE
400
REJECTED
Virtual Account Min and Max length is 12 digit
400
REJECTED
Virtual Account allowed value should be numeric
400
REJECTED
PROVIDE_EITHER_IBAN_OR_VIRTUAL_ACCOUNT_NUMBER_NOT_BOTH
400
REJECTED
accOpeningToDate is Mandatory for date range search
400
REJECTED
accOpening FromDate is Mandatory for date range search
400
REJECTED
FROM_DATE_IS_AFTER_CURRENT_DATE
400
REJECTED
INVALID_DATE_FORMAT(Valid format is yyyy-MM-dd)
400
REJECTED
DATE_RANGE_SHOULD_NOT_EXCEED_15_DAYS
400
REJECTED
TO_DATE_IS_BEFORE_FROM_DATE
400
REJECTED
TO_DATE_IS_AFTER_CURRENT_DATE
400
REJECTED
INVALID_TO_DATE_FORMAT(Valid format is yyyy-MM-dd)
400
REJECTED
Search values(VirtualAccNum or IBAN or DateRange) are required
400
REJECTED
INVALID_FROM_DATE_FORMAT(Valid format is yyyy-MM-dd)
400
REJECTED
INVALID_IBAN
400
REJECTED
IBAN Min and Max length is 23 digit
400
REJECTED
INVALID REQUEST TYPE
404
SUCCESS
NO_RECORDS_FOUND
500
FAILED
Request Processing Failed due to internal server error, Please try after sometime
500
FAILED
FAILED_TO_FETCH_VIEW_VA_RECORDS
Status Code at Record Level:
Status code
Status
Description
400
REJECTED
Batch Id should be unique for each request
400
REJECTED
INVALID EXPIRY DATE
400
REJECTED
Should have at least one record to process request
400
REJECTED
Valid physical account number under the given cif
400
REJECTED
Value should be numeric And Unique
401
REJECTED
Unauthorized
500
REJECTED
Internal server error
3. enquiry: This GET method will be used to inquire about the status of the transaction, which will return the details of successful created virtual accounts.
Request Headers:
Fields
Description
Mandatory/Optional
Data Type
Length
Sample Value
clientId
Unique client ID provided by Mashreq to corporate.
Mandatory
STRING
Authorization
Bearer Token received from get token API with respect to Scope
Mandatory
STRING
Request Parameters:
Fields
Description
Mandatory/Optional
Data Type
Length
Sample Value
reqType
Unique client ID provided by Mashreq to corporate.
Mandatory
STRING
Max 9
ENQUIRY
batchId
Unique batch Id passed by the corporate\client.
Conditional
STRING
Max 16
msBatchReference
Batch reference number assigned by the bank
Conditional
cif
Unique CIF number
Mandatory
STRING
Max 9
10150935
Response Parameters:
Fields
Description
Mandatory/Optional
Data type
Length
Sample value
reqType
This is requesting type which should always be prefixed as "ENQUIRY"
Max 20
statusCode
This http status is at the batch level.
status
VA creation status
description
Description of virtual account status
Max 16
batchId
Unique reference number which client can input in the field.
Max 16
msBatchReference
Batch reference number will be generated by the system
STRING
Max 16
channelReference
Initially when transaction gets initiated it this field remains blank.
STRING
Min 1 - Max 16
vaResponseList
Contains array of requests with CIF level list, should have at least one request to process.
STRING
Max 16
cif
CIF number provided by the bank.
STRING
Max 16
status
Status can be "Completed", "Rejected" or "Partially Completed"
STRING
Max 36
description
Displays the description of the status
STRING
Max 16
virtualAccounts
Block starts for virtual account starts here, please refer sample below
STRING
Max 16
virtualEntityId
This is entity level title which is also populated for Virtual accounts.
STRING
Max 12
product
A constant value "COLV"
STRING
Max 4
virtualAccNumber
Whatever is input as part of initiation will be displayed in the initiation response. It can be single or array of request.
STRING
Max 12
realAccNumber
Physical account number underneath which VA gets created.
STRING
Min 1 - Max 15
payerId
Payer Id is optional field.
STRING
remarks
It contains any information that may be required to be part of VAs.
STRING
expiryDate
This refers to expiry of Virtual accounts.
STRING
Max 10
status
Status can be "Completed", "Rejected"
STRING
statusCode
This is http status code, which occurs as part of response at record level.
STRING
description
Displays the description of the status
STRING
Status Code at Batch Level:
Status code
Status
Description
200
COMPLETED
ALL_TRANSACTIONS_COMPLETED
201
INITIATED
ALL_TRANSACTIONS_INITIATED
400
REJECTED
ALL_TRANSACTIONS_REJECTED
500
FAILED
ALL_TRANSACTIONS_FAILED
200
IN_PROGRESS
ALL_IN_PROGRESS
500
FAILED
ALL_TRANSACTIONS_FAILED_OR_REJECTED
200
COMPLETED
PARTIAL_TRANSACTIONS_COMPLETED
200
INITIATED
PARTIAL_TRANSACTIONS_COMPLETED
201
INITIATED
PARTIAL_TRANSACTIONS_INITIATED
Status Code at Record Level:
Status code
Status
Description
200
COMPLETED
Record successfully saved. Virtual Account Number:012300000001 ; IBAN:AE430330000012300000001
400
REJECTED
Batch Id should be unique for each request
400
REJECTED
INVALID EXPIRY DATE
400
REJECTED
Should have at least one record to process request
400
REJECTED
Valid physical account number under the given cif
400
REJECTED
Value should be numeric And Unique
401
REJECTED
Unauthorized
500
REJECTED
Internal server error
500
FAILED
Please verify the provided Virtual Entity Id
500
FAILED
Please verify the provided Account Product
IMPORTANTS NOTES:
Number of API/s
1
Number of APIs
APIC Calls
320
Calls per month
Active users
220
Active users
Regions
Overview
Overview
Virtual Account Management is essential for businesses that handle a large volume of transactions from their customers. By providing unique virtual account numbers, it helps in accurately tracking and reconciling inward payments. This not only improves operational efficiency but also enhances the accuracy of financial records.
What are the benefits?
Simplified Reconciliation
Easily match incoming payments with invoices or clients using unique virtual account numbers, reducing manual effort and errors.
Improved Cash Management
Gain better control and visibility over cash flows, enabling more effective financial planning and management.
Operational Efficiency
Reduce manual intervention in payment processing, leading to faster and more accurate financial operations.
Enhanced Customer Experience
Provide clients with unique account numbers for easier payment tracking and reconciliation, improving transparency and customer satisfaction.
Scalability
Effortlessly scale the number of virtual accounts as business needs grow, accommodating increasing transaction volumes.
Cost Savings
Lower operational costs by minimizing manual reconciliation efforts and reducing the risk of errors.
Which APIs are offered?
- Virtual Account Management API: This API enables business to initiate, view and inquire about virtual accounts seamlessly, simplifying the reconciliation process and enhancing financial management.
By leveraging Mashreq’s Virtual Account Management APIs, corporate clients can optimize their financial operations, ensuring more efficient, accurate, and scalable management of their collections
Popular Use case
What can I do with this API ?
Product benefits
Assign unique virtual account numbers to clients for streamlined payment tracking and reconciliation.
Simplify the process of matching payments to invoices by using virtual accounts.
Manage recurring payments efficiently by assigning virtual accounts to subscribers.
Create virtual accounts for borrowers to track loan repayments, ensuring timely processing of payments.
Virtual Account Management
The client assigned unique virtual account numbers to property buyers and tenants for streamlined payment tracking and reconciliation.
Image
The client created virtual account number for their customers and transaction to streamline payment and enhance operational efficiency.
Image
Engage with us
Get started today or reach out to learn more.
Schedule a call with our team to understand how our offering can support you and your customers.