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. Reversed Disbursement (for reversed disbursement transactions)
    ...Read more
  5. Successful Refund (for successfully processed initiated refunds)
    ...Read more
  6. Failed Refund (for failed initiated refunds)
    ...Read more
  7. Settlement Completion (for successfully processed settlements to your bank account or wallet)
    ...Read more
  8. Completed Oflline Payments
    ...Read more
  9. Notification for Rejected Payments
    ...Read more
  10. Mandate Status Change
    ...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/otp/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.
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": {}
    }
}

Get Status By Reference

This endpoint returns the status of a transaction using either the Monnify transaction reference or the merchant's payment reference
GET
{{base_url}}/api/v2/merchant/transactions/query

Headers

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

Body Params

transactionReference
String

The Monnify generated reference
paymentReference
String

The merchant generated 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/reference/{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":{{bvn}}
}
RESPONSE
Copy button
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "accountReference": "a1fe1c73c6f985eb43e8ef35ec0d6a398698cdea",
        "accountName": "CHUKS BENJI WILS",
        "customerEmail": "[email protected]",
        "customerName": "mao  Zhang",
        "bvn": "22222222222"
    }
}

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"
}

Direct Debit

Create Mandate

This endpoint initiates the creation of a mandate
POST
{{base_url}}/api/v1/direct-debit/mandate/create

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 Monnify contract code
mandateReference
String

Merchants generated reference to identify a mandate
autoRenew
Boolean

This informs Monnify wether the mandate will be renewed once it reaches end date. Set this parameter to true for Open Fixed and Open Flexible mandates and false otherwise.
customerName
String

The customer's name
customerEmailAddress
String

The customer's address
customerPhoneNumber
String

The customer's phone number
customerAddress
String

The customer's address
customerAccountNumber
String

The customer's bank account number
customerAccountBankCode
String

The bank code of the customer’s bank account
mandateDescription
String

The description of the payment the mandate is associated to
mandateStartDate
String

The start date for the mandate. The date format is: YYYY-MM-DD HH:MM:SS
mandateEndDate
String

The end date for the mandate. The date format is: YYYY-MM-DD HH:MM:SS
mandateAmount
Float

Total lifetime amount debitable on the mandate.
debitAmount
Float

The amount to be debited periodically. Set this field for Open Fixed and Closed Fixed mandates to specify the amount to be charged periodically. Ignore for other mandate types
REQUEST
Copy button
{
    "contractCode": "4934121686",
    "mandateReference": "unique_ref3_02s600972",
    "autoRenew": false,
    "customerName": "Ankit Kushwaha",
    "customerPhoneNumber": "1234567890",
    "customerEmailAddress": "[email protected]",
    "customerAddress": "123 Example Street, City, Country",
    "customerAccountNumber": "0051762787",
    "customerAccountBankCode": "998",
    "mandateDescription": "Subscription Fee",
    "mandateStartDate": "2024-05-22T10:15:30",
    "mandateEndDate": "2025-05-22T10:15:30"
}
RESPONSE
Copy button
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "responseMessage": "Your request for creating a mandate is submitted. An authorization instruction will be sent to the customer email.",
        "mandateReference": "unique_ref3_02s600972",
        "mandateCode": "MTDD|01HY8W3FBKHTFBZP9DQ9KNHR1G",
        "mandateStatus": "INITIATED"
    }
}

Get Mandate Status

This endpoint retrieves the details of a created mandate
GET
{{base_url}}/api/v1/direct-debit/mandate/

Headers

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

Body Params

mandateReferences
String

Merchants generated reference to identify a mandate
REQUEST
Copy button
curl -H "Accept: application/json" 
https://sandbox.monnify.com/api/v1/direct-debit/mandate/?mandateReferences=unique_ref3_02gs600s972
RESPONSE
Copy button
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": [
        {
            "mandateCode": "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0",
            "externalMandateReference": "unique_ref3_02gs600s972",
            "startDate": "2024-05-19T09:15:30.000+0000",
            "endDate": "2024-09-22T09:15:30.000+0000",
            "mandateStatus": "ACTIVE",
            "mandateAmount": 50000,
            "contractCode": "4934121686",
            "autoRenew": false,
            "customerPhoneNumber": "1234567890",
            "customerEmailAddress": "[email protected]",
            "customerAddress": "123 Example Street, City, Country",
            "customerName": "Ankit Kushwaha",
            "customerAccountName": "Ankit Kushwaha",
            "customerAccountNumber": "0051762787",
            "customerAccountBankCode": "998",
            "mandateDescription": "Subscription Fee",
            "debitAmount": null,
            "authorizationMessage": null,
            "authorizationLink": null
        }
    ]
}

Debit Mandate

This endpoint debits an active mandate
POST
{{base_url}}/api/v1/direct-debit/mandate/debit

Headers

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

Body Params

paymentReference
String

Merchants unique reference to identify a single direct debit payment
mandateCode
String

Monnify generated mandate identifier
debitAmount
String

Payment amount to be debited from a single debit transaction
narration
String

Description of the single debit
customerEmail
String

The customer's email address
REQUEST
Copy button
{
  "paymentReference": "PR1234567991002",
  "mandateCode": "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0",
  "debitAmount": 1000.00,
  "narration": "Payment for Services",
  "customerEmail":"[email protected]"
}
RESPONSE
Copy button
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "transactionStatus": "PENDING",
        "responseMessage": "Debit mandate request accepted for processing",
        "transactionReference": "MNFY|20240519180055|000001",
        "paymentReference": "PR1234567991002",
        "debitAmount": 1000,
        "narration": "Payment for Services",
        "mandateCode": "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0"
    }
}

Get Debit Status

This endpoint gets the status of a debited mandate
GET
{{base_url}}/api/v1/direct-debit/mandate/debit-status

Headers

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

Body Params

paymentReference
String

The payment reference used in debiting a mandate
REQUEST
Copy button
curl -H "Accept: application/json" 
{{monnify_base_url}}/api/v1/direct-debit/mandate/debit-status?paymentReference=String
RESPONSE
Copy button
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "transactionStatus": "PAID",
        "responseMessage": null,
        "transactionReference": "MNFY|20240519180055|000001",
        "paymentReference": "PR1234567991002",
        "debitAmount": 1000,
        "narration": "Payment for Services",
        "mandateCode": "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0"
    }
}

Update Mandate

This endpoint cancels/deactivate a mandate
PATCH
{{base_url}}/api/v1/direct-debit/mandate/cancel-mandate/{{mandateCode}}

Headers

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

Body Params

mandateCode
String

Monnify generated mandate identifier
REQUEST
Copy button
curl --header "Content-Type: application/json" 
 --request POST 
 --data '{}' 
 https://sandbox.monnify.com/api/v1/direct-debit/mandate/cancel-mandate/MTDD%7C01HY8W3FBKHTFBZP9DQ9KNHR1G
RESPONSE
Copy button
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "responseMessage": "Mandate has been requested to be cancelled.",
        "mandateReference": "unique_ref3_02s600972",
        "mandateCode": "MTDD|01HY8W3FBKHTFBZP9DQ9KNHR1G",
        "mandateStatus": "ACTIVE"
    }
}

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