Search..

API Reference

Learn how to integrate Monnify APIs into your applications.


Introduction

The Monnify API provides extensive access to the features available on our dashboard, enabling you to leverage them for your own application. To get started, you must first create a Monnify account on www.monnify.com and obtain the required API keys for all Monnify integrations. Please note that the Monnify API is secured through Basic Authentication or OAuth (Bearer Tokens).

Authentication

Monnify's core security protocol is OAuth 2.0, which authenticates API requests via associated API keys that can be managed directly from the dashboard. Monnify provides an API key, that is used together with a secret key to generate a basic token and a secret key that should be kept confidential and stored exclusively on...Read more


Webhooks

Webhooks is an API concept that enables applications to automatically communicate with each other without constant polling. Monnify integration sends ...Read more

Monnify Webhook Events and Structure

As part of the Monnify integration, notifications are automatically sent to your system when certain actions are completed. These notifications trigger corresponding activities on your system, and you can specify URLs for certain activities on your integration. The notifications include an event-type property that indicates what action has taken place, as well as event data containing details of the event.

Supported notification event types on Monnify include

  1. Successful Collection (for successful payments made on your account)
    ...Read more
  2. Successful Disbursement (for disbursement transactions with a successful definite status)
    ...Read more
  3. Failed Disbursement (for failed disbursement transactions)
    ...Read more
  4. Successful Refund (for successfully processed initiated refunds)
    ...Read more
  5. Failed Refund (for failed initiated refunds)
    ...Read more
  6. Settlement Completion (for successfully processed settlements to your bank account or wallet)
    ...Read more
  7. Completed Oflline Payments
    ...Read more
  8. Notification for Rejected Payments
    ...Read more


Structure and Sample

A typical event notification structure is of the format:

Sample event notification structure
Copy button
{
"eventType": "type_of_event",
"eventData": {
"prop1": "value1",
"prop2": "value2"
}
}

Transaction Hash Computation

As a security measure, Monnify computes a hash of the request body whenever it sends a notification and includes it in the request header with the key...Read more


Javascript, PHP, Java Sample Codes:

Expand to see Sample codes on how to compute Transaction Hash in Javascript, PHP, Java etc....Read more


Going Live

After successfully uploading necessary documents and meeting compliance requirements, your Monnify account will be activated, and you will be ready to go live. However, before doing so, it is important to check that certain components are properly set up to ensure smooth payment collection, communication between Monnify and your business, and communication between your customers and your business.

Seamless Payment Collection And Notification

This guide will outline the necessary steps for setting up seamless payment collection and notification through the use of webhook URLs on your Monnify dashboard...Read more


Disabling OTP API Disbursement And IP Whitelisting

If your application is planning to integrate our disbursement API, it is advisable to disable the sending of OTP to your business email when customers initiate a withdraw...Read more

Switching From Monnify Sandbox To Live Mode

It's recommended that you change all your Monnify sandbox credentials to their respective live credentials when going live. This includes the Monnify Sandbox base_url, API Key and Secret, and Contract Code.



Authentication

Generate Access Token

POST
{{base_url}}/api/v1/auth/login


Headers

Authorization
basic
Authorize this API call by including Authorization header that contains the word 'Basic' followed by a space and a base64-encoded string 'apiKey:clientSecret' i.e. 'Basic base64(ApiKey:SecretKey)', include the Token in the request header.

Body Params

REQUEST
Copy button
curl --header "Content-Type: application/json"
--request POST
--data '{}'
{{sandbox_url}}/api/v1/auth/login
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibW9ubmlmeS12YWx1ZS1hZGRlZC1zZXJ2aWNlIiwibW9ubmlmeS1wYXltZW50LWVuZ2luZSIsIm1vbm5pZnktZGlzYnVyc2VtZW50LXNlcnZpY2UiLCJtb25uaWZ5LW9mZmxpbmUtcGF5bWVudC1zZXJ2aWNlIl0sInNjb3BlIjpbInByb2ZpbGUiXSwiZXhwIjoxNjU4MjIwNTk1LCJhdXRob3JpdGllcyI6WyJNUEVfTUFOQUdFX0xJTUlUX1BST0ZJTEUiLCJNUEVfVVBEQVRFX1JFU0VSVkVEX0FDQ09VTlQiLCJNUEVfSU5JVElBTElaRV9QQVlNRU5UIiwiTVBFX1JFU0VSVkVfQUNDT1VOVCIsIk1QRV9DQU5fUkVUUklFVkVfVFJBTlNBQ1RJT04iLCJNUEVfUkVUUklFVkVfUkVTRVJWRURfQUNDT1VOVCIsIk1QRV9ERUxFVEVfUkVTRVJWRURfQUNDT1VOVCIsIk1QRV9SRVRSSUVWRV9SRVNFUlZFRF9BQ0NPVU5UX1RSQU5TQUNUSU9OUyJdLCJqdGkiOiJhZmYwMTMyMi1kMmNmLTQzOGYtYWVkMC0wOGY0NTBhNmVhZWYiLCJjbGllbnRfaWQiOiJNS19URVNUX0pSUUFaUkZEMlcifQ.KOkMyFJIMKc6aZViDB3ekoiCPU2647eW_1RpySy9t_OXzfDSER2nn2QzXZsGPn8GlPJ4ZdhtuhevHQCLnEKQYIScgB9EQTPHTldiBG7uf9ta3NQK6Sxzq2pkM8heuO1v87tqtPLbBF7LlmI21liUPAPrxJVnw5PhCAOKbInIG-sj0BWbwMXJ2E8Cgz6yUeQ46-C0bmkyc0U6-FqENPSNl7oNXNY-nWaQfXd7tw2ybE4YoEzoRXcLTy0KLjlf3sxA5PizyT3nh9YqjVIRli-3sggnpvdjmIzw8784g_knNYmA8rj1Of7ROa_enDYmH6dWHbB1luchU9Y67FMhlBDWLg",
"expiresIn": 3567
}
}

Transactions

Initialize Transaction

This endpoint initialises the transaction that would be used for card payments and dynamic transfers.
POST
{{base_url}}/api/v1/merchant/transactions/init-transaction


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

amount
Float

The amount(in Naira) to be paid, minimum is N20

customerName
String

The name of the customer

customerEmail
String

The customer email

paymentReference
String

A unique string of characters that identifies each transaction

paymentDescription
String

A description of the payment

currencyCode
String

The currency code

contractCode
String

The merchant contract code

redirectUrl
String

A url to redirect to after payment completion

paymentMethods
String

The method of payment collection

incomeSplitConfig
Object

A way to split payments among subAccounts.

metadata
Object

This field can be used to pass extra information from customers

REQUEST
Copy button
{
"amount": 100.00,
"customerName": "Stephen Ikhane",
"customerEmail": "[email protected]",
"paymentReference": "123031klsadkad",
"paymentDescription": "Trial transaction",
"currencyCode": "NGN",
"contractCode":"32904822812",
"redirectUrl": "https://my-merchants-page.com/transaction/confirm",
"paymentMethods":["CARD","ACCOUNT_TRANSFER"]
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"transactionReference": "MNFY|20190915200044|000090",
"paymentReference": "1568577644707",
"merchantName": "Test Limited",
"apiKey": "MK_TEST_VR7J3UAACH",
"enabledPaymentMethod": [
"ACCOUNT_TRANSFER",
"CARD"
],
"checkoutUrl": "https://sandbox.sdk.monnify.com/checkout/MNFY|20190915200044|000090"
}
}

Pay With Bank Transfer

This endpoint generates a dynamic account number and its associated bank for one time payment.
POST
{{base_url}}/api/v1/merchant/bank-transfer/init-payment


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

transactionReference
String

A unique Monnify reference returned as part of the response from the initialise transaction endpoint

bankCode
String

A valid bank code to enable the creation of USSD string associated with such bank

REQUEST
Copy button
{
"transactionReference": "MNFY|24|20220721134824|000081",
"bankCode": "058"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"accountNumber": "5000610089",
"accountName": "Test01-Tri",
"bankName": "Wema bank",
"bankCode": "035",
"accountDurationSeconds": 2309,
"ussdPayment": "*737*2*100.00*5000610089#",
"requestTime": "2022-07-21T13:52:31",
"expiresOn": "2022-07-21T14:32:31",
"transactionReference": "MNFY|24|20220721134824|000081",
"paymentReference": "123---03--1klsa--dkad",
"amount": 100,
"fee": 10,
"totalPayable": 100,
"collectionChannel": "API_NOTIFICATION",
"productInformation": null
}
}

Charge Card

This endpoint allows you to initiate charge on a card.
POST
{{base_url}}/api/v1/merchant/cards/charge


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

transactionReference
String

The transaction reference gotten as part of the response from the initialise transaction endpoint.

collectionChannel
String

This field basically describes the channel of collection.

card
Object

An object containing the card information.

number
String

The card pan or number on the card.

pin
String

The pin associated with the card.

expiryMonth
String

The card expiry month.

expiryYear
String

The card expiry year

cvv
String

The card cvv number.

REQUEST
Copy button
{
"transactionReference": "MNFY|99|20220725110839|000256",
"collectionChannel": "API_NOTIFICATION",
"card": {
"number": "4111111111111111",
"expiryMonth": "10",
"expiryYear": "2022",
"pin": "1234",
"cvv": "123"
}
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"status": "SUCCESS",
"message": "Transaction Successful",
"transactionReference": "MNFY|99|20220725110839|000256",
"paymentReference": "12-3---03--1klsa--dkad",
"authorizedAmount": 100
}
}

Authorize OTP

The endpoint authorizes an OTP to complete a charge on a card.
POST
{{base_url}}/api/v1/merchant/cards/charge


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

transactionReference
String

The transaction reference gotten from the initialise transaction endpoint.

collectionChannel
String

This is the channel of collection and should always be "API_NOTIFICATION" in this endpoint.

tokenId
String

This is an id of the token issued and is always part of the response from the charge card endpoint.

token
String

This is the token(OTP) sent to the user device by his bank

REQUEST
Copy button
{
"transactionReference": "MNFY|20190512185357|000002",
"collectionChannel": "API_NOTIFICATION",
"tokenId": "1234567890",
"token": "123456"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"status": "SUCCESS",
"message": "Transaction Successful",
"transactionReference": "MNFY|54|20210429142945|000208",
"paymentReference": "1619702984105",
"authorizedAmount": 2000
}
}

Authorize 3DS Card

This endpoint authorizes charge on a card that uses 3DS Secure Authentication.
POST
{{base_url}}/api/v1/sdk/cards/secure-3d/authorize


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

transactionReference
String

The transaction reference gotten from the initialise transaction endpoint.

collectionChannel
String

This is the channel of collection and should always be "API_NOTIFICATION" in this endpoint.

card
Object

An object containing the card information.

number
String

The card pan or number on the card.

pin
String

The pin associated with the card.

expiryMonth
String

The card expiry month.

expiryYear
String

The card expiry year

cvv
String

The card cvv number.

apiKey
String

The merchant API key

REQUEST
Copy button
{
"transactionReference": "MNFY|19|20210430115705|000243",
"collectionChannel": "API_NOTIFICATION",
"card": {
"cvv": "123",
"expiryMonth": "12",
"expiryYear": "2022",
"number": "4000000000000002",
"pin": "1234"
}
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"status": "BANK_AUTHORIZATION_REQUIRED",
"message": "3D Secure Authorization required",
"secure3dData": {
"id": "2000.00-59077a3e5157fae7ca9dd260d911ccbb",
"redirectUrl": "http://localhost:10001"
},
"transactionReference": "MNFY|19|20210430115705|000243",
"paymentReference": "1619780224192",
"authorizedAmount": 1000
}
}

Get All Transactions

This endpoint returns a list of transactions carried out on your integration.
GET
{{base_url}}/api/v1/transactions/search


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

page
Integer

The number of page of to be retrieved. It starts from 0.

size
Integer

The Size of transactions to be returned per page.

paymentReference
String

Unique reference generated by merchant for each transaction.

transactionReference
String

Unique transaction reference generated by Monnify for each transaction

fromAmount
Float

A number indicating minimum amount for the transactions to be returned

toAmount
Float

A number indicating maximum amount for the transactions to be returned

amount
Float

A number indicating exact amount for the transactions to be returned

customerName
String

Name of customer for the transactions to be returned

customerEmail
String

Email of customer for the transactions be returned.

paymentStatus
String

Transaction status for transactions to be returned

from
Timestamp

Time for transactions to be retrieved.

to
Timestamp

The maximum time for transactions to be retrieved.

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v1/transactions/search?
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"createdOn": "2022-07-25T11:53:52.000+0000",
"amount": 100,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-25T12:30:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|99|20220725125351|000271",
"paymentReference": "12__0-3-031k^^ls0a--dk--ad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T11:26:29.000+0000",
"amount": 100,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-25T12:00:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|65|20220725122629|000296",
"paymentReference": "12__0-3-031kls0a--dk--ad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T11:14:09.000+0000",
"amount": 100,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-25T11:50:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|65|20220725121408|000291",
"paymentReference": "12__0-3-031kls0a--dkad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T10:48:27.000+0000",
"amount": 100,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-25T11:20:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|67|20220725114827|000285",
"paymentReference": "120-3-031kls0a--dkad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T10:43:51.000+0000",
"amount": 100,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-25T11:20:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|65|20220725114351|000289",
"paymentReference": "12-3-031kls0a--dkad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T10:41:50.000+0000",
"amount": 100,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-25T11:20:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|67|20220725114150|000284",
"paymentReference": "12-3---031kls0a--dkad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T10:19:58.000+0000",
"amount": 100,
"flagged": false,
"fee": 10,
"currencyCode": "NGN",
"completedOn": "2022-07-25T10:20:20.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "PAID",
"transactionReference": "MNFY|67|20220725111957|000283",
"paymentReference": "12-3---03--1kls0a--dkad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"payableAmount": 100,
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "CARD",
"createdOn": "2022-07-25T10:08:39.000+0000",
"amount": 100,
"flagged": false,
"fee": 10,
"currencyCode": "NGN",
"completedOn": "2022-07-25T10:09:23.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "PAID",
"transactionReference": "MNFY|99|20220725110839|000256",
"paymentReference": "12-3---03--1klsa--dkad",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"payableAmount": 100,
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"paymentMethod": "ACCOUNT_TRANSFER",
"createdOn": "2022-07-22T13:23:39.000+0000",
"amount": 20,
"flagged": false,
"fee": 10,
"currencyCode": "NGN",
"completedOn": "2022-07-22T13:29:13.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "PAID",
"transactionReference": "MNFY|24|20220722142339|000144",
"paymentReference": "13i--0-00--lfuik93j",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"payableAmount": 20,
"completed": true,
"paymentMethodList": [
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Stephen Ikhane",
"merchantCode": "1X1SDUSYRD47"
},
"createdOn": "2022-07-22T13:22:57.000+0000",
"amount": 20,
"flagged": false,
"currencyCode": "NGN",
"completedOn": "2022-07-22T14:00:42.000+0000",
"paymentDescription": "Trial transaction",
"paymentStatus": "EXPIRED",
"transactionReference": "MNFY|69|20220722142257|000170",
"paymentReference": "13i--000--lfuik93j",
"merchantCode": "1X1SDUSYRD47",
"merchantName": "Test01",
"metaData": {},
"completed": true,
"paymentMethodList": [
"CARD",
"ACCOUNT_TRANSFER"
],
"collectionChannel": "WEB_SDK"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 10,
"pageNumber": 0,
"offset": 0,
"paged": true,
"unpaged": false
},
"last": false,
"totalElements": 115,
"totalPages": 12,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 10,
"size": 10,
"number": 0,
"empty": false
}
}

Get Transaction Status

This endpoint returns the status of a transaction
GET
{{base_url}}/api/v2/transactions/MNFY%7C67%7C20220725111957%7C000283


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

transactionReference
String

Urlencoding of the said transaction reference

REQUEST
Copy button
curl -H "Accept: application/json"
https://sandbox.monnify.com/api/v2/transactions/MNFY%7C67%7C20220725111957%7C000283
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"transactionReference": "MNFY|67|20220725111957|000283",
"paymentReference": "12-3---03--1kls0a--dkad",
"amountPaid": "100.00",
"totalPayable": "100.00",
"settlementAmount": "90.00",
"paidOn": "25/07/2022 11:20:20 AM",
"paymentStatus": "PAID",
"paymentDescription": "Trial transaction",
"currency": "NGN",
"paymentMethod": "CARD",
"product": {
"type": "WEB_SDK",
"reference": "12-3---03--1kls0a--dkad"
},
"cardDetails": {
"cardType": "Sandbox Card Scheme",
"last4": "1111",
"expMonth": "10",
"expYear": "22",
"bin": "411111",
"bankCode": null,
"bankName": null,
"reusable": false,
"countryCode": null,
"cardToken": null,
"supportsTokenization": false,
"maskedPan": "411111******1111"
},
"accountDetails": null,
"accountPayments": [],
"customer": {
"email": "[email protected]",
"name": "Stephen Ikhane"
},
"metaData": {}
}
}

Customer Reserved Account

Create Reserved Account(General)

This endpoint allows the creation of dedicated virtual accounts for your customers.
POST
{{base_url}}/api/v2/bank-transfer/reserved-accounts


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

accountReference
String

A unique reference generated by merchants.

accountName
String

The name to be displayed during name enquiry

currencyCode
String

The currency allowed,"NGN.

contractCode
String

The merchant contract code

customerEmail
String

The customer's email

bvn
String

The bvn attached to a reserve account

getAllAvailableBanks
Boolean

This decides wether account numbers be generated to all allowable banks.

preferredBanks
Array

This field helps to choose certain banks for virtual account creation. This field is needed if getAvailableBanks is false

incomeSplitConfig
Object

A configuration on how payments are to be split among subaccounts

restrictPaymentSource
Boolean

Decides if payment should be restricted to some reserved accounts

allowedPaymentSource
Object

This captures bvns or account numbers or account names that are permitted to fund a reserved account. This is mandatory if restrictPaymentSource is set to true

nin
String

The customer’s NIN

REQUEST
Copy button
{ "accountReference": "abc123d380",
"accountName": "ysbbs hsbsb nxnznq",
"currencyCode": "NGN",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "ysbbs hsbsb nxnznq",
"bvn": "54848484888",
"nin":"34848484058",
"getAllAvailableBanks": true
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "7059707855",
"accountReference": "abc123d380",
"accountName": "ysb",
"currencyCode": "NGN",
"customerEmail": "[email protected]",
"customerName": "ysbbs hsbsb nxnznq",
"accounts": [
{
"bankCode": "035",
"bankName": "Wema bank",
"accountNumber": "5000606570",
"accountName": "ysb"
},
{
"bankCode": "232",
"bankName": "Sterling bank",
"accountNumber": "6001363048",
"accountName": "ysb"
}
],
"collectionChannel": "RESERVED_ACCOUNT",
"reservationReference": "DQD6S0N4U20FN8MF2EE1",
"reservedAccountType": "GENERAL",
"status": "ACTIVE",
"createdOn": "2022-07-27 15:29:40.131",
"incomeSplitConfig": [],
"bvn": "54848484888",
"restrictPaymentSource": false
}
}

Create Reserved Account(Invoice)

This endpoint allows the creation of an invoiced reserved account.
POST
{{base_url}}/api/v1/bank-transfer/reserved-accounts


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

contractCode
String

The merchant's contract code.

accountName
String

The name to be displayed during name enquiry.

currencyCode
String

The currency allowed,"NGN.

accountReference
String

A unique reference generated by the merchant

customerName
String

Full name of the customer

customerEmail
String

Email address of the customer.

reservedAccountType
String

This should be "INVOICE".

bvn
String

The customer's BVN

nin
String

The customer's NIN

REQUEST
Copy button
{
"contractCode":"7059707855",
"accountName":"Jane Doe",
"currencyCode":"NGN",
"accountReference": "janedoe1223--3",
"customerEmail": "[email protected]",
"customerName": "Jane Doe",
"reservedAccountType": "INVOICE"
}
RESPONSE
Copy button
{
"requestSuccessful": false,
"responseMessage": "You can not reserve two accounts with the same reference",
"responseCode": "99"
}

Get Reserved Account Details

This endpoint returns details of an account reserved for a customer
GET
{{base_url}}/api/v2/bank-transfer/reserved-accounts/{accountReference}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

accountReerence
String

The unique reference used in creating the reserved account.

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v2/bank-transfer/reserved-accounts/abc1niui--23
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "7059707855",
"accountReference": "abc1niui--23",
"accountName": "Test01-Tes",
"currencyCode": "NGN",
"customerEmail": "[email protected]",
"customerName": "mao Zhang",
"accounts": [
{
"bankCode": "035",
"bankName": "Wema bank",
"accountNumber": "5000588053",
"accountName": "Tes"
},
{
"bankCode": "232",
"bankName": "Sterling bank",
"accountNumber": "6001363175",
"accountName": "Tes"
}
],
"collectionChannel": "RESERVED_ACCOUNT",
"reservationReference": "8MD1E79P4LD94N6E2VNJ",
"reservedAccountType": "GENERAL",
"status": "ACTIVE",
"createdOn": "2022-07-31 10:08:41.0",
"contract": {
"name": "Default Contract",
"code": "7059707855",
"description": null
},
"transactionCount": 0,
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_762212281785",
"feePercentage": 10.5,
"feeBearer": true,
"splitPercentage": 20,
"reservedAccountConfigCode": "HRCNXDSAYX"
}
],
"bvn": "21212121212",
"restrictPaymentSource": true
}
}

Add Linked Accounts

This endpoint links accounts with another partner bank to an existing customer.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/add-linked-accounts/{accountReference}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

getAllAvailableBanks
Boolean

Determine if all necessary banks should be used

preferredBanks
Array

Contains bank codes of desired banks

accountReference
String

The unique reference used in creating the reserved account.

REQUEST
Copy button
{
"getAllAvailableBanks": false,
"preferredBanks": ["232"]
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "7059707855",
"accountReference": "abc1niui--23",
"accountName": "Tes",
"currencyCode": "NGN",
"customerEmail": "[email protected]",
"customerName": "mao Zhang",
"accounts": [
{
"bankCode": "035",
"bankName": "Wema bank",
"accountNumber": "5000588053",
"accountName": "Tes"
},
{
"bankCode": "232",
"bankName": "Sterling bank",
"accountNumber": "6001363175",
"accountName": "Tes"
}
],
"collectionChannel": "RESERVED_ACCOUNT",
"reservationReference": "8MD1E79P4LD94N6E2VNJ",
"reservedAccountType": "GENERAL",
"status": "ACTIVE",
"createdOn": "2022-07-31 10:08:41.0",
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_762212281785",
"feePercentage": 10.5,
"feeBearer": true,
"splitPercentage": 20,
"reservedAccountConfigCode": "HRCNXDSAYX"
}
],
"bvn": "21212121212",
"restrictPaymentSource": true
}
}

Update BVN for a Reserve Account

This endpoint updates BVN of customers reserved account
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/update-customer-bvn/{reservedAccountReference}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

bvn
String

The BVN used in creating the reserved account

REQUEST
Copy button
{
"bvn": "21212121212"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "915483727511",
"accountReference": "121612212051585",
"currencyCode": "NGN",
"customerEmail": "[email protected]",
"customerName": "Pascool Oj",
"accountNumber": "4290733572",
"bankName": "Providus Bank",
"bankCode": "101",
"collectionChannel": "RESERVED_ACCOUNT",
"reservationReference": "R8J4LCW3P82WN4X6LQCW",
"reservedAccountType": "GENERAL",
"status": "ACTIVE",
"createdOn": "2021-02-01 21:40:55.0",
"bvn": "21212121212",
"restrictPaymentSource": false
}
}

Allowed Payment Source(s)

This endpoint manages accounts that can fund a reserved account using either BVNs, Account Name or Account Number.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/update-payment-source-filter/{accountReference}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

restrictPaymentSource
Boolean

This field activate or de-activate restricting of payment sources for a reserved account.

allowedPaymentSource
Object

A collection of possible payment sources.

bvns
Array

List of BVNs that should be validated

bankAccounts
Array

List of account numbers that can fund the reserved account.

accountNumbers
String

An account number from which reserved account can be funded.

bankCode
String

A 3 digit CBN code for the account

accountNames
Array

List of account names for accounts from which reserved accounts can be funded.

accountReference
String

The unique reference used in creating the reserved account.

REQUEST
Copy button
{
"restrictPaymentSource": true,
"allowedPaymentSources": {
"bvns": [
"21212121212",
"20202020202"
]
}
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"restrictPaymentSource": true,
"allowedPaymentSources": {
"bvns": [
"21212121212",
"20202020202"
],
"bankAccounts": [
{
"accountNumber": "0068687503",
"bankCode": "232"
},
{
"accountNumber": "2048714015",
"bankCode": "057"
}
],
"accountNames": [
"DAMILARE OGUNNAIKE SAMUEL"
]
}
}
}

Updating Split Config for Reserved Account

This endpoint updates the split config of a customer reserved account.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/update-income-split-config/{accountReference}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

subAccountCode
String

The unique reference for the sub account that should receive the split

feeBearer
Boolean

This field determine if the sub account should bear transaction fees or not

feePercentage
Float

The percentage of the transaction fee to be borne by the sub account

splitPercentage
Float

The percentage of the amount paid to be split into the sub account.

accountReference
String

The unique reference used in creating the reserved account.

REQUEST
Copy button
[
{
"subAccountCode": "MFY_SUB_762212281785",
"feePercentage": 10.50
},
{
"subAccountCode": "MFY_SUB_322165393053",
"splitPercentage": 30
}
]
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"code": "HRCNXDSAYX",
"reservedAccountCode": "HRCNXDSAYX",
"feeBearer": "MERCHANT_ONLY",
"configDetails": [
{
"subAccountCode": "MFY_SUB_762212281785",
"feePercentage": 10.5,
"feeBearer": false,
"splitPercentage": 0,
"reservedAccountConfigCode": "HRCNXDSAYX"
},
{
"subAccountCode": "MFY_SUB_322165393053",
"feePercentage": 0,
"feeBearer": false,
"splitPercentage": 30,
"reservedAccountConfigCode": "HRCNXDSAYX"
}
]
}
}

Deallocating a reserved account

This endpoint allows you to deallocate/delete already created a reserved account.
DELETE
{{base_url}}/api/v1/bank-transfer/reserved-accounts/{accountReference}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

accountReference
String

The unique reference used to identify this reserved account

REQUEST
Copy button
curl --header "Content-Type: application/json"
--request POST
--data '{}'
{{base_url}}/api/v1/bank-transfer/reserved-accounts/5000588053
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"contractCode": "7059707855",
"accountReference": "abc1niui--23",
"accountName": "Tes",
"currencyCode": "NGN",
"customerEmail": "[email protected]",
"customerName": "mao Zhang",
"accountNumber": "5000588053",
"bankName": "Wema bank",
"bankCode": "035",
"collectionChannel": "RESERVED_ACCOUNT",
"reservationReference": "8MD1E79P4LD94N6E2VNJ",
"reservedAccountType": "GENERAL",
"status": "ACTIVE",
"createdOn": "2022-07-31 10:08:41.0",
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_762212281785",
"feePercentage": 10.5,
"feeBearer": false,
"splitPercentage": 0,
"reservedAccountConfigCode": "HRCNXDSAYX"
},
{
"subAccountCode": "MFY_SUB_322165393053",
"feePercentage": 0,
"feeBearer": false,
"splitPercentage": 30,
"reservedAccountConfigCode": "HRCNXDSAYX"
}
],
"bvn": "22342115371",
"restrictPaymentSource": true
}
}

Get Reserved Account Transactions

This endpoint returns the list of all transactions done on a reserved account.
GET
{{base_url}}/api/v1/bank-transfer/reserved-accounts/transactions


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

accountReference
String

The unique reference used in creating the reserved account.

page
Integer

The page of data you want returned by Monnify (Starts from 0).

size
Integer

The number of records you want returned in a page.

REQUEST
Copy button
curl -H "Accept: application/json"
https://sandbox.monnify.com/api/v1/bank-transfer/reserved-accounts/transactions
?accountReference={accountReference}&page=0&size=10
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"customerDTO": {
"email": "[email protected]",
"name": "Test Reserved Account",
"merchantCode": "ALJKHDALASD"
},
"providerAmount": 0.21,
"paymentMethod": "ACCOUNT_TRANSFER",
"createdOn": "2019-07-24T14:12:27.000+0000",
"amount": 100.00,
"flagged": false,
"providerCode": "98271",
"fee": 0.79,
"currencyCode": "NGN",
"completedOn": "2019-07-24T14:12:28.000+0000",
"paymentDescription": "Test Reserved Account",
"paymentStatus": "PAID",
"transactionReference": "MNFY|20190724141227|003374",
"paymentReference": "MNFY|20190724141227|003374",
"merchantCode": "ALJKHDALASD",
"merchantName": "Test Limited"
"payableAmount": 100.00,
"amountPaid": 100.00,
"completed": true
},
{
"customerDTO": {
"email": "[email protected]",
"name": "Test Reserved Account",
"merchantCode": "ALJKHDALASD"
},
"providerAmount": 0.11,
"paymentMethod": "ACCOUNT_TRANSFER",
"createdOn": "2019-07-24T11:14:45.000+0000",
"amount": 50.00,
"flagged": false,
"providerCode": "98271",
"fee": 0.79,
"currencyCode": "NGN",
"completedOn": "2019-07-24T11:14:45.000+0000",
"paymentDescription": "Test Reserved Account",
"paymentStatus": "PAID",
"transactionReference": "MNFY|20190724111444|003259",
"paymentReference": "MNFY|20190724111444|003259",
"merchantCode": "ALJKHDALASD",
"merchantName": "Test Limited",
"settleInstantly": true,
"payableAmount": 50.00,
"amountPaid": 50.00,
"completed": true
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 10,
"pageNumber": 0,
"offset": 0,
"unpaged": false,
"paged": true
},
"totalElements": 2,
"totalPages": 1,
"last": true,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 2,
"size": 10,
"number": 0,
"empty": false
}
}

Update KYC Info

This endpoint links customers' BVN/NIN to their respective reserved accounts.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/{accountReference}/kyc-info


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

bvn
String

The customer's BVN

nin
String

The customer’s NIN

accountReference
String

The account reference linked to the reserved account being updated.

REQUEST
Copy button
{
"bvn":"83891300182",
"nin":"83891300182"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"accountReference": "a1fe1c73c6f985eb43e8ef35ec0d6a398698cdea",
"accountName": "CHUKWUEMEKA BENJAMIN ONONOGBU",
"customerEmail": "[email protected]",
"customerName": "mao Zhang",
"bvn": "22222222227"
}
}

Invoice

Create an Invoice

This endpoint creates invoice for payments on your integration.
POST
{{base_url}}/api/v1/invoice/create


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

amount
Float

The amount to be paid by the customer

currencyCode
String

The currency of the transaction being initialized. "NGN"

invoiceReference
String

Merchant's Unique reference for the invoice

customerName
String

Full name of the customer

customerEmail
String

Email of the customer

contractCode
String

Merchant's contract code

description
String

Description of the transaction. Will be used as the account name for bank transfer payments

expiryDate
String

The expiry date for the invoice. The format is:YYYY-MM-DD HH:MM:SS

incomeSplitConfig
Object

This field contains specifications on how payments to this reserve account should be split.

redirectUrl
String

A URL which customer will be redirected to when payment is successfully completed

REQUEST
Copy button
{
"amount": "999",
"invoiceReference": "183891300182",
"description": "test invoice",
"currencyCode": "NGN",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-10-30 12:00:00",
"paymentMethods": [],
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_322165393053",
"feePercentage": 10.5,
"splitAmount": 20,
"feeBearer": true
}
],
"redirectUrl": "http://app.monnify.com"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 999,
"invoiceReference": "183891300182",
"invoiceStatus": "PENDING",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-10-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-07-31 12:14:14",
"checkoutUrl": "https://sandbox.sdk.monnify.com/checkout/MNFY|99|20220731121414|000867",
"accountNumber": "5000588061",
"accountName": "tes",
"bankName": "Wema bank",
"bankCode": "035",
"redirectUrl": "http://app.monnify.com",
"transactionReference": "MNFY|99|20220731121414|000867",
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_322165393053",
"splitAmount": 20,
"feePercentage": 10.5,
"feeBearer": true,
"splitPercentage": null
}
]
}
}

View Invoice Details

This endpoint returns details of an invoice on your integration.
GET
{{base_url}}/api/v1/invoice/{invoiceReference}/details


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

invoiceReference
String

The unique reference used in creating the invoice.

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v1/invoice/18389130010082/details
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 999,
"invoiceReference": "18389130010082",
"invoiceStatus": "PENDING",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-10-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-07-31 12:29:26",
"checkoutUrl": "https://sandbox.sdk.monnify.com/checkout/MNFY|99|20220731122925|000868",
"accountNumber": "5000588060",
"accountName": "tes",
"bankName": "Wema bank",
"bankCode": "035",
"transactionReference": "MNFY|99|20220731122925|000868",
"incomeSplitConfig": [
{
"subAccountCode": "MFY_SUB_322165393053",
"splitAmount": 20,
"feePercentage": 10.5,
"feeBearer": true,
"splitPercentage": 0
}
]
}
}

Get All Invoices

This endpoint returns the list of all the invoice available on your integration.
GET
{{base_url}}/api/v1/invoice/all


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v1/invoice/all
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"amount": 999,
"invoiceReference": "18389130010082",
"invoiceStatus": "PENDING",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-10-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-07-31 12:29:26",
"accountNumber": "5000588060",
"bankName": "Wema bank",
"bankCode": "035"
},
{
"amount": 999,
"invoiceReference": "183891300182",
"invoiceStatus": "PENDING",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-10-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-07-31 12:14:15",
"accountNumber": "5000588061",
"bankName": "Wema bank",
"bankCode": "035"
},
{
"amount": 900,
"invoiceReference": "183891182",
"invoiceStatus": "PAID",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-05-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-05-20 10:07:52"
},
{
"amount": 999,
"invoiceReference": "1838913189",
"invoiceStatus": "EXPIRED",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-03-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-03-09 12:18:58",
"accountNumber": "5000654355",
"bankName": "Wema bank",
"bankCode": "035"
},
{
"amount": 999,
"invoiceReference": "1838913187",
"invoiceStatus": "EXPIRED",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-03-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-03-09 12:18:40",
"accountNumber": "5000654354",
"bankName": "Wema bank",
"bankCode": "035"
},
{
"amount": 999,
"invoiceReference": "1838913182",
"invoiceStatus": "EXPIRED",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-03-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-03-09 11:55:45",
"accountNumber": "5000654351",
"bankName": "Wema bank",
"bankCode": "035"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 10,
"pageNumber": 0,
"offset": 0,
"unpaged": false,
"paged": true
},
"last": true,
"totalElements": 6,
"totalPages": 1,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 6,
"size": 10,
"number": 0,
"empty": false
}
}

Cancel an Invoice

This endpoint cancels an Invoice on your integration.
DELETE
{{base_url}}/api/v1/invoice/{invoiceReference}/cancel


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

invoiceReference
String

The unique reference used in creating the invoice.

REQUEST
Copy button
curl --header "Content-Type: application/json"
--request POST
--data '{}'
{{base_url}}/api/v1/invoice/18389130010082/cancel
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 999,
"invoiceReference": "18389130010082",
"invoiceStatus": "CANCELLED",
"description": "test invoice",
"contractCode": "7059707855",
"customerEmail": "[email protected]",
"customerName": "John Snow",
"expiryDate": "2022-10-30 12:00:00",
"createdBy": "MK_TEST_JRQAZRFD2W",
"createdOn": "2022-07-31 12:29:26",
"accountNumber": "5000588060",
"bankName": "Wema bank",
"bankCode": "035"
}
}

Attaching a Reserved Account to an Invoice

This endpoint attaches a Reserved Account to an Invoice.
POST
{{base_url}}/api/v1/invoice/create


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

amount
Float

Amount to be paid

currencyCode
String

The currency of the transaction being initialized. "NGN"

invoiceReference
String

Merchant's Unique reference for the invoice.

customerName
String

Full name of the customer

customerEmail
String

Email address of the customer

contractCode
String

Merchant's contract code

description
String

Description for the transaction.

expiryDate
String

Expiry date for the invoice

incomeSplitConfig
Object

This field contains specifications on how payments to this reserve account should be split.

accountReference
String

Your unique reference used to identify this reserved account

REQUEST
Copy button
{
"amount": "999",
"invoiceReference": "1838913182",
"accountReference": "janedoe12233",
"description": "test invoice",
"currencyCode": "NGN",
"contractCode": "38238193818",
"customerEmail": "[email protected]",
"customerName": "Jane Doe",
"expiryDate": "2019-10-30 12:00:00"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 999,
"invoiceReference": "1838913182",
"invoiceStatus": "PENDING",
"description": "test invoice",
"contractCode": "4876165459",
"customerEmail": "[email protected]",
"customerName": "Jane Doe",
"expiryDate": "2019-10-18 14:48:00",
"createdBy": "MK_TEST_VR7J3UAACH",
"createdOn": "2019-08-27 23:14:29",
"checkoutUrl": "https://sandbox.sdk.monnify.com/checkout/MNFY|20190827231429|000340",
"accountNumber": "1122334455",
"accountName": "Jane Doe",
"bankName": "GTBank",
"bankCode": "058"
}
}

Recurring Payment

Charge Card Token

This endpoint allows you to charge an already tokenized card with it’s card token. **NOTE**: The customer email address used in the first successful charge should be stored along with the card token.
POST
{{base_url}}/api/v1/merchant/cards/charge-card-token


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

REQUEST
Copy button
{
"cardToken": "MNFY_64355FBB44534A3E8B484985436BE1BD",
"amount": 20,
"customerName": "Marvelous Benji",
"customerEmail": "[email protected]",
"paymentReference": "16427769909682937",
"paymentDescription": "Paying for Product A",
"currencyCode": "NGN",
"contractCode": "100693167467",
"apiKey": "MK_PROD_WTZLS10MX6",
"metaData": {
"ipAddress": "127.0.0.1",
"deviceType": "mobile"
}
}
RESPONSE
Copy button
{
"requestSuccessful": false,
"responseMessage": "Invalid card token",
"responseCode": "99"
}

Sub Accounts

Create Sub Account(s)

This endpoint allows you to create a sub account to enable the spliting of payments between different accounts.
POST
{{base_url}}/api/v1/sub-accounts


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

currencyCode
String

Settlement currency. "NGN"

accountNumber
String

The account number that should be created as a sub account.

bankCode
String

The 3 digit bank code of the bank where the account number is domiciled

email
String

The email tied to the sub account

defaultSplitPercentage
Float

The default percentage to be split into the sub account on any transaction.

REQUEST
Copy button
[
{
"currencyCode": "NGN",
"bankCode": "058",
"accountNumber": "0211319282",
"email": "[email protected]",
"defaultSplitPercentage": 20.87
}
]
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": [
{
"subAccountCode": "MFY_SUB_811397375865",
"accountNumber": "0211319282",
"accountName": "ALEMOH DANIEL MOSES",
"currencyCode": "NGN",
"email": "[email protected]",
"bankCode": "058",
"bankName": "GTBank",
"defaultSplitPercentage": 20.87,
"settlementProfileCode": "8717495899",
"settlementReportEmails": []
}
]
}

Delete Sub Account

This endpoint deletes a sub account on your integration.
DELETE
{{base_url}}/api/v1/sub-accounts/{subAccountCode}


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

subAccountCode
String

The subAccountCode of the sub account you want to delete.

REQUEST
Copy button
curl --header "Content-Type: application/json"
--request POST
--data '{}'
{{base_url}}/api/v1/sub-accounts/MFY_SUB_811397375865
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0"
}

Get Sub Accounts

This endpoint returns the list of sub accounts that have been created on your integration.
GET
{{base_url}}/api/v1/sub-accounts


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v1/sub-accounts
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": [
{
"subAccountCode": "MFY_SUB_811397375865",
"accountNumber": "0211319282",
"accountName": "ALEMOH DANIEL MOSES",
"currencyCode": "NGN",
"email": "[email protected]",
"bankCode": "058",
"bankName": "GTBank",
"defaultSplitPercentage": 20.87,
"settlementProfileCode": "8717495899",
"settlementReportEmails": []
},
{
"subAccountCode": "MFY_SUB_322165393053",
"accountNumber": "2085886393",
"accountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"currencyCode": "NGN",
"email": "[email protected]",
"bankCode": "057",
"bankName": "Zenith bank",
"defaultSplitPercentage": 20,
"settlementProfileCode": "8717495899",
"settlementReportEmails": []
},
{
"subAccountCode": "MFY_SUB_687043136486",
"accountNumber": "8569214283",
"accountName": "MFY / 9jaCash-jaCash-ABODUNRIN OYELEKE MAICHEAL",
"currencyCode": "NGN",
"email": "[email protected]",
"bankCode": "035",
"bankName": "Wema bank",
"defaultSplitPercentage": 20.87,
"settlementProfileCode": "8717495899",
"settlementReportEmails": []
}
]
}

Update Sub Account

This endpoint updates the details of an existing sub account.
PUT
{{base_url}}/api/v1/sub-accounts


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

currencyCode
String

Settlement currency. "NGN"

accountNumber
String

The account number that should be created as a sub account.

bankCode
String

The 3 digit bank code of the bank where the account number is domiciled

email
String

The email tied to the sub account

defaultSplitPercentage
Float

The default percentage to be split into the sub account on any transaction.

subAccountCode
String

The sub account code of the account to be updated.

REQUEST
Copy button
{
"subAccountCode": "MFY_SUB_811397375865",
"currencyCode": "NGN",
"bankCode": "058",
"accountNumber": "0211319282",
"email": "[email protected]",
"defaultSplitPercentage": "25"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"subAccountCode": "MFY_SUB_811397375865",
"accountNumber": "0211319282",
"accountName": "ALEMOH DANIEL MOSES",
"currencyCode": "NGN",
"email": "[email protected]",
"bankCode": "058",
"bankName": "GTBank",
"defaultSplitPercentage": 25,
"settlementProfileCode": "8717495899",
"settlementReportEmails": []
}
}

Transfers (Disbursement)

Initiate Transfer (Single)

This endpoint helps to initiate transfer to desired bank account.
POST
{{base_url}}/api/v2/disbursements/single


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

amount
Float

Amount to disburse

reference
String

The unique reference for the transaction

narration
String

The Narration for the transactions being processed

destinationBankCode
String

The 3 digit bank code representing the destination bank

destinationAccountNumber
String

The beneficiary account number

currency
String

The currency of the transaction being initialised - "NGN"

sourceAccountNumber
String

Unique identifier of your wallet

REQUEST
Copy button
{
"amount": 200,
"reference":"referen00ce---1290034",
"narration":"911 Transaction",
"destinationBankCode": "057",
"destinationAccountNumber": "2085886393",
"currency": "NGN",
"sourceAccountNumber": "3934178936"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 200,
"reference": "referen00ce---1290034",
"status": "SUCCESS",
"dateCreated": "2022-07-31T14:31:33.759+0000",
"totalFee": 35,
"destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"destinationBankName": "Zenith bank",
"destinationAccountNumber": "2085886393",
"destinationBankCode": "057"
}
}

Initiate Transfer (Async)

This endpoint helps initiate transfer asynchronously to desired bank account.
POST
{{base_url}}/api/v2/disbursements/single


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

amount
Float

Amount to disburse

reference
String

The unique reference for the transaction

narration
String

The Narration for the transactions being processed

destinationBankCode
String

The 3 digit bank code representing the destination bank

destinationAccountNumber
String

The beneficiary account number

currency
String

The currency of the transaction being initialised - "NGN"

sourceAccountNumber
String

Unique identifier of your wallet

async
Boolean

An option to process disbursment asynchronously

REQUEST
Copy button
{
"amount": 200,
"reference":"reference-0x1290034",
"narration":"911 Transaction",
"destinationBankCode": "057",
"destinationAccountNumber": "2085886393",
"currency": "NGN",
"sourceAccountNumber": "3934178936",
"async":true
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 200,
"reference": "reference-0x1290034",
"status": "PENDING",
"dateCreated": "2023-09-22T15:38:38.443+0000",
"totalFee": 35,
"destinationBankName": "Zenith bank",
"destinationAccountNumber": "2085886393",
"destinationBankCode": "057"
}
}

Initiate Transfer (Bulk)

This endpoint helps in Initiating Bulk Transfer transactions on your integration.
POST
{{base_url}}/api/v2/disbursements/batch


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

title
String

The title of the batch disbursement

batchReference
String

A unique reference identifying the batch disbursement

narration
String

A narration for the disbursement

sourceAccountNumber
String

The merchant WALLET ACCOUNT NUMBER.

onValidationFailure
Enum

Decision to be taken if any of the disbursement batches fail. Either BREAK or CONTINUE.

notificationInterval
Integer

This determines how often Monnify should notify the merchant of its progress when processing a batch transfer

transactionList
Array

A list of transactions to be processed

REQUEST
Copy button
{
"title" : "Game of Batches",
"batchReference":"batchreference--12934",
"narration":"911 Transaction",
"sourceAccountNumber": "3934178936",
"onValidationFailure" : "CONTINUE",
"notificationInterval": 25,
"transactionList" : [
{
"amount": 1300,
"reference":"Final-Refere-nce-1a",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN"
},
{
"amount": 570,
"reference":"Final-Ref-erence-2a",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN"
},
{
"amount": 230,
"reference":"Final-Refer-ence-3a",
"narration":"911 Transaction",
"destinationBankCode": "058",
"destinationAccountNumber": "0111946768",
"currency": "NGN"
}
]
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"totalAmount": 2100,
"totalFee": 105,
"batchReference": "batchreference--12934",
"batchStatus": "AWAITING_PROCESSING",
"totalTransactionsCount": 3,
"dateCreated": "2022-07-31T14:41:19.588+0000"
}
}

Authorize Single Transfers

This endpoint authorizes single transfers on your integration.
POST
{{base_url}}/api/v2/disbursements/single/validate-otp


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

reference
String

The unique reference for the transfer

authorizationCode
String

The OTP sent to merchant's email address

REQUEST
Copy button
{
"reference":"refere--n00ce---1290034",
"authorizationCode":"491763"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 200,
"reference": "refere--n00ce---1290034",
"status": "SUCCESS",
"dateCreated": "2022-07-31T15:36:16.000+0000",
"totalFee": 35,
"destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"destinationBankName": "Zenith bank",
"destinationAccountNumber": "2085886393",
"destinationBankCode": "057"
}
}

Authorize Bulk Transfers

This endpoint authorizes bulk transfers on your integration.
POST
{{base_url}}/api/v2/disbursements/batch/validate-otp


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

reference
String

The batch reference used in the transfer

authorizationCode
String

The OTP sent to the merchant's email

REQUEST
Copy button
{
"reference":"batchre-ference--12934",
"authorizationCode":"122080"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"totalAmount": 2100,
"totalFee": 105,
"batchReference": "batchre-ference--12934",
"batchStatus": "AWAITING_PROCESSING",
"totalTransactionsCount": 3,
"dateCreated": "2022-07-31T15:49:03.000+0000"
}
}

Resend OTP

This endpoint generates a new OTP in the event that there were challenges with the former OTP sent.
POST
{{base_url}}/api/v2/disbursements/single/resend-otp


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

reference
String

The reference used for the transfer

REQUEST
Copy button
{
"reference" : "{{reference}}"
}
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"message": "Authorization code will be processed and sent to predefined email addresses(s)"
}
}

Single Transfer Status

This endpoint verifies the status of a single transfer on your integration.
GET
{{base_url}}/api/v2/disbursements/single/summary


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

reference
String

The reference used for the transfer

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v2/disbursements/single/summary?reference=referen00ce---1290034
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"amount": 200,
"reference": "referen00ce---1290034",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731033133AABQGN",
"createdOn": "2022-07-31T14:31:34.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "2085886393",
"destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"destinationBankCode": "057",
"destinationBankName": "Zenith bank"
}
}

List All Single Transfers

This endpoint returns the list of all single transfers made on your integration.
GET
{{base_url}}/api/v2/disbursements/single/transactions


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

pageSize
Integer

The number of transfer records to return

pageNo
Integer

A number specifying what page of transfers to be retrieved

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v2/disbursements/single/transactions?pageSize=20&pageNo=1
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"amount": 10,
"reference": "hjkdd0odood0pl",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220516012053AAAYYN",
"createdOn": "2022-05-16T12:20:54.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "hjkddodood0pl",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220422013417AAAXSP",
"createdOn": "2022-04-22T12:34:18.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "hjkddodood0p9",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220422103648AAAXSG",
"createdOn": "2022-04-22T09:36:48.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "hjkddodood0p",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220422103636AAAXSF",
"createdOn": "2022-04-22T09:36:36.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "hjkddodood0",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220422103623AAAXSE",
"createdOn": "2022-04-22T09:36:23.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "hjkddodood",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220422090109AAAXRK",
"createdOn": "2022-04-22T08:01:10.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "reference234hh",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220420120659AAAXNY",
"createdOn": "2022-04-20T11:06:59.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "reference29034hh",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220420120252AAAXNX",
"createdOn": "2022-04-20T11:02:53.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "referene2934hh",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220326055912AAAWGE",
"createdOn": "2022-03-26T16:59:12.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "reference2934hh",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220322053101AAAVTO",
"createdOn": "2022-03-22T16:31:02.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 10,
"reference": "reference2934",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220317100514AAAVMO",
"createdOn": "2022-03-17T09:05:14.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 230,
"reference": "Final-Reference-",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315094149AAAVDV",
"createdOn": "2022-03-15T08:41:49.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 230,
"reference": "Final-Reference-3c",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "FAILED",
"transactionDescription": "Account number could not be validated",
"transactionReference": "MFDS20220315094149AAAVDW",
"createdOn": "2022-03-15T08:41:49.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946788",
"destinationBankCode": "058"
},
{
"amount": 230,
"reference": "Final-Reference-3b",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "FAILED",
"transactionDescription": "Account number could not be validated",
"transactionReference": "MFDS20220315094149AAAVDX",
"createdOn": "2022-03-15T08:41:49.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111940768",
"destinationBankCode": "058"
},
{
"amount": 1300,
"reference": "Final-Reference-v",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315094148AAAVDT",
"createdOn": "2022-03-15T08:41:49.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 570,
"reference": "Final-Reference-m",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315094148AAAVDU",
"createdOn": "2022-03-15T08:41:49.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 570,
"reference": "Final-Reference-2",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315093929AAAVDR",
"createdOn": "2022-03-15T08:39:30.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 230,
"reference": "Final-Reference-3",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315093929AAAVDS",
"createdOn": "2022-03-15T08:39:30.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 1300,
"reference": "Final-Reference-1",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315093929AAAVDQ",
"createdOn": "2022-03-15T08:39:29.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 1300,
"reference": "Final-Reference-1a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220315093339AAAVDN",
"createdOn": "2022-03-15T08:33:39.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 20,
"pageNumber": 1,
"offset": 20,
"paged": true,
"unpaged": false
},
"last": false,
"totalPages": 3,
"totalElements": 54,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": false,
"numberOfElements": 20,
"size": 20,
"number": 1,
"empty": false
}
}

List All Bulk Transfers

This endpoint returns the list of all bulk transfers made on your integration.
GET
{{base_url}}/api/v2/disbursements/bulk/transactions


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

pageSize
Integer

The number of transfer records to return

pageNo
Integer

A number specifying what page of transfers to be retrieved

REQUEST
Copy button
curl -H "Accept: application/json"
https://sandbox.monnify.com/api/v2/disbursements/single/transactions?pageSize=5
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"totalAmount": 45,
"totalFee": 80,
"batchReference": "Batch-1596666798811",
"batchStatus": "COMPLETED",
"totalTransactionsCount": 4,
"dateCreated": "2020-08-05T22:33:21.000+0000"
},
{
"totalAmount": 50,
"totalFee": 20,
"batchReference": "Batch-1593606495053",
"batchStatus": "COMPLETED",
"totalTransactionsCount": 1,
"dateCreated": "2020-07-01T12:28:16.000+0000"
},
{
"totalAmount": 50,
"totalFee": 20,
"batchReference": "Batch-1593606391931",
"batchStatus": "COMPLETED",
"totalTransactionsCount": 1,
"dateCreated": "2020-07-01T12:26:33.000+0000"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 3,
"pageNumber": 0,
"offset": 0,
"unpaged": false,
"paged": true
},
"totalPages": 3,
"last": false,
"totalElements": 7,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 3,
"size": 3,
"number": 0,
"empty": false
}
}

Get Bulk Transfer Transactions

This endpoint returns the list of all transactions in a bulk transfer batch and their status.
GET
{{base_url}}/api/v2/disbursements/bulk/batchreference--12934/transactions


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

pageSize
Integer

The number of transfer record to be returned per page

pageNo
Integer

A number specifying what page of transfers to be retrieved

batchReference
String

A unique reference identifying the batch disbursement

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v2/disbursements/bulk/batchreference--12934/transactions
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"amount": 230,
"reference": "Final-Refer-ence-3a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034121AABQGQ",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 570,
"reference": "Final-Ref-erence-2a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034121AABQGP",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 1300,
"reference": "Final-Refere-nce-1a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034120AABQGO",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 10,
"pageNumber": 0,
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"totalPages": 1,
"totalElements": 3,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 3,
"size": 10,
"number": 0,
"empty": false
}
}

Bulk Transfer Status

This endpoint verifies the status of a bulk transfer on your integration.
GET
{{base_url}}/api/v2/disbursements/bulk/batchreference--12934/transactions


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

batchReference
String

A unique reference identifying the batch disbursement

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v2/disbursements/bulk/batchreference--12934/transactions
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"amount": 230,
"reference": "Final-Refer-ence-3a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034121AABQGQ",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 570,
"reference": "Final-Ref-erence-2a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034121AABQGP",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 1300,
"reference": "Final-Refere-nce-1a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034120AABQGO",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 10,
"pageNumber": 0,
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"totalPages": 1,
"totalElements": 3,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 3,
"size": 10,
"number": 0,
"empty": false
}
}

Search Disbursement Transactions

This endpoint returns the list of all disbursement transactions.
GET
{{base_url}}/api/v2/disbursements/search-transactions


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

sourceAccountNumber
String

The merchant's WALLET ACCOUNT NUMBER, this parameter is mandatory

pageSize
Integer

The number of records to return

pageNo
Integer

The current page from the total

startDate
String

A timestamp value specifying the date to start filtering disbursement transactions by the createdAt field

endDate
String

A timestamp value specifying the date to stop filtering disbursement transactions by the createdAt field

amountFrom
String

A number specifying the lower bound for filtering the transactions by the amount field

amountTo
String

A number specifying the upper bound for filtering the transactions by the amount field.

REQUEST
Copy button
curl -H "Accept: application/json"
{{base_url}}/api/v2/disbursements/search-transactions?sourceAccountNumber=3934178936
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"content": [
{
"amount": 200,
"reference": "refere--n00ce---1290--034",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": true,
"status": "EXPIRED",
"transactionDescription": "Transaction has expired",
"transactionReference": "MFDS20220731044951AABQGV",
"createdOn": "2022-07-31T15:49:51.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "2085886393",
"destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"destinationBankCode": "057",
"destinationBankName": "Zenith bank"
},
{
"amount": 230,
"reference": "Final-Ref--er-ence-3a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": true,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731044903AABQGU",
"createdOn": "2022-07-31T15:49:04.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 570,
"reference": "Final-Ref-e--rence-2a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": true,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731044903AABQGT",
"createdOn": "2022-07-31T15:49:04.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 1300,
"reference": "Final-Ref--ere-nce-1a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": true,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731044903AABQGS",
"createdOn": "2022-07-31T15:49:04.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 200,
"reference": "refere--n00ce---1290034",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": true,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731043616AABQGR",
"createdOn": "2022-07-31T15:36:16.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "2085886393",
"destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"destinationBankCode": "057",
"destinationBankName": "Zenith bank"
},
{
"amount": 230,
"reference": "Final-Refer-ence-3a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034121AABQGQ",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 570,
"reference": "Final-Ref-erence-2a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034121AABQGP",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 1300,
"reference": "Final-Refere-nce-1a",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731034120AABQGO",
"createdOn": "2022-07-31T14:41:21.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "0111946768",
"destinationAccountName": "MEKILIUWA SMART CHINONSO",
"destinationBankCode": "058",
"destinationBankName": "GTBank"
},
{
"amount": 200,
"reference": "referen00ce---1290034",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "SUCCESS",
"transactionDescription": "Transaction successful",
"transactionReference": "MFDS20220731033133AABQGN",
"createdOn": "2022-07-31T14:31:34.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "2085886393",
"destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU",
"destinationBankCode": "057",
"destinationBankName": "Zenith bank"
},
{
"amount": 200,
"reference": "reference---12934",
"narration": "911 Transaction",
"currency": "NGN",
"fee": 35,
"twoFaEnabled": false,
"status": "FAILED",
"transactionDescription": "Name enquiry failed",
"transactionReference": "MFDS20220731031032AABQGM",
"createdOn": "2022-07-31T14:10:33.000+0000",
"sourceAccountNumber": "3934178936",
"destinationAccountNumber": "5000143115",
"destinationBankCode": "035",
"destinationBankName": "Wema bank"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"pageSize": 10,
"pageNumber": 0,
"offset": 0,
"paged": true,
"unpaged": false
},
"last": false,
"totalPages": 6,
"totalElements": 54,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"first": true,
"numberOfElements": 10,
"size": 10,
"number": 0,
"empty": false
}
}

Get Wallet Balance

This endpoint returns the available balance in your monnify wallet.
GET
{{base_url}}/api/v2/disbursements/wallet-balance


Headers

Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.

Body Params

accountNumber
String

The merchant's WALLET ACCOUNT NUMBER.

REQUEST
Copy button
curl -H "Accept: application/json"
https://sandbox.monnify.com/api/v2/disbursements/wallet-balance?accountNumber=String
RESPONSE
Copy button
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"availableBalance": 378.93,
"ledgerBalance": 378.93
}
}

Wallet

Create Wallet

This endpoint creates wallets for merchants' customers
POST
{{base_url}}/api/v1/disbursements/wallet


Headers

Authorization
basic
Authorize this API call by including Authorization header that contains the word 'Basic' followed by a space and a base64-encoded string 'apiKey:clientSecret' i.e. 'Basic base64(ApiKey:SecretKey)', include the Token in the request header.

Body Params

walletReference
String

A unique identifier for the wallet

walletName
String

The desired wallet name

customerName
String

The customer's name

customerEmail
String

The customer's email

bvn
String

The customer's bvn

bvnDateOfBirth
String

The date of birth associated with the bvn in the format yyyy-mm-dd

REQUEST
Copy button
{
"walletReference":"ref16842048425966",
"walletName":"Staging Wallet - ref16804248425966",
"customerName": "John Doe",
"bvnDetails": {
"bvn": "804248425966",
"bvnDateOfBirth": "1993-04-23"
},
"customerEmail": "[email protected]"
}
RESPONSE