Page Comparison

...

Info
This endpoint is protected with OAuth 2.0 Bearer token. To find out more about authorization for Monnify endpoints, check Here.

Endpoint URL: {{base_url}}/api/v2/disbursements/single

...

Code Block

language	json

{
    "amount": 1020,
    "reference":"reference12934ben9-jlo00hdhdjjdfjoj--i",
    "narration":"911 TransactionTest01",
    "destinationBankCode": "035057",
    "destinationAccountNumber": "50001431152085096393",
    "currency": "NGN",
    "sourceAccountNumber": "8016472829",
    "destinationAccountName": "9624937372Marvelous Benji"
}

If the merchant does not have Two Factor Authentication (2FA) enabled, the transaction will be processed instantly and the response will be as follows:

...

Code Block

language	json

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "amount": 1020,
        "sessionIdreference": "090405220516131608508626806834ben9-jlo00hdhdjjdfjoj--i",
        "referencestatus": "reference12934SUCCESS",
        "statusdateCreated": "SUCCESS"2022-11-03T14:13:38.140+0000",
        "dateCreatedtotalFee": "13/11/2019 09:34:32 PM",
		"totalFee": 20.000.00,
        "sessionId": "090405221103151339936348270655",
       }
}

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

language	json

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "amount": 10,
        "reference": "reference12934",
        "status": "PENDING_AUTHORIZATION",
        "dateCreated": "13/11/2019 08:48:32 PM"
    }
}

...

Initiate Transfer (Single) Failed Disbursement Transaction Request

Code Block

language	json

{
    "amount": 10,
    "reference":"reference12934",
    "narration":"911 Transaction",
    "destinationBankCode": "044 "destinationAccountName": "Marvelous Benji",
        "destinationBankName": "Zenith bank",
        "destinationAccountNumber": "2085096393",
        "destinationBankCode": "057"
    }
}

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

language	json

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "amount": 20,
        "reference": "ben9-jlo00hdhdjjdfjoji",
        "status": "PENDING_AUTHORIZATION",
        "dateCreated": "2022-11-03T14:11:12.659+0000",
        "totalFee": 0.00,
        "destinationAccountName": "Marvelous Benji",
        "destinationBankName": "Zenith bank",
        "destinationAccountNumber": "2085096393",
        "destinationBankCode": "057"
    }
}

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

language	json

{
    "amount": 20,
    "reference":"ben9-jlo00hdhdjjdfjoji",
    "narration":"Test01",
    "destinationBankCode": "057",
    "destinationAccountNumber": "2085096393",
    "currency": "NGN",
    "sourceAccountNumber": "8016472829",
    "destinationAccountName": "Marvelous Benji"
}

The response will be as follows:

Initiate Transfer (Single) Failed Disbursement Transaction Response

Code Block

language	json

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "amount": 20,
        "reference": "ben900gg00-hhooooji",
        "status": "FAILED",
        "dateCreated": "2023-02-28T09:39:03.936+0000",
        "totalFee": 0.00,
        "destinationAccountName": "Marvelous Benji",
        "destinationBankName": "Zenith bank",
        "destinationAccountNumber": "2085886393",
        "destinationBankCode": "057",
        "comment": "You do not have sufficient balance to process this request. Please fund your account and try again."
    }
}

...

Processing Transfers Asynchronously

You can easily process transfer to your users asynchronously (by simply setting the “async” parameter to true in your request body) so that your server doesn’t have to wait for Monnify to get the final status of the transfer. When transfers are processed asynchronously, a pending status is returned in the response body, so we recommend that you have a disbursement webhook setup on your end(see here for setup; Webhooks) to receive the final status of the transfer. However you can also requery the transfer to check its status(Transfer Status).

Sample Request

Code Block

{
    "amount": 20,
    "reference":"a78c632b93",
    "narration":"Test01",
    "destinationBankCode": "057",
    "destinationAccountNumber": "2085096393",
    "currency": "NGN",
    "sourceAccountNumber": "8016472829",
    "destinationAccountName": "Marvelous Benji",
    "async":true
}

Sample Response

Code Block
{ "requestSuccessful": true, "responseMessage": "success", "destinationAccountNumberresponseCode": "00357854170", "currencyresponseBody": "NGN", "sourceAccountNumber": "9624937372" }

The response will be as follows:

Initiate Transfer (Single) Failed Disbursement Transaction Response

Code Block

language	json

{{
        "requestSuccessfulamount": true20,
        "responseMessagereference": "successa78c632b93",
        "responseCodestatus": "0PENDING",
      "responseBody": {  "dateCreated": "2023-03-17T14: 16: 45.499+0000",
        "amounttotalFee": 500.00,
        "referencedestinationAccountName": "ref1622802875358Marvelous Benji",
        "statusdestinationBankName": "FAILEDZenith bank",
        "dateCreateddestinationAccountNumber": "2021-06-04T10:34:38.269+00002085886393",
        "totalFeedestinationBankCode": 35.00"057"
    }
}

Bulk Transfers

To initiate a bulk transfer, you will need to send a request to the endpoint below:

...

Code Block

language	json

{
	"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",
			"destinationAccountName": "Benjamin Wilson",
	    	"destinationAccountNumber": "0111946768",
	    	"currency": "NGN"
    	},
		{
    		"amount": 570,
	    	"reference":"Final-Reference-2a",
	    	"narration":"911 Transaction",
	    	"destinationBankCode": "058",
			"destinationBankCodedestinationAccountName": "058Benjamin Wilson",
	    	"destinationAccountNumber": "0111946768",
	    	"currency": "NGN"
    	},
		{
    		"amount": 230,
	    	"reference":"Final-Reference-3a",
	    	"narration":"911 Transaction",
			"destinationAccountName": "Benjamin Wilson",
	    	"destinationBankCode": "058",
	    	"destinationAccountNumber": "0111946768",
	    	"currency": "NGN"
    	}

   	]
}

...

Status	Description
PENDING, AWAITING_PROCESSING and IN_PROGRESS	This response is gotten when transaction is still pending.
PENDING_AUTHORIZATION	This response is gotten if the merchant has 2FA enabled and authorization is needed for the disbursement to be initiated.
PENDING_BATCH_AUTHORIZATION	This response is gotten if merchant has 2FA enabled but the transaction is part of a batch.
OTP_EMAIL_DISPATCH_FAILED	This is very rare, but it happens when Monnify failed to send the OTP.
SUCCESS and COMPLETED	This response is gotten if the disbursement was successful.
REVERSED	This response is gotten if disbursement was reversed.
FAILED	This response is gotten when disbursement was not successful.
EXPIRED	A batch transaction has an expiry time. Once the transaction time has elapsed, you will get an EXPIRED responsebatch transaction has an expiry time. Once the transaction time has elapsed, you will get an EXPIRED response.
DUPLICATE REQUEST (D07)	This response is gotten when a transfer request is made to the same destination account with the same transaction amount within a 2 minutes interval.

...

Field Reference

^(M) indicates fields that are mandatory in the request body. ^(m) 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 destinationAcountNumber ^(M)	The beneficiary account number
destinationAccountName	The beneficiary account name. This will be used if provided, otherwise it will gotten via account number lookup
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.

...

Versions Compared

Old Version 19

New Version Current

Key

Initiate Transfer (Single) Response 2FA Enabled

Initiate Transfer (Single) Failed Disbursement Transaction Request

Initiate Transfer (Single) Response 2FA Enabled

Initiate Transfer (Single) Failed Disbursement Transaction Request

Initiate Transfer (Single) Failed Disbursement Transaction Response

Processing Transfers Asynchronously

Initiate Transfer (Single) Failed Disbursement Transaction Response

Bulk Transfers

Field Reference