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

Successful Collection (for successful payments made on your account)
...Read more
Successful Disbursement (for disbursement transactions with a successful definite status)
...Read more
Failed Disbursement (for failed disbursement transactions)
...Read more
Reversed Disbursement (for reversed disbursement transactions)
...Read more
Successful Refund (for successfully processed initiated refunds)
...Read more
Failed Refund (for failed initiated refunds)
...Read more
Settlement Completion (for successfully processed settlements to your bank account or wallet)
...Read more
Completed Oflline Payments
...Read more
Notification for Rejected Payments
...Read more
Mandate Status Change
...Read more

Structure and Sample

A typical event notification structure is of the format:

Sample event notification structure
{ 
        "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.

Monnify Environments

Sandbox Mode(base_url): https://sandbox.monnify.com

Live Mode(base_url): https://api.monnify.com

Authentication

Generate Access Token

This endpoint allows the user to authenticate and obtain an 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
curl --header "Content-Type: application/json" 
 --request POST 
 --data '{}' 
 {{sandbox_url}}/api/v1/auth/login

RESPONSE
 
{
    "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(required)

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

customerName

String

The name of the customer

customerEmail

String(required)

The customer email

paymentReference

String(required)

A unique string of characters that identifies each transaction

paymentDescription

String

A description of the payment

currencyCode

String(required)

The currency code

contractCode

String(required)

The merchant contract code

redirectUrl

String

A url to redirect to after payment completion

paymentMethods

String

The method of payment collection

incomeSplitConfig

List<IncomeSplitConfig>

A way to split payments among subAccounts. IncomeSplitConfig { String subAccountCode; Float feePercentage; Float splitPercentage; Float splitAmount; Boolean feeBearer; }

metaData

Map<String,Object>

This field can be used to pass extra information from customers

incomeSplitConfig.subAccountCode

String(required)

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

incomeSplitConfig.feeBearer

Boolean

Boolean to determine if the sub account should bear transaction fees or not

incomeSplitConfig.feePercentage

Float

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

incomeSplitConfig.splitPercentage

Float

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

incomeSplitConfig.splitAmount

Float

The value of the amount paid that should be split into the sub account

REQUEST
{
  "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
 
{
    "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(required)

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

bankCode

String

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

REQUEST
{
  "transactionReference": "MNFY|24|20220721134824|000081",
  "bankCode": "058"
}

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

Pay with USSD

This endpoint allows you get short USSD codes for a transaction using the transactionReference of an initialized transaction and the bank code of the customer’s bank from the get banks endpoint.

POST

{{base_url}}/api/v1/merchant/ussd/initialize

Headers

Authorization

bearer

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

Body Params

transactionReference

String(required)

Transaction refrence of the initialized transaction

bankUssdCode

String(required)

USSD code of the desired bank from which payment would be made.

REQUEST
{
    "transactionReference":"MNFY|73|20241204103608|000002",
    "bankUssdCode":"737"
}

RESPONSE
 
{
    "requestSuccessful": false,
    "responseMessage": "USSD provider not configured.",
    "responseCode": "99"
}

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(required)

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

collectionChannel

String(required)

This field basically describes the channel of collection.

card

Object

An object containing the card information.

number

String(required)

The card pan or number on the card.

String(required)

The pin associated with the card.

expiryMonth

String(required)

The card expiry month.

expiryYear

String(required)

The card expiry year

cvv

String(required)

The card cvv number.

REQUEST
{
    "transactionReference": "MNFY|99|20220725110839|000256",
    "collectionChannel": "API_NOTIFICATION",
    "card": {
        "number": "4111111111111111",
        "expiryMonth": "10",
        "expiryYear": "2022",
        "pin": "1234",
        "cvv": "123"
    }
}

RESPONSE
 
{
    "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(required)

The transaction reference gotten from the initialise transaction endpoint.

collectionChannel

String(required)

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

tokenId

String(required)

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

token

String(required)

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

REQUEST
{
    "transactionReference": "MNFY|20190512185357|000002",
    "collectionChannel": "API_NOTIFICATION",
    "tokenId": "1234567890",
    "token": "123456"
}

RESPONSE
 
{
    "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(required)

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(required)

An object containing the card information.

number

String(required)

The card pan or number on the card.

String(required)

The pin associated with the card.

expiryMonth

String(required)

The card expiry month.

expiryYear

String(required)

The card expiry year

cvv

String(required)

The card cvv number.

apiKey

String(required)

The merchant API key

REQUEST
{
    "transactionReference": "MNFY|19|20210430115705|000243",
    "collectionChannel": "API_NOTIFICATION",
    "card": {
        "cvv": "123",
        "expiryMonth": "12",
        "expiryYear": "2022",
        "number": "4000000000000002",
        "pin": "1234"
    }
}

RESPONSE
 
{
    "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 in milliseconds.

Timestamp

The maximum time for transactions to be retrieved in milliseconds.

REQUEST
curl -H "Accept: application/json" 
{{base_url}}/api/v1/transactions/search?

RESPONSE
 
{
    "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 (PENDING, OVERPAID, PARTIALLY_PAID, PAID, EXPIRED, FAILED, EXPIRED, CANCELLED)

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(required)

Urlencoding of the said transaction reference

REQUEST
curl -H "Accept: application/json" 
https://sandbox.monnify.com/api/v2/transactions/MNFY%7C67%7C20220725111957%7C000283

RESPONSE
 
{
    "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 as query parameters.

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 url encoded

paymentReference

String

The merchant generated reference url encoded

REQUEST
curl -H "Accept: application/json" 
https://sandbox.monnify.com/api/v2/transactions/query?transactionReference=MNFY%7C67%7C20220725111957%7C000283

RESPONSE
 
{
    "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(required)

A unique reference generated by merchants.

accountName

String(required)

The name to be displayed during name enquiry

currencyCode

String(required)

The currency allowed,"NGN.

contractCode

String(required)

The merchant contract code

customerEmail

String(required)

The customer's email

bvn

String(required if nin is null)

The bvn attached to a reserve account

getAllAvailableBanks

Boolean(required)

This is always true in all cases.

incomeSplitConfig

List<IncomeSplitConfig>

A configuration on how payments are to be split among subaccounts IncomeSplitConfig { String subAccountCode; Float feePercentage; Float splitPercentage; Float splitAmount; Boolean feeBearer;

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(required if bvn is null)

The customer’s NIN

REQUEST
{
    "accountReference":"abc1niui23",
    "accountName":"Test Reserved Account",
    "currencyCode":"NGN",
    "contractCode":"100693167467",
    "customerEmail":"[email protected]",
    "customerName":"John Doe",
    "bvn":"21212121212",
    "getAllAvailableBanks":true,
}

RESPONSE
 
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "contractCode": "100693167467",
        "accountReference": "abc1niui23",
        "accountName": "MARVELOUS BENJI",
        "currencyCode": "NGN",
        "customerEmail": "[email protected]",
        "customerName": "John Doe",
        "accounts": [
            {
                "bankCode": "50515",
                "bankName": "Moniepoint Microfinance Bank",
                "accountNumber": "6839490147",
                "accountName": "MARVELOUS BENJI"
            }
        ],
        "collectionChannel": "RESERVED_ACCOUNT",
        "reservationReference": "96ZPXECUD84UQTB00931",
        "reservedAccountType": "GENERAL",
        "status": "ACTIVE",
        "createdOn": "2024-11-25 07:35:17.566",
        "incomeSplitConfig": [],
        "bvn": "21212121212",
        "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(required)

The merchant's contract code.

accountName

String(required)

The name to be displayed during name enquiry.

currencyCode

String(required)

The currency allowed,"NGN.

accountReference

String(required)

A unique reference generated by the merchant

customerName

String

Full name of the customer

customerEmail

String(required)

Email address of the customer.

reservedAccountType

String

This should be "INVOICE".

bvn

String(required if nin is null)

The customer's BVN

nin

String(required if bvn is null)

The customer's NIN

REQUEST
{
    "contractCode":"7059707855",
    "accountName":"Jane Doe",
    "currencyCode":"NGN",
    "accountReference": "janedoe1223--3",
    "customerEmail": "[email protected]",
    "customerName": "Jane Doe",
    "reservedAccountType": "INVOICE"
}

RESPONSE
 
{
    "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

accountReference

String(required)

The unique reference used in creating the reserved account.

REQUEST
curl -H "Accept: application/json" 
{{monnify_base_url}}/api/v2/bank-transfer/reserved-accounts/abc1niui23

RESPONSE
 
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "contractCode": "100693167467",
        "accountReference": "abc1niui23",
        "accountName": "MfyInt-MARVELOUS BENJI",
        "currencyCode": "NGN",
        "customerEmail": "[email protected]",
        "customerName": "John Doe",
        "accounts": [
            {
                "bankCode": "50515",
                "bankName": "Moniepoint Microfinance Bank",
                "accountNumber": "6839490147",
                "accountName": "MARVELOUS BENJI"
            }
        ],
        "collectionChannel": "RESERVED_ACCOUNT",
        "reservationReference": "96ZPXECUD84UQTB00931",
        "reservedAccountType": "GENERAL",
        "status": "ACTIVE",
        "createdOn": "2024-11-25 07:35:18.0",
        "contract": {
            "name": "Default Contract",
            "code": "100693167467",
            "description": null
        },
        "transactionCount": 0,
        "bvn": "21212121212",
        "restrictPaymentSource": false
    }
}

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
{
	"getAllAvailableBanks": false,
    "preferredBanks": ["50515"]
}

RESPONSE
 
{
    "requestSuccessful": false,
    "responseMessage": "Cannot find reserved account",
    "responseCode": "99"
}

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/{accountReference}

Headers

Authorization

bearer

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

Body Params

bvn

String(required)

The BVN used in creating the reserved account

accountReference

String

The unique reference used in creating the reserved account.

REQUEST
{
"bvn": "21212121212"
}

RESPONSE
 
{
    "requestSuccessful": false,
    "responseMessage": "Invalid BVN provided",
    "responseCode": "99"
}

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
{
    "restrictPaymentSource": true,
    "allowedPaymentSources": {
        "bvns": [
            "21212121212",
            "20202020202"
        ]
    }
}

RESPONSE
 
{
    "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
[
    {
        "subAccountCode": "MFY_SUB_762212281785",
        "feePercentage": 10.50
    },
       {
        "subAccountCode": "MFY_SUB_322165393053",
        "splitPercentage": 30
    }
]

RESPONSE
 
{
    "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
curl --header "Content-Type: application/json" 
 --request POST 
 --data '{}' 
 {{monnify_base_url}}/api/v1/bank-transfer/reserved-accounts/reference/{accountReference}

RESPONSE
 
{
    "requestSuccessful": false,
    "responseMessage": "Cannot find reserved account",
    "responseCode": "99"
}

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
curl -H "Accept: application/json" 
https://sandbox.monnify.com/api/v1/bank-transfer/reserved-accounts/transactions
?accountReference={accountReference}&page=0&size=10

RESPONSE
 
{
    "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
{
    "bvn":{{bvn}}
}

RESPONSE
 
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "accountReference": "a1fe1c73c6f985eb43e8ef35ec0d6a398698cdea",
        "accountName": "MARVELOUS BENJI",
        "customerEmail": "[email protected]",
        "customerName": "mao  Zhang",
        "bvn": "21212121212"
    }
}

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(required)

The amount to be paid by the customer

currencyCode

String(required)

The currency of the transaction being initialized. "NGN"

invoiceReference

String(required)

Merchant's Unique reference for the invoice

customerName

String(required)

Full name of the customer

customerEmail

String(required)

Email of the customer

contractCode

String(required)

Merchant's contract code

description

String(required)

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

expiryDate

String(required)

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

incomeSplitConfig

List<IncomeSplitConfig>

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
{
    "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
 
{
    "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": "Moniepoint Microfinance bank",
        "bankCode": "50515",
        "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(required)

The unique reference used in creating the invoice.

REQUEST
curl -H "Accept: application/json" 
{{base_url}}/api/v1/invoice/18389130010082/details

RESPONSE
 
{
    "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": "Moniepoint Microfinance bank",
        "bankCode": "50515",
        "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
curl -H "Accept: application/json" 
{{base_url}}/api/v1/invoice/all

RESPONSE
 
{
    "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": "Moniepoint Microfinance bank",
                "bankCode": "50515"
            },
            {
                "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": "Moniepoint Microfinance bank",
                "bankCode": "50515"
            },
            {
                "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": "Moniepoint Microfinance bank",
                "bankCode": "50515"
            },
            {
                "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": "Moniepoint Microfinance bank",
                "bankCode": "50515"
            },
            {
                "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": "Moniepoint Microfinance bank",
                "bankCode": "50515"
            }
        ],
        "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(required)

The unique reference used in creating the invoice.

REQUEST
curl --header "Content-Type: application/json" 
 --request POST 
 --data '{}' 
 {{base_url}}/api/v1/invoice/18389130010082/cancel

RESPONSE
 
{
    "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": "Moniepoint Microfinance bank",
        "bankCode": "50515"
    }
}

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(required)

Amount to be paid

currencyCode

String(required)

The currency of the transaction being initialized. "NGN"

invoiceReference

String(required)

Merchant's Unique reference for the invoice.

customerName

String(required)

Full name of the customer

customerEmail

String(required)

Email address of the customer

contractCode

String(required)

Merchant's contract code

description

String(required)

Description for the transaction.

expiryDate

String(required)

Expiry date for the invoice

incomeSplitConfig

List<IncomeSplitConfig>

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

accountReference

String(required)

Your unique reference used to identify this reserved account

REQUEST
{
    "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
 
{
    "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": "Moniepoint Microfinance bank",
        "bankCode": "50515"
    }
}

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

cardToken

String(required)

Card token gotten by performing a re-query on a card transaction using the Get Transaction Status API.

amount

Float(required)

customerName

String(required)

Full name of the customer

customerEmail

String(required)

Email of the customer

paymentReference

String(required)

A unique string of characters that identifies each transaction

paymentDescription

String(required)

A description of the payment

currencyCode

String(required)

The currency code

contractCode

String(required)

The merchant contract code

apiKey

String(required)

The merchant API key

metaData

Map<String,Object>

This field can be used to pass extra information from customers

incomeSplitConfig

List<IncomeSplitConfig>

A way to split payments among subAccounts. IncomeSplitConfig { String subAccountCode; Float feePercentage; Float splitPercentage; Float splitAmount; Boolean feeBearer; }

REQUEST
{

    "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
 
{
    "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(required)

The merchant’s Monnify contract code

mandateReference

String(required)

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(required)

The customer's name

customerEmailAddress

String(required)

The customer's email address

customerPhoneNumber

String(required)

The customer's phone number

customerAddress

String(required)

The customer's home address

customerAccountNumber

String(required)

The customer's bank account number

customerAccountBankCode

String(required)

The bank code of the customer’s bank account

mandateDescription

String(required)

The description of the payment the mandate is associated to

mandateStartDate

String(required)

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

mandateEndDate

String(required)

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

customerCancellation

Boolean

Informs Monnify if the Mandate can be cancelled by the customer

REQUEST
{
    "contractCode": "4934121686",
    "mandateReference": "unique_ref3_02s600972",
    "autoRenew": false,
    "customerCancellation": true,
    "customerName": "Ankit Kushwaha",
    "customerPhoneNumber": "1234567890",
    "customerEmailAddress": "[email protected]",
    "customerAddress": "123 Example Street, City, Country",
    "customerAccountName": "Ankit Kushwaha",
    "customerAccountNumber": "0051762787",
    "customerAccountBankCode": "998",
    "mandateDescription": "Subscription Fee",
    "mandateStartDate": "2024-05-22T10:15:30",
    "mandateEndDate": "2025-05-22T10:15:30"
}

RESPONSE
 
{
    "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
curl -H "Accept: application/json" 
https://sandbox.monnify.com/api/v1/direct-debit/mandate/?mandateReferences=unique_ref3_02gs600s972

RESPONSE
 
{
    "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(required)

Merchants unique reference to identify a single direct debit payment

mandateCode

String(required)

Monnify generated mandate identifier

debitAmount

String(required)

Payment amount to be debited from a single debit transaction

narration

String(required)

Description of the single debit

customerEmail

String(required)

The customer's email address

REQUEST
{
  "paymentReference": "PR1234567991002",
  "mandateCode": "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0",
  "debitAmount": 1000.00,
  "narration": "Payment for Services",
  "customerEmail":"[email protected]"
}

RESPONSE
 
{
    "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
curl -H "Accept: application/json" 
{{monnify_base_url}}/api/v1/direct-debit/mandate/debit-status?paymentReference=String

RESPONSE
 
{
    "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
curl --header "Content-Type: application/json" 
 --request POST 
 --data '{}' 
 https://sandbox.monnify.com/api/v1/direct-debit/mandate/cancel-mandate/MTDD%7C01HY8W3FBKHTFBZP9DQ9KNHR1G

RESPONSE
 
{
    "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(required)

Settlement currency. "NGN"

accountNumber

String(required)

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

bankCode

String(required)

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

String(required)

The email tied to the sub account

defaultSplitPercentage

Float(required)

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

REQUEST
[
	{
		"currencyCode": "NGN",
		"bankCode": "058",
		"accountNumber": "0211319282",
		"email": "[email protected]",
		"defaultSplitPercentage": 20.87
	}
]

RESPONSE
 
{
    "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
curl --header "Content-Type: application/json" 
 --request POST 
 --data '{}' 
 {{base_url}}/api/v1/sub-accounts/MFY_SUB_811397375865

RESPONSE
 
{
    "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
curl -H "Accept: application/json" 
{{base_url}}/api/v1/sub-accounts

RESPONSE
 
{
    "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": "Marvelous Benji",
            "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": "50515",
            "bankName": "Moniepoint Microfinance 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

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
{
	"subAccountCode": "MFY_SUB_811397375865",
	"currencyCode": "NGN",
	"bankCode": "058",
	"accountNumber": "0211319282",
	"email": "[email protected]",
	"defaultSplitPercentage": "25"
}

RESPONSE
 
{
    "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(required)

Amount to disburse

reference

String(required)

The unique reference for the transaction

narration

String(required)

The Narration for the transactions being processed

destinationBankCode

String(required)

The 3 digit bank code representing the destination bank

destinationAccountNumber

String(required)

The beneficiary account number

currency

String(required)

The currency of the transaction being initialised - "NGN"

sourceAccountNumber

String(required)

Your Wallet Account Number

REQUEST
{
    "amount": 200,
    "reference":"referen00ce---1290034",
    "narration":"911 Transaction",
    "destinationBankCode": "057",
    "destinationAccountNumber": "2085886393",
    "currency": "NGN",
    "sourceAccountNumber": "3934178936"
}

RESPONSE
 
{
    "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": "Marvelous Benji",
        "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(required)

Amount to disburse

reference

String(required)

The unique reference for the transaction

narration

String(required)

The Narration for the transactions being processed

destinationBankCode

String(required)

The 3 digit bank code representing the destination bank

destinationAccountNumber

String(required)

The beneficiary account number

currency

String(required)

The currency of the transaction being initialised - "NGN"

sourceAccountNumber

String(required)

Unique identifier of your wallet

async

Boolean

An option to process disbursment asynchronously

REQUEST
{
    "amount": 200,
    "reference":"reference-0x1290034",
    "narration":"911 Transaction",
    "destinationBankCode": "057",
    "destinationAccountNumber": "2085886393",
    "currency": "NGN",
    "sourceAccountNumber": "3934178936",
    "async":true
}

RESPONSE
 
{
    "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
{
	"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
 
{
    "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
{
    "reference":"refere--n00ce---1290034",
    "authorizationCode":"491763"
}

RESPONSE
 
{
    "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": "Marvelous Benji",
        "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
{
    "reference":"batchre-ference--12934",
    "authorizationCode":"122080"
}

RESPONSE
 
{
    "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
{
    "reference" : "{{reference}}"
}

RESPONSE
 
{
    "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. **Transaction States** - PENDING - SUCCESS - FAILED - REVERSED - PENDING_AUTHORIZATION - OTP_EMAIL_DISPATCH_FAILED

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
curl -H "Accept: application/json" 
{{base_url}}/api/v2/disbursements/single/summary?reference=referen00ce---1290034

RESPONSE
 
{
    "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": "Marvelous Benji",
        "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
curl -H "Accept: application/json" 
{{base_url}}/api/v2/disbursements/single/transactions?pageSize=20&pageNo=1

RESPONSE
 
{
    "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
curl -H "Accept: application/json" 
https://sandbox.monnify.com/api/v2/disbursements/single/transactions?pageSize=5

RESPONSE
 
{
    "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

A unique reference identifying the batch disbursement

REQUEST
curl -H "Accept: application/json" 
{{base_url}}/api/v2/disbursements/bulk/batchreference--12934/transactions

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