Payment Initiation | API Developer Portal

Corporate

Payment Initiation

Description

These APIs streamline the process, integrate with various platforms, and ensure compliance with regulations, enhancing convenience and efficiency in account-to- account, domestic fund transfers, and cross border fund transfers.

In order to subscribe, Please

Select plan

Default Plan

APIs

Title	Version	Type	Rate limits
Payment Initiation API	1.0.1	REST	100 calls per hour
POST /vendorPayment			100 calls per hour
GET /enquireTransaction			100 calls per hour

Overview
APIs Offered
Use Cases

Payment Initiation API

This API enables corporate to establish domestic money transfers, account-to-account transfers, and cross-border transfers for the vendor and inquire about any fund transfer that is done to the vendor. Both single and bulk transfers are supported.

Payment Initiation API

View API Specifications

NOTE:

This API offers 2 operation types namely vendorPayment and enquireTransaction.
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

Flow Chart

What operations can be performed?

1. vendorPayment: This is a POST method used to establish domestic money transfers, account-to-account and cross-border transfers for the vendor. Both single and bulk transfers are supported.

Request Headers:

Fields

Description

Mandatory/Optional

Data Type

Length

Sample Value

clientId

Unique client ID provided by Mashreq to corporate.

Mandatory

STRING

batchId

If there is only one transaction batchId becomes optional, you can also pass one transaction with batch details.

Conditional Mandatory

STRING

Min 1 - Max 16

batchCount

If there is only one transaction batchId becomes optional, you can also pass one transaction with batch details.

Conditional Mandatory

STRING

Min 0 - Max 1000

Authorization

Bearer Token received from get token API with respect to Scope

Mandatory

STRING

Request Parameters:

Fields

Description

Domestic Fund Transfers

Account to Account Transfers

Cross Border Transfers

Length

Data Type

Sample Value

cifNumber

Unique CIF number

Mandatory

Max 9

STRING

transactionDetails

List of transaction details block

Mandatory

Max 1000

STRING

All transactions will fall under array, and it would repeat for every new transaction

Mandatory

[

STRING

debitAccountNumber

Debit account number

Mandatory

Min12 - Max23

STRING

customerReference

Unique Customer reference number

Mandatory

Min1 - Max 16

STRING

valueDate

YYYY-MM-DD is the format

Mandatory

STRING

paymentCurrency

Payment currency is AED for domestic transactions and can be any for cross-border transfer

Mandatory

STRING

paymentAmount

Payment amount

Mandatory

Min1 - Max15

STRING

payby

D = Pay by debit acc currency, P = Pay by paymentCurrency

Optional

STRING

beneAccountNumber

Beneficiary account number

Mandatory

STRING

beneName

Beneficiary Name

Mandatory

Min1 - Max140

STRING

beneSwiftCode

Beneficiary SWIFT CODE

Optional

Mandatory

Min8 - Max11

STRING

beneAddress

Beneficiary address

Mandatory

Min1 - Max105

STRING

beneEmail

Beneficiary Email

Optional

255

STRING

purposeCode

Purpose of code for local transfer is mandatory

STRING

purposeOfPaymentAddInfo

Additional Purpose of payment

Mandatory

Optional

Mandatory

STRING

chargeType

BEN\SHA\OUR

STRING

ChargeAccountNumber

Specific account number for charges

Optional

Min12 - Max23

STRING

dealRefNo

Deal reference number compulsory if it's a deal tranx

Optional

STRING

dealrate

Deal rate can be blank but ensure deal reference number is there.

Optional

STRING

dealDate

Deal date can be blank but ensure deal reference number is there.

Optional

STRING

routing

Is used to input routing information if the BIC is not mentioned then the routing is mandatory.

Optional

Conditional Mandatory

STRING

End of array, you can repeat the array for new transactions

Mandatory

]

STRING

Response Parameters:

Fields

Description

Mandatory/Optional

Data Type

Length

Sample Value

requestStatus

Shows the status of transaction as soon as transaction is initiated

Mandatory

message

Returns narration of actual reason of transaction.

Mandatory

msBatchRefNo

Once bank receives the batch request transaction it assigns or generate a batch number to the request.

Mandatory

batchId

Unique batch Id passed by the corporate\client.

Mandatory

STRING

transactionsStatus

List of transaction details block

Mandatory

transactionsDate

Date of transaction initiation

Mandatory

STRING

2024-02-22

All transactions will fall under array, and it would repeat for every new transaction

[

Status

Transaction status

Mandatory

STRING

INITIATED

customerReference

Document reference Or ERP id.

Mandatory

STRING

Min1 - Max16

sampleCustRef1

msTxnRefNo

Transaction reference

Mandatory

STRING

Max16

MSeb1234567890ad

bankRefNo

Bank reference number will be visible only in inquiry API call after processing the transaction

Mandatory

STRING

Max16

9999888877776666

uetr

Unique electronic transaction ref

Optional

STRING

Max36

description

Description displays

Mandatory

STRING

Transaction Request has been initiated

isFinalStatus

It can be Y or N. Y = No further status of transaction is expected Transaction is concluded. N = Transaction is still in transit and status is expected to change.

Mandatory

Min1

End of array

]

Status Code Information:

Status code

Status

Description

200

INITIATED

Transaction request initiated

400

REJECTED

Transaction rejected due to invalid request.

401

REJECTED

Transaction rejected due to Unauthorized user

500

FAILED

Failed to initiate transaction due to internal sever error, Please try after sometime.

400

REJECTED

INVALID_CIF_NUMBER

400

REJECTED

INVALID_DEBIT_ACCOUNT_NUMBER

400

REJECTED

INVALID_CUSTOMER_REFERENCE

400

REJECTED

INVALID_VALUE_DATE

400

REJECTED

INVALID_CURRENCY

400

REJECTED

INVALID_AMOUNT

400

REJECTED

INVALID_PAY_BY

400

REJECTED

INVALID_BENE_IBAN_NUMBER

400

REJECTED

INVALID_BENE_NAME

400

REJECTED

INVALID_BENE_SWIFT_CODE

400

REJECTED

INVALID_BENE_ADDRESS

400

REJECTED

INVALID_BENE_EMAIL

400

REJECTED

INVALID_PURPOSE_CODE

400

REJECTED

INVALID_PURPOSE_CODE_ADD_INFO

400

REJECTED

INVALID_CHARGE_TYPE

400

REJECTED

INVALID_CHARGE_ACCOUNT_NUMBER

400

REJECTED

No Accounts mapped for this user

400

REJECTED

INVALID_BENE_IBAN_NUMBER

401

REJECTED

API Banking is not enabled for this user

2. enquireTransaction: This service is used to inquire a domestic funds transfer transaction for the vendor. This is a GET method.

Request Headers:

Fields

Description

Mandatory/Optional

Data Type

Length

Sample Value

clientId

Unique client ID provided by Mashreq to corporate.

Mandatory

STRING

batchId

If there is only one transaction batchId becomes optional, you can also pass one transaction with batch details.

Conditional Mandatory

STRING

Min 1 - Max 16

batchCount

If there is only one transaction batchId becomes optional, you can also pass one transaction with batch details.

Conditional Mandatory

STRING

Min 0 - Max 1000

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

batchId

Unique batch Id passed by the corporate\client.

Conditional

msBatchRefNo

Batch reference number assigned by the bank

Conditional

cifNumber

Unique CIF number

Mandatory

STRING

10150935

customerReference

Unique Customer reference number

Conditional

STRING

Min1 - Max16

Test1234

msTxnRefNo

Transaction reference

Conditional

Max 16

Response Parameters:

Fields

Description

Mandatory/Optional

Data Type

Length

Sample Value

requestStatus

Shows the status of transaction as soon as transaction is initiated

Mandatory

message

Returns narration of actual reason of transaction.

Mandatory

msBatchRefNo

Once bank receives the batch request transaction it assigns or generate a batch number to the request.

Mandatory

batchId

Unique batch Id passed by the corporate\client.

Mandatory

STRING

transactionsStatus

List of transaction details block

Mandatory

transactionsDate

Date of transaction initiation

Mandatory

STRING

2024-02-22

All transactions will fall under array, and it would repeat for every new transaction

[

Status

Transaction status

Mandatory

STRING

COMPLETED

customerReference

Document reference Or ERP id.

Mandatory

STRING

Min1 - Max16

sampleCustRef1

msTxnRefNo

Transaction reference

Mandatory

STRING

Max16

MSeb1234567890ad

bankRefNo

Bank reference number will be visible only in inquiry API call after processing the transaction

Mandatory

STRING

Max16

9999888877776666

uetr

Unique electronic transaction ref

Optional

STRING

Max36

description

Description displays

Mandatory

STRING

Payment request has been completed

isFinalStatus

It can be Y or N. Y = No further status of transaction is expected Transaction is concluded.

N = Transaction is still in transit and status is expected to change.

Mandatory

Min1

End of array

]

Status Code Information:

Status code

Status

Description

200

INITIATED

Transaction request has been initiated and under processing.

200

COMPLETED

Payment request has been completed.

400

REJECTED

Payment request has been rejected. Please contact customer service unit.

400

REJECTED

Invalid transaction inquiry, customer reference not available.

401

REJECTED

Enquiry Rejected due to Unauthorised user

500

FAILED

Failed to retrieve transaction status due to internal server error, please try after some time.

401

REJECTED

API Banking is disabled for this user

IMPORTANTS NOTES:

The UETR reference number may not appear upfront in the initial response when the transactions are initiated; it may appear during the inquiry call.
UETR reference is not available for account-to-account transactions.
“isFinalStatus” 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 the transaction is still in transit and the status update is expected to change.

Region specific clearing

UAEFTS

No specific threshold.

IPP

AED amount under threshold of 50k.

SWIFT

FCY currency payments no specific threshold

QATCH

QAR amount under threshold of 50 Million.

RTGS

QAR amount Above threshold of 50 Million.

FAWRAN

QAR amount under to 500000.

SWIFT

FCY currency payments no specific threshold

FAWRI

No specific threshold.

SWIFT

FCY currency payments no specific threshold

View API Specifications

Number of API/s

Number of APIs

APIC Calls

320

Calls per month

Active users

360

Active users

Regions

Overview

Corporate Payment Initiation is a powerful tool that enables businesses to initiate and manage payments directly from their internal systems or ERPs, such as Instant Payment (up to AED 50,000), Domestic Fund Transfers, Account-to-Account Transfers, and Cross Border Fund Transfers.

What are the benefits?

Real-Time Processing
Execute payments instantly, improving cash flow management and financial planning.
Automation and Efficiency
Automate payment workflows to reduce manual intervention, minimize errors, and save time.
Cost Savings
Lower operational costs by reducing the need for manual or cheque based payment and reconciliation.
Enhanced Security
Utilize advanced security features to protect sensitive financial data and ensure compliance with regulatory standards.
Scalability
Easily scale payment operations to accommodate business growth and changing needs.
Improved Cash Flow Management
Gain better control and visibility over cash flows, enabling more effective financial management.

Which APIs are offered?

Payment Initiation API: This API enables corporate to establish domestic money transfers, account-to-account transfers, and cross-border transfers for the vendor and inquire about any fund transfer that is done to the vendor. Both single and bulk transfers are supported.

By harnessing Mashreq’s Payment Initiation APIs, businesses can significantly enhance their financial operations, ensuring smoother, faster, and more secure payment processes

What can I do with this API ?

icon

Product benefits

Facilitate instant transfers between your business accounts and speed up book transfers.

Streamline the process of paying vendors, reducing delays and improving supplier relationships.

Simplify cross-border transactions, ensuring quick payments, compliant with international standards.

Manage large volumes of payments efficiently with bulk support for Payment Initiation.

Payment Initiation

Engage with us

Get started today or reach out to learn more.

Get Started

Schedule a call with our team to understand how our offering can support you and your customers.

Schedule a call