Single Transfers
To initiate a single transfer, you will need to send a request to the endpoint below:
| Info |
|---|
This endpoint is protected with OAuth 2.0 Bearer token |
Endpoint
...
URL:{{base_url}}/api/v2/disbursements/single
...
This endpoint is protected with OAuth 2.0 Bearer Token
HTTP Method: POST
| Info |
|---|
The {{base_url}} for test is |
Below is a sample request for initiating a single transfer
...
...
Initiate Transfer (Single)
| Code Block | ||
|---|---|---|
| ||
{
"amount": 10,
"reference":"reference12934",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN",
"sourceAccountNumber": "9624937372"
} |
If the merchant does not have Two Factor Authentication (2FA) enabled, the transaction will be processed instantly and the response will be as follows:
...
...
Initiate Transfer (Single) Response 2FA Disabled
| Code Block | ||
|---|---|---|
| ||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 10,
"reference": "reference12934",
"status": "SUCCESS",
"dateCreated": "13/11/2019 09:34:32 PM",
"totalFee": 20.00
}
} |
If the merchant has Two Factor Authentication (2FA) enabled, a One Time Password (OTP) will be sent to the designated email address(es). That OTP will need to be supplied via the VALIDATE OTP REQUEST before the transaction can be approved. If 2FA is enabled, the response will be as follows:
...
...
Initiate Transfer (Single) Response 2FA Enabled
| Code Block | ||
|---|---|---|
| ||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 10,
"reference": "reference12934",
"status": "PENDING_AUTHORIZATION",
"dateCreated": "13/11/2019 08:48:32 PM"
}
} |
To simulate a failed disbursement transaction on the sandbox environment, you should use this destination account number: 0035785417 and destination bank code: 044. Here is a sample request:
...
...
Initiate Transfer (Single) Failed Disbursement Transaction Request
| Code Block | ||
|---|---|---|
| ||
{
"amount": 10,
"reference":"reference12934",
"narration":"911 Transaction",
"destinationBankCode": "044",
"destinationAccountNumber": "0035785417",
"currency": "NGN",
"sourceAccountNumber": "9624937372"
}
|
The response will be as follows:
...
Initiate Transfer (Single) Failed Disbursement Transaction Response
| Code Block | ||
|---|---|---|
| ||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 50.00,
"reference": "ref1622802875358",
"status": "FAILED",
"dateCreated": "2021-06-04T10:34:38.269+0000",
"totalFee": 35.00
}
} |
Bulk Transfers
To initiate a bulk transfer, you will need to send a request to the endpoint below:
| Info | ||
|---|---|---|
| ||
| POST: This endpoint is protected with OAuth 2.0 Bearer token |
Endpoint URL: {{base_url}}/api/v2/disbursements/batch
HTTP Method: POST
| Info |
|---|
The {{base_url}} for test is |
This endpoint is protected with Basic Authentication
but when you go live, it changes to the live url |
Bulk transfers allows you send a single request with a list of disbursements you want to be processed. Below is a sample request for initiating a bulk transfer
...
...
Initiate Transfer (Bulk)
| Code Block | ||
|---|---|---|
| ||
{
"title" : "Game of Batches",
"batchReference":"batchreference12934",
"narration":"911 Transaction",
"sourceAccountNumber": "9624937372",
"onValidationFailure" : "CONTINUE",
"notificationInterval": 10,
"transactionList" : [
{
"amount": 1300,
"reference":"Final-Reference-1a",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN"
},
{
"amount": 570,
"reference":"Final-Reference-2a",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN"
},
{
"amount": 230,
"reference":"Final-Reference-3a",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN"
}
]
} |
| Info |
|---|
When a bulk transfer request is sent, it is simply acknowledged by the system and then processed in the background. Monnify goes through each account to attempt to validate them and depending on what value is set for the onValidationFailure field, Monnify will either continue processing with the valid transfers or reject the entire batch. |
If the merchant does not have Two Factor Authentication (2FA) enabled, the transaction will be processed instantly and the response will be as follows:
...
...
Initiate Transfer (Bulk) Response 2FA Disabled
| Code Block | ||
|---|---|---|
| ||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"totalAmount": 2108.48,
"totalFee": 8.48,
"batchReference": "batch-1573681308355",
"batchStatus": "COMPLETED",
"totalTransactions": 3,
"dateCreated": "13/11/2019 09:42:06 PM"
}
} |
If the merchant has Two Factor Authentication (2FA) enabled, a One Time Password (OTP) will be sent to the designated email address(es). That OTP will need to be supplied via the VALIDATE OTP REQUEST before the transaction can be approved. If 2FA is enabled, the response will be as follows:
...
...
Initiate Transfer (Bulk) Response 2FA Enabled
| Code Block | ||
|---|---|---|
| ||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"totalAmount": 2108.48,
"totalFee": 8.48,
"batchReference": "batch-1573684027157",
"batchStatus": "PENDING_AUTHORIZATION",
"totalTransactions": 3,
"dateCreated": "13/11/2019 10:27:25 PM"
}
} |
...
Field Reference
(M) indicates fields that are mandatory in the request body. (m) Indicates Indicates fields that are mandatory only if the parent object is not empty.
Field | Description |
|---|---|
amount (M) | The amount to be disbursed to the beneficiary |
reference (M) | The unique reference for a transaction. Also to be specified for each transaction in a bulk transaction request. |
batchReference (M) | The unique reference for the entire batch of transactions being sent. |
narration (M) | The Narration for the transactions being processed |
bankCode (M) | The 3 digit bank code representing the destination bank |
accountNumber (M) | The beneficiary account number |
currency (M) | The currency of the transaction being initialised - "NGN" |
sourceAccountNumber (M) | Unique identifier of your wallet. Can be obtained on the disbursements page on the web portal and is represented as WALLET ACCOUNT NUMBER. |
onValidationFailure | Used to determine how Monnify should handle failed transaction validations in a batch. The two options are BREAK & CONTINUE. Use Break to tell Monnify to reject the entire batch and use CONTINUE to tell Monnify to process the valid transactions. |
notificationInterval | Used to determine how often Monnify should notify the merchant of progress when processing a batch transfer. The options are 10, 20, 50 and 100 and they represent percentages. i.e. 20 means notify me at intervals of 20% (20%, 40%, 60%, 80% ,100%). |
status | The status of a single transfer request. (SUCCESS, FAILED, PENDING, IN_PROGRESS, OTP_EMAIL_DISPATCH_FAILED, PENDING_AUTHORIZATION). A status of PENDING or IN_PROGRESS should NOT be treated as FAILED nor SUCCESS. Kindly do a requery to get the final status of the transfer. |
batchStatus | The status of the processing of the entire Batch. (FAILED_ON_ACCOUNTS_VALIDATION, OTP_EMAIL_DISPATCH_FAILED, PENDING, IN_PROGRESS, PENDING_AUTHORIZATION, AWAITING_PROCESSING, IN_PROGRESS ,COMPLETED) |
totalTransactions | The total number of transactions in the batch. |
totalAmount | The total amount deducted for all the transactions in the batch |
totalFee | The total transaction fees deducted for all the transactions in the batch. |
...
Response Codes
When a request is initiated, a response code is returned indicating what happened with initiated request. Please see table below describing how each response code should be handled.
Response Code | Description | Comment |
|---|---|---|
0 | Request was processed. | Please check transaction status in response body to ascertain status of the transaction. |
99 | An unexpected error occurred while processing transaction | Re-query to ascertain transaction status. |
D01 | Something went wrong and transaction could not be processed. Actual error message will be displayed in 'responseMessage' field. | Treat as FAILED. |
D02 | Transaction does not exist. | Treat as FAILED. |
D03 | Invalid account details supplied. | Treat as FAILED |
D04 | Insufficient wallet balance. | Treat as FAILED |
...
Related Articles
| Filter by label (Content by label) | ||||||
|---|---|---|---|---|---|---|
|