Corporate
Virtual Account Entry Update
Description
These APIs enable corporate clients to update and inquire about the entry of credit information into one or more virtual accounts using their associated virtual account numbers. These APIs support bulk entry.
- Overview
- APIs Offered
- Use Cases
- 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
- msBatchreferencenumber
- TransactionReferencenumber
- From & To date
- Batch ID
- TransactionReferencenumber
- From & To date
- msBatchreferencenumber
- Batch id
- Transaction Reference Number
- One of above 4 field is mandatory
- If to date is provided from date is mandatory
- Bulk support is against one CIF ID i.e. multiple entries can be updated in one batch referring to a single CIF.
- You may have to initiate a new batch for a different CIF.
- For enquiry CIF and Batch id mandatory.
Virtual Account Entry Update API
This API allows the customer to make a manual credit entry into one or more associated virtual accounts using the virtual account numbers and inquire about the status of update.
Virtual Account Entry Update API
View API Specifications
This API allows the customer to make a manual credit entry into one or more associated virtual accounts using the virtual account numbers and inquire about the status of update.
NOTE:
Flow Chart
Image
What operations can be performed?
1. initiateVirtualAccountEntries: This POST method allows the customer to make a manual credit entry into one or more associated virtual accounts using the virtual account numbers.
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
clientId
Unique client ID provided by Mashreq to corporate.
Mandatory
STRING
Max 9
10150935
batchId
Unique batch reference number which client can input single of multiple requests
Mandatory
STRING
Max 16
virtualAccountRequestEntriesDtos
Contains array of requests with CIF level list, should have at least one request to process.
Mandatory
virtualAccount
Virtual account number that needs to be updated with the entry
Mandatory
STRING
Max 12
drCrInd
Entry update can be Credit or Debit respective prefixes are "C" for credit "D" for Debit
Mandatory
STRING
Min 1 - Max 16
C or D
amount
Amount that needs to be updated as entry in the virtual account.
Mandatory
STRING
txnDesc
It can be any description related to the entry.
Mandatory
STRING
Max 4
COBO
valueDate
Date when the entry is being made
Mandatory
STRING
Max 12
2024-11-14
currency
Currency of the transaction in which the posting is done
Mandatory
STRING
Min 1 - Max 15
125.50
txnReferenceNo
Any reference for the transaction number duplication check on this.
Response Parameters:
Fields
Description
Mandatory/Optional
Data type
Length
Sample value
statusCode
This http status is at the batch level.
Mandatory
STRING
Max 20
status
Description of the status of transaction at batch level
Mandatory
STRING
ALL_TRANSACTIONS_INITIATED
description
Detailed description at the transaction level.
Mandatory
STRING
batchId
Unique reference number input during the initiation time is returned as part of response.
Mandatory
STRING
msBatchReference
System reference number generated at the batch level by the bank
Mandatory
STRING
Max 16
vaResponseList
Array starts from this prefix
Mandatory
STRING
Max 16
msTxnReferenceNo
Unique reference number generated by the system at transaction level
Mandatory
STRING
Max 16
txnReferenceNo
Reference entered during the initiation is returned as part of response as well.
Mandatory
STRING
Max 16
virtualAccNumber
Virtual account number updated for the entry.
Mandatory
STRING
Max 16
txnDesc
Description entered during the VA entry initiation is returned as part of response as well.
Mandatory
STRING
Max 16
valueDate
Date when the entry is being made
Mandatory
STRING
Max 12
2024-11-14
drCrInd
Entry update can be Credit or Debit respective prefixes are "C" for credit "D" for Debit
Mandatory
STRING
Max 4
amount
Amount that needs to be updated as entry in the virtual account is returned as part of response as well.
Mandatory
STRING
Max 12
currency
Currency of the transaction in which the posting is done
Mandatory
STRING
Min 1 - Max 15
status
Since this is a initial response which verify the syntax and returns value as "Initiated" at the transaction level.
Mandatory
STRING
statusCode
It contains http at transaction level.
Mandatory
STRING
description
Description information at each transaction level.
Mandatory
STRING
Max 10
Status Code Information:
Field
Error
Error Description
Error Code
Input is empty
Multiple Client ids found
403
Client ID
Input is "Null"
Invalid client id or secret
401
Invalid / "Non onboarded"
Cannot pass the security checks that are required by the target API or operation. Enable debug headers for more details.
401
Input is empty
Cannot pass the security checks that are required by the target API or operation. Enable debug headers for more details.
401
Secret Code
Input is "Null"
Cannot pass the security checks that are required by the target API or operation. Enable debug headers for more details.
401
Invalid
Cannot pass the security checks that are required by the target API or operation. Enable debug headers for more details.
401
Input is "Null" / empty
CIF is mandatory
400
CIF
Invalid / "Non onboarded"
Unauthorized user access
401
Input is "Null" / empty
Batch id is mandatory
400
Batch id
Input is "duplicate"
Duplicate Batch ID
400
Input has more than 16-digits
Maximum length allowed is 16 digits Alphanumeric
400
Input is "Null" / empty
VA is mandatory
400
VA
Input has more than/ less than 12 digits
VA Maximum length is 12
400
Input is in Alphabetic/Alphanumeric format
Allowed value is Numeric
400
Input is "Null" / empty
Transaction Description cannot be Empty or Null
400
Transaction Description
Input has more than 105 digits
Maximum length is 105 characters for Transaction Description
400
Input is "Null" / empty
Date value is mandatory
400
Input is Future Date Value
Future date value is not accepted
400
Value Date
Input date value is more than configured days
Invalid date value
400
Invalid date value format
Incorrect date format.
400
Input is "Null" / empty
Credit/Debit Indicator can not be Empty or 'Null'
400
Input is in Special character format
Credit/Debit Indicator value can be 'D' / 'C'
400
Debit Credit Indicator
Input is in Alphanumeric format
Credit/Debit Indicator value can be 'D' / 'C'
400
Input is in Lower Case format
Credit/Debit Indicator value can be 'D' / 'C'
400
Input is "Null" / empty
Amount cannot be empty or 'Null'
400
Amount
Input has more than 25 digits
Maximum length allowed for Amount is 25 digit
400
Input is in Alphabetic/Alphanumeric format
Amount value should be Numeric or Decimal
400
Input has more than/less than 3 Characters
Length should be 3 characters for Currency
400
Currency
Input is other than VA currency
Currency is invalid
400
Input is in Alphanumeric format
Length should be 3 characters for Currency
400
Input is "Null" / empty
Transaction Reference cannot be Empty or Null
400
Transaction Reference
Input has more than 16 digits
maximum length allowed is 16 digits. Input should be Alphanumeric
400
2. virtualAccountEntriesEnquiry: This GET service enables the customer to make an inquiry request about the manual credit entry status in one or more virtual accounts associated with them.
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
cif
Unique client ID provided by Mashreq to corporate.
Mandatory
STRING
Max 9
batchId
Unique batch Id passed by the corporate\client.
Conditional
STRING
Max 16
Conditional Mandatory with below:
Note: One of above 4 field is mandatory
virtualAccount
Batch reference number assigned by the bank
Optional
STRING
Max 12
msBatchReference
Unique Reference Number generated by MS at batch level
Conditional
STRING
Max 16
Conditional Mandatory with below:
Note: One of above 4 field is mandatory
fromDate
Starting date range
Mandatory
STRING
Max 10
Conditional Mandatory with below:
Note:
toDate
Ending date range
Conditional
STRING
Max 10
drcrInd
drCrInd for debit or credit Indication
Optional
STRING
Max 1
msreferenceNumber
Unique Reference Number generated by MS at batch level
Optional
STRING
Max 16
txnReferenceNo
Transaction Reference Number entered by Customer in VA Entry Update API
Conditional
STRING
Max 16
operatingAccount
Physical account of the virtual account
Optional
STRING
Max 12
Response Parameters:
Fields
Description
Mandatory/Optional
Data type
Length
Sample value
statusCode
Captures the http status code
Mandatory
STRING
status
VA entry update status
Mandatory
STRING
description
It displays status the batch level
Mandatory
STRING
cif
Customer information number assigned by the bank.
Mandatory
STRING
batchId
Unique reference number at the file level.
Mandatory
STRING
msBatchReference
Batch reference number will be generated by the system
Mandatory
STRING
SourceReferenceNo
Reference number from the source system.
Mandatory
STRING
vaResponseList
Contains array of requests with CIF level list, should have at least one request to process.
Mandatory
STRING
Max 16
msTxnReferenceNo
Reference number initiated from the system
Mandatory
STRING
Max 16
txnReferenceNo
Reference number entered during update of VA entry
Mandatory
STRING
Max 16
virtualAccnumber
VA number used for the entry update.
Mandatory
STRING
Max 12
2024-11-14
realAccNumber
Physical account number underneath which VA gets created.
Mandatory
STRING
Max 12
payerId
Text information entered by the client
Mandatory
STRING
txnDesc
It is the description information entered during initiation by corporate
Mandatory
STRING
Max 105
valueDate
This is the date when transaction was initiated
Mandatory
STRING
Max 12
drCrInd
It returns the value C or D as per the transaction that takes place
Mandatory
STRING
Max 25
amount
Amount to be updated in the request for VA update
Mandatory
STRING
Max 3
currency
Currency of the amount
Mandatory
STRING
status
Transaction status
Mandatory
STRING
statusCode
Http Transaction status code
Mandatory
STRING
description
Returns the narration of the status.
Mandatory
STRING
IMPORTANTS NOTES:
Number of API/s
1
Number of APIs
APIC Calls
160
Calls per month
Active users
250
Active users
Regions
Overview
Overview
Mashreq’s Virtual Account Entry Update APIs are customer-exclusive APIs that are used to manually update and inquire about credit information in customer associated virtual accounts if there is a delay in updating information. This feature is designed to boost customer responsiveness.
Which APIs are offered?
- Virtual Account Entry Update API: This API provides the customer to make a manual credit entry into one or more associated virtual accounts using the virtual account numbers and inquire about the status of update.
NOTE: Virtual Account Entry Update APIs are customer-exclusive APIs that required additional approval from back office to subscribe
By utilizing Mashreq’s Virtual Account Entry Update APIs, businesses can manually insert the credit information entry into one or more associated virtual accounts, ensuring timely and accurate financial reporting and reconciliation
Popular Use case
What can I do with this API ?
Product benefits
Automate the reconciliation of bank statements with corporate financial records.
Monitor cash flows, helping businesses manage liquidity and optimize financial planning.
Generate accurate and timely financial reports for internal and external stakeholders.
Simplify auditing and ensure compliance with financial regulations with industry standard financial statements.
Virtual Account Entry Update
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.