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
- 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
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
Live Mode(base_url): https://api.monnify.com
Authentication
Generate Access Token
POST
{{base_url}}/api/v1/auth/login
Headers
Authorization
basic
Authorize this API call by including Authorization header that contains the word 'Basic' followed by a space and a base64-encoded string 'apiKey:clientSecret' i.e. 'Basic base64(ApiKey:SecretKey)', include the Token in the request header.
Body Params
REQUEST
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
The amount(in Naira) to be paid, minimum is N20
customerName
String
The name of the customer
customerEmail
String
The customer email
paymentReference
String
A unique string of characters that identifies each transaction
paymentDescription
String
A description of the payment
currencyCode
String
The currency code
contractCode
String
The merchant contract code
redirectUrl
String
A url to redirect to after payment completion
paymentMethods
String
The method of payment collection
incomeSplitConfig
Object
A way to split payments among subAccounts.
metadata
Object
This field can be used to pass extra information from customers
REQUEST
{"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
A unique Monnify reference returned as part of the response from the initialise transaction endpoint
bankCode
String
A valid bank code to enable the creation of USSD string associated with such bank
REQUEST
{"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}}
Charge Card
This endpoint allows you to initiate charge on a card.
POST
{{base_url}}/api/v1/merchant/cards/charge
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
transactionReference
String
The transaction reference gotten as part of the response from the initialise transaction endpoint.
collectionChannel
String
This field basically describes the channel of collection.
card
Object
An object containing the card information.
number
String
The card pan or number on the card.
pin
String
The pin associated with the card.
expiryMonth
String
The card expiry month.
expiryYear
String
The card expiry year
cvv
String
The card cvv number.
REQUEST
{"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/charge
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
transactionReference
String
The transaction reference gotten from the initialise transaction endpoint.
collectionChannel
String
This is the channel of collection and should always be "API_NOTIFICATION" in this endpoint.
tokenId
String
This is an id of the token issued and is always part of the response from the charge card endpoint.
token
String
This is the token(OTP) sent to the user device by his bank
REQUEST
{"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
The transaction reference gotten from the initialise transaction endpoint.
collectionChannel
String
This is the channel of collection and should always be "API_NOTIFICATION" in this endpoint.
card
Object
An object containing the card information.
number
String
The card pan or number on the card.
pin
String
The pin associated with the card.
expiryMonth
String
The card expiry month.
expiryYear
String
The card expiry year
cvv
String
The card cvv number.
apiKey
String
The merchant API key
REQUEST
{"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.
to
Timestamp
The maximum time for transactions to be retrieved.
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
GET
{{base_url}}/api/v2/transactions/MNFY%7C67%7C20220725111957%7C000283
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
transactionReference
String
Urlencoding of the said transaction reference
REQUEST
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": {}}}
Customer Reserved Account
Create Reserved Account(General)
This endpoint allows the creation of dedicated virtual accounts for your customers.
POST
{{base_url}}/api/v2/bank-transfer/reserved-accounts
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
accountReference
String
A unique reference generated by merchants.
accountName
String
The name to be displayed during name enquiry
currencyCode
String
The currency allowed,"NGN.
contractCode
String
The merchant contract code
customerEmail
String
The customer's email
bvn
String
The bvn attached to a reserve account
getAllAvailableBanks
Boolean
This decides wether account numbers be generated to all allowable banks.
preferredBanks
Array
This field helps to choose certain banks for virtual account creation. This field is needed if getAvailableBanks is false
incomeSplitConfig
Object
A configuration on how payments are to be split among subaccounts
restrictPaymentSource
Boolean
Decides if payment should be restricted to some reserved accounts
allowedPaymentSource
Object
This captures bvns or account numbers or account names that are permitted to fund a reserved account. This is mandatory if restrictPaymentSource is set to true
REQUEST
{ "accountReference": "abc123d380","accountName": "ysbbs hsbsb nxnznq","currencyCode": "NGN","contractCode": "7059707855","customerEmail": "[email protected]","customerName": "ysbbs hsbsb nxnznq","bvn": "54848484888","getAllAvailableBanks": true}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "abc123d380","accountName": "ysb","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "ysbbs hsbsb nxnznq","accounts": [{"bankCode": "035","bankName": "Wema bank","accountNumber": "5000606570","accountName": "ysb"},{"bankCode": "232","bankName": "Sterling bank","accountNumber": "6001363048","accountName": "ysb"}],"collectionChannel": "RESERVED_ACCOUNT","reservationReference": "DQD6S0N4U20FN8MF2EE1","reservedAccountType": "GENERAL","status": "ACTIVE","createdOn": "2022-07-27 15:29:40.131","incomeSplitConfig": [],"bvn": "54848484888","restrictPaymentSource": false}}
Create Reserved Account(Invoice)
This endpoint allows the creation of an invoiced reserved account.
POST
{{base_url}}/api/v1/bank-transfer/reserved-accounts
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
contractCode
String
The merchant's contract code.
accountName
String
The name to be displayed during name enquiry.
currencyCode
String
The currency allowed,"NGN.
accountReference
String
A unique reference generated by the merchant
customerName
String
Full name of the customer
customerEmail
String
Email address of the customer.
reservedAccountType
String
This should be "INVOICE".
REQUEST
{"contractCode":"7059707855","accountName":"Jane Doe","currencyCode":"NGN","accountReference": "janedoe1223--3","customerEmail": "[email protected]","customerName": "Jane Doe","reservedAccountType": "INVOICE"}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "janedoe1223--3","accountName": "Jan","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "Jane Doe","accountNumber": "5000588070","bankName": "Wema bank","bankCode": "035","collectionChannel": "RESERVED_ACCOUNT","reservationReference": "E0HXPHGPPNADE9FE1QT6","reservedAccountType": "INVOICE","status": "INACTIVE","createdOn": "2022-07-31 13:52:07.402","incomeSplitConfig": [],"restrictPaymentSource": false}}
Get Reserved Account Details
This endpoint returns details of an account reserved for a customer
GET
{{base_url}}/api/v2/bank-transfer/reserved-accounts/{accountReference}
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
accountReerence
String
The unique reference used in creating the reserved account.
REQUEST
curl -H "Accept: application/json"{{base_url}}/api/v2/bank-transfer/reserved-accounts/abc1niui--23
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "abc1niui--23","accountName": "Test01-Tes","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "mao Zhang","accounts": [{"bankCode": "035","bankName": "Wema bank","accountNumber": "5000588053","accountName": "Tes"},{"bankCode": "232","bankName": "Sterling bank","accountNumber": "6001363175","accountName": "Tes"}],"collectionChannel": "RESERVED_ACCOUNT","reservationReference": "8MD1E79P4LD94N6E2VNJ","reservedAccountType": "GENERAL","status": "ACTIVE","createdOn": "2022-07-31 10:08:41.0","contract": {"name": "Default Contract","code": "7059707855","description": null},"transactionCount": 0,"incomeSplitConfig": [{"subAccountCode": "MFY_SUB_762212281785","feePercentage": 10.5,"feeBearer": true,"splitPercentage": 20,"reservedAccountConfigCode": "HRCNXDSAYX"}],"bvn": "21212121212","restrictPaymentSource": true}}
Add Linked Accounts
This endpoint links accounts with another partner bank to an existing customer.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/add-linked-accounts/{accountReference}
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
getAllAvailableBanks
Boolean
Determine if all necessary banks should be used
preferredBanks
Array
Contains bank codes of desired banks
accountReference
String
The unique reference used in creating the reserved account.
REQUEST
{"getAllAvailableBanks": false,"preferredBanks": ["232"]}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "abc1niui--23","accountName": "Tes","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "mao Zhang","accounts": [{"bankCode": "035","bankName": "Wema bank","accountNumber": "5000588053","accountName": "Tes"},{"bankCode": "232","bankName": "Sterling bank","accountNumber": "6001363175","accountName": "Tes"}],"collectionChannel": "RESERVED_ACCOUNT","reservationReference": "8MD1E79P4LD94N6E2VNJ","reservedAccountType": "GENERAL","status": "ACTIVE","createdOn": "2022-07-31 10:08:41.0","incomeSplitConfig": [{"subAccountCode": "MFY_SUB_762212281785","feePercentage": 10.5,"feeBearer": true,"splitPercentage": 20,"reservedAccountConfigCode": "HRCNXDSAYX"}],"bvn": "21212121212","restrictPaymentSource": true}}
Update BVN for a Reserve Account
This endpoint updates BVN of customers reserved account
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/update-customer-bvn/{reservedAccountReference}
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
bvn
String
The BVN used in creating the reserved account
REQUEST
{"bvn": "21212121212"}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "915483727511","accountReference": "121612212051585","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "Pascool Oj","accountNumber": "4290733572","bankName": "Providus Bank","bankCode": "101","collectionChannel": "RESERVED_ACCOUNT","reservationReference": "R8J4LCW3P82WN4X6LQCW","reservedAccountType": "GENERAL","status": "ACTIVE","createdOn": "2021-02-01 21:40:55.0","bvn": "21212121212","restrictPaymentSource": false}}
Allowed Payment Source(s)
This endpoint manages accounts that can fund a reserved account using either BVNs, Account Name or Account Number.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/update-payment-source-filter/{accountReference}
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
restrictPaymentSource
Boolean
This field activate or de-activate restricting of payment sources for a reserved account.
allowedPaymentSource
Object
A collection of possible payment sources.
bvns
Array
List of BVNs that should be validated
bankAccounts
Array
List of account numbers that can fund the reserved account.
accountNumbers
String
An account number from which reserved account can be funded.
bankCode
String
A 3 digit CBN code for the account
accountNames
Array
List of account names for accounts from which reserved accounts can be funded.
accountReference
String
The unique reference used in creating the reserved account.
REQUEST
{"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/{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 '{}'{{base_url}}/api/v1/bank-transfer/reserved-accounts/5000588053
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "abc1niui--23","accountName": "Tes","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "mao Zhang","accountNumber": "5000588053","bankName": "Wema bank","bankCode": "035","collectionChannel": "RESERVED_ACCOUNT","reservationReference": "8MD1E79P4LD94N6E2VNJ","reservedAccountType": "GENERAL","status": "ACTIVE","createdOn": "2022-07-31 10:08:41.0","incomeSplitConfig": [{"subAccountCode": "MFY_SUB_762212281785","feePercentage": 10.5,"feeBearer": false,"splitPercentage": 0,"reservedAccountConfigCode": "HRCNXDSAYX"},{"subAccountCode": "MFY_SUB_322165393053","feePercentage": 0,"feeBearer": false,"splitPercentage": 30,"reservedAccountConfigCode": "HRCNXDSAYX"}],"bvn": "22342115371","restrictPaymentSource": true}}
Get Reserved Account Transactions
This endpoint returns the list of all transactions done on a reserved account.
GET
{{base_url}}/api/v1/bank-transfer/reserved-accounts/transactions
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
accountReference
String
The unique reference used in creating the reserved account.
page
Integer
The page of data you want returned by Monnify (Starts from 0).
size
Integer
The number of records you want returned in a page.
REQUEST
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}}
Invoice
Create an Invoice
This endpoint creates invoice for payments on your integration.
POST
{{base_url}}/api/v1/invoice/create
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
amount
Float
The amount to be paid by the customer
currencyCode
String
The currency of the transaction being initialized. "NGN"
invoiceReference
String
Merchant's Unique reference for the invoice
customerName
String
Full name of the customer
customerEmail
String
Email of the customer
contractCode
String
Merchant's contract code
description
String
Description of the transaction. Will be used as the account name for bank transfer payments
expiryDate
String
The expiry date for the invoice. The format is:YYYY-MM-DD HH:MM:SS
incomeSplitConfig
Object
This field contains specifications on how payments to this reserve account should be split.
redirectUrl
String
A URL which customer will be redirected to when payment is successfully completed
REQUEST
{"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": "Wema bank","bankCode": "035","redirectUrl": "http://app.monnify.com","transactionReference": "MNFY|99|20220731121414|000867","incomeSplitConfig": [{"subAccountCode": "MFY_SUB_322165393053","splitAmount": 20,"feePercentage": 10.5,"feeBearer": true,"splitPercentage": null}]}}
View Invoice Details
This endpoint returns details of an invoice on your integration.
GET
{{base_url}}/api/v1/invoice/{invoiceReference}/details
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
invoiceReference
String
The unique reference used in creating the invoice.
REQUEST
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": "Wema bank","bankCode": "035","transactionReference": "MNFY|99|20220731122925|000868","incomeSplitConfig": [{"subAccountCode": "MFY_SUB_322165393053","splitAmount": 20,"feePercentage": 10.5,"feeBearer": true,"splitPercentage": 0}]}}
Get All Invoices
This endpoint returns the list of all the invoice available on your integration.
GET
{{base_url}}/api/v1/invoice/all
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
REQUEST
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": "Wema bank","bankCode": "035"},{"amount": 999,"invoiceReference": "183891300182","invoiceStatus": "PENDING","description": "test invoice","contractCode": "7059707855","customerEmail": "[email protected]","customerName": "John Snow","expiryDate": "2022-10-30 12:00:00","createdBy": "MK_TEST_JRQAZRFD2W","createdOn": "2022-07-31 12:14:15","accountNumber": "5000588061","bankName": "Wema bank","bankCode": "035"},{"amount": 900,"invoiceReference": "183891182","invoiceStatus": "PAID","description": "test invoice","contractCode": "7059707855","customerEmail": "[email protected]","customerName": "John Snow","expiryDate": "2022-05-30 12:00:00","createdBy": "MK_TEST_JRQAZRFD2W","createdOn": "2022-05-20 10:07:52"},{"amount": 999,"invoiceReference": "1838913189","invoiceStatus": "EXPIRED","description": "test invoice","contractCode": "7059707855","customerEmail": "[email protected]","customerName": "John Snow","expiryDate": "2022-03-30 12:00:00","createdBy": "MK_TEST_JRQAZRFD2W","createdOn": "2022-03-09 12:18:58","accountNumber": "5000654355","bankName": "Wema bank","bankCode": "035"},{"amount": 999,"invoiceReference": "1838913187","invoiceStatus": "EXPIRED","description": "test invoice","contractCode": "7059707855","customerEmail": "[email protected]","customerName": "John Snow","expiryDate": "2022-03-30 12:00:00","createdBy": "MK_TEST_JRQAZRFD2W","createdOn": "2022-03-09 12:18:40","accountNumber": "5000654354","bankName": "Wema bank","bankCode": "035"},{"amount": 999,"invoiceReference": "1838913182","invoiceStatus": "EXPIRED","description": "test invoice","contractCode": "7059707855","customerEmail": "[email protected]","customerName": "John Snow","expiryDate": "2022-03-30 12:00:00","createdBy": "MK_TEST_JRQAZRFD2W","createdOn": "2022-03-09 11:55:45","accountNumber": "5000654351","bankName": "Wema bank","bankCode": "035"}],"pageable": {"sort": {"sorted": true,"unsorted": false,"empty": false},"pageSize": 10,"pageNumber": 0,"offset": 0,"unpaged": false,"paged": true},"last": true,"totalElements": 6,"totalPages": 1,"sort": {"sorted": true,"unsorted": false,"empty": false},"first": true,"numberOfElements": 6,"size": 10,"number": 0,"empty": false}}
Cancel an Invoice
This endpoint cancels an Invoice on your integration.
DELETE
{{base_url}}/api/v1/invoice/{invoiceReference}/cancel
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
invoiceReference
String
The unique reference used in creating the invoice.
REQUEST
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": "Wema bank","bankCode": "035"}}
Attaching a Reserved Account to an Invoice
This endpoint attaches a Reserved Account to an Invoice.
POST
{{base_url}}/api/v1/invoice/create
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
amount
Float
Amount to be paid
currencyCode
String
The currency of the transaction being initialized. "NGN"
invoiceReference
String
Merchant's Unique reference for the invoice.
customerName
String
Full name of the customer
customerEmail
String
Email address of the customer
contractCode
String
Merchant's contract code
description
String
Description for the transaction.
expiryDate
String
Expiry date for the invoice
incomeSplitConfig
Object
This field contains specifications on how payments to this reserve account should be split.
accountReference
String
Your unique reference used to identify this reserved account
REQUEST
{"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": "GTBank","bankCode": "058"}}
Recurring Payment
Charge Card Token
This endpoint allows you to charge an already tokenized card with it’s card token.
**NOTE**: The customer email address used in the first successful charge should be stored along with the card token.
POST
{{base_url}}/api/v1/merchant/cards/charge-card-token
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
REQUEST
{"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"}
Sub Accounts
Create Sub Account(s)
This endpoint allows you to create a sub account to enable the spliting of payments between different accounts.
POST
{{base_url}}/api/v1/sub-accounts
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
currencyCode
String
Settlement currency. "NGN"
accountNumber
String
The account number that should be created as a sub account.
bankCode
String
The 3 digit bank code of the bank where the account number is domiciled
email
String
The email tied to the sub account
defaultSplitPercentage
Float
The default percentage to be split into the sub account on any transaction.
REQUEST
[{"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": "BENJAMIN CHUKWUEMEKA ONONOGBU","currencyCode": "NGN","email": "[email protected]","bankCode": "057","bankName": "Zenith bank","defaultSplitPercentage": 20,"settlementProfileCode": "8717495899","settlementReportEmails": []},{"subAccountCode": "MFY_SUB_687043136486","accountNumber": "8569214283","accountName": "MFY / 9jaCash-jaCash-ABODUNRIN OYELEKE MAICHEAL","currencyCode": "NGN","email": "[email protected]","bankCode": "035","bankName": "Wema bank","defaultSplitPercentage": 20.87,"settlementProfileCode": "8717495899","settlementReportEmails": []}]}
Update Sub Account
This endpoint updates the details of an existing sub account.
PUT
{{base_url}}/api/v1/sub-accounts
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
currencyCode
String
Settlement currency. "NGN"
accountNumber
String
The account number that should be created as a sub account.
bankCode
String
The 3 digit bank code of the bank where the account number is domiciled
email
String
The email tied to the sub account
defaultSplitPercentage
Float
The default percentage to be split into the sub account on any transaction.
subAccountCode
String
The sub account code of the account to be updated.
REQUEST
{"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
Amount to disburse
reference
String
The unique reference for the transaction
narration
String
The Narration for the transactions being processed
destinationBankCode
String
The 3 digit bank code representing the destination bank
destinationAccountNumber
String
The beneficiary account number
currency
String
The currency of the transaction being initialised - "NGN"
sourceAccountNumber
String
Unique identifier of your wallet
REQUEST
{"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": "BENJAMIN CHUKWUEMEKA ONONOGBU","destinationBankName": "Zenith bank","destinationAccountNumber": "2085886393","destinationBankCode": "057"}}
Asynchronous Transfer
This endpoint helps initiate transfer asynchronously to desired bank account.
POST
{{base_url}}/api/v2/disbursements/single
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
amount
Float
Amount to disburse
reference
String
The unique reference for the transaction
narration
String
The Narration for the transactions being processed
destinationBankCode
String
The 3 digit bank code representing the destination bank
destinationAccountNumber
String
The beneficiary account number
currency
String
The currency of the transaction being initialised - "NGN"
sourceAccountNumber
String
Unique identifier of your wallet
async
Boolean
An option to process disbursement 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": "BENJAMIN CHUKWUEMEKA ONONOGBU","destinationBankName": "Zenith bank","destinationAccountNumber": "2085886393","destinationBankCode": "057"}}
Authorize Bulk Transfers
This endpoint authorizes bulk transfers on your integration.
POST
{{base_url}}/api/v2/disbursements/batch/validate-otp
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
reference
String
The batch reference used in the transfer
authorizationCode
String
The OTP sent to the merchant's email
REQUEST
{"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.
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": "BENJAMIN CHUKWUEMEKA ONONOGBU","destinationBankCode": "057","destinationBankName": "Zenith bank"}}
List All Single Transfers
This endpoint returns the list of all single transfers made on your integration.
GET
{{base_url}}/api/v2/disbursements/single/transactions
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
pageSize
Integer
The number of transfer records to return
pageNo
Integer
A number specifying what page of transfers to be retrieved
REQUEST
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
String
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}}
Bulk Transfer Status
This endpoint verifies the status of a bulk transfer on your integration.
GET
{{base_url}}/api/v2/disbursements/bulk/batchreference--12934/transactions
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
batchReference
String
A unique reference identifying the batch disbursement
REQUEST
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}}
Search Disbursement Transactions
This endpoint returns the list of all disbursement transactions.
GET
{{base_url}}/api/v2/disbursements/search-transactions
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
sourceAccountNumber
String
The merchant's WALLET ACCOUNT NUMBER, this parameter is mandatory
pageSize
Integer
The number of records to return
pageNo
Integer
The current page from the total
startDate
String
A timestamp value specifying the date to start filtering disbursement transactions by the createdAt field
endDate
String
A timestamp value specifying the date to stop filtering disbursement transactions by the createdAt field
amountFrom
String
A number specifying the lower bound for filtering the transactions by the amount field
amountTo
String
A number specifying the upper bound for filtering the transactions by the amount field.
REQUEST
curl -H "Accept: application/json"{{base_url}}/api/v2/disbursements/search-transactions?sourceAccountNumber=3934178936
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"content": [{"amount": 200,"reference": "refere--n00ce---1290--034","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": true,"status": "EXPIRED","transactionDescription": "Transaction has expired","transactionReference": "MFDS20220731044951AABQGV","createdOn": "2022-07-31T15:49:51.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "2085886393","destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU","destinationBankCode": "057","destinationBankName": "Zenith bank"},{"amount": 230,"reference": "Final-Ref--er-ence-3a","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": true,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731044903AABQGU","createdOn": "2022-07-31T15:49:04.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "0111946768","destinationAccountName": "MEKILIUWA SMART CHINONSO","destinationBankCode": "058","destinationBankName": "GTBank"},{"amount": 570,"reference": "Final-Ref-e--rence-2a","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": true,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731044903AABQGT","createdOn": "2022-07-31T15:49:04.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "0111946768","destinationAccountName": "MEKILIUWA SMART CHINONSO","destinationBankCode": "058","destinationBankName": "GTBank"},{"amount": 1300,"reference": "Final-Ref--ere-nce-1a","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": true,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731044903AABQGS","createdOn": "2022-07-31T15:49:04.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "0111946768","destinationAccountName": "MEKILIUWA SMART CHINONSO","destinationBankCode": "058","destinationBankName": "GTBank"},{"amount": 200,"reference": "refere--n00ce---1290034","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": true,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731043616AABQGR","createdOn": "2022-07-31T15:36:16.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "2085886393","destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU","destinationBankCode": "057","destinationBankName": "Zenith bank"},{"amount": 230,"reference": "Final-Refer-ence-3a","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": false,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731034121AABQGQ","createdOn": "2022-07-31T14:41:21.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "0111946768","destinationAccountName": "MEKILIUWA SMART CHINONSO","destinationBankCode": "058","destinationBankName": "GTBank"},{"amount": 570,"reference": "Final-Ref-erence-2a","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": false,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731034121AABQGP","createdOn": "2022-07-31T14:41:21.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "0111946768","destinationAccountName": "MEKILIUWA SMART CHINONSO","destinationBankCode": "058","destinationBankName": "GTBank"},{"amount": 1300,"reference": "Final-Refere-nce-1a","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": false,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731034120AABQGO","createdOn": "2022-07-31T14:41:21.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "0111946768","destinationAccountName": "MEKILIUWA SMART CHINONSO","destinationBankCode": "058","destinationBankName": "GTBank"},{"amount": 200,"reference": "referen00ce---1290034","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": false,"status": "SUCCESS","transactionDescription": "Transaction successful","transactionReference": "MFDS20220731033133AABQGN","createdOn": "2022-07-31T14:31:34.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "2085886393","destinationAccountName": "BENJAMIN CHUKWUEMEKA ONONOGBU","destinationBankCode": "057","destinationBankName": "Zenith bank"},{"amount": 200,"reference": "reference---12934","narration": "911 Transaction","currency": "NGN","fee": 35,"twoFaEnabled": false,"status": "FAILED","transactionDescription": "Name enquiry failed","transactionReference": "MFDS20220731031032AABQGM","createdOn": "2022-07-31T14:10:33.000+0000","sourceAccountNumber": "3934178936","destinationAccountNumber": "5000143115","destinationBankCode": "035","destinationBankName": "Wema bank"}],"pageable": {"sort": {"sorted": true,"unsorted": false,"empty": false},"pageSize": 10,"pageNumber": 0,"offset": 0,"paged": true,"unpaged": false},"last": false,"totalPages": 6,"totalElements": 54,"sort": {"sorted": true,"unsorted": false,"empty": false},"first": true,"numberOfElements": 10,"size": 10,"number": 0,"empty": false}}
Get Wallet Balance
This endpoint returns the available balance in your monnify wallet.
GET
{{base_url}}/api/v2/disbursements/wallet-balance
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
accountNumber
String
The merchant's WALLET ACCOUNT NUMBER.
REQUEST
curl -H "Accept: application/json"https://sandbox.monnify.com/api/v2/disbursements/wallet-balance?accountNumber=String
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"availableBalance": 378.93,"ledgerBalance": 378.93}}
Wallet
Create Wallet
This endpoint creates wallets for merchants' customers
POST
{{base_url}}/api/v1/disbursements/wallet
Headers
Authorization
basic
Authorize this API call by including Authorization header that contains the word 'Basic' followed by a space and a base64-encoded string 'apiKey:clientSecret' i.e. 'Basic base64(ApiKey:SecretKey)', include the Token in the request header.
Body Params
walletReference
String
A unique identifier for the wallet
walletName
String
The desired wallet name
customerName
String
The customer's name
customerEmail
String
The customer's email
bvn
String
The customer's bvn
bvnDateOfBirth
String
The date of birth associated with the bvn in the format yyyy-mm-dd
REQUEST
{"walletReference":"ref1684248425966","walletName":"Staging Wallet - ref1684248425966","customerName": "John Doe","bvnDetails": {"bvn": "22222222226","bvnDateOfBirth": "1993-10-03"},"customerEmail": "[email protected]"}
RESPONSE
{"requestSuccessful": false,"responseMessage": "bvnDetails.bvn could not be validated","responseCode": "99"}
Wallet Balance
This endpoint returns the balance associated with a wallet
GET
{{base_url}}/api/v1/disbursements/wallet/balance
Headers
Authorization
basic
Authorize this API call by including Authorization header that contains the word 'Basic' followed by a space and a base64-encoded string 'apiKey:clientSecret' i.e. 'Basic base64(ApiKey:SecretKey)', include the Token in the request header.
Body Params
walletReference
String
The unique identifier of the wallet
REQUEST
curl -H "Accept: application/json"{{monnify_base_url}}/api/v1/disbursements/wallet/balance?accountNumber=9318673649
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"availableBalance": 5000000000,"ledgerBalance": 5000000000}}
Get Wallets
This endpoint returns all the wallets created by a merchant
GET
{{base_url}}/api/v1/disbursements/wallet
Headers
Authorization
basic
Authorize this API call by including Authorization header that contains the word 'Basic' followed by a space and a base64-encoded string 'apiKey:clientSecret' i.e. 'Basic base64(ApiKey:SecretKey)', include the Token in the request header.
Body Params
customerEmail
String
The customer's email
pageSize
Integer
The number of wallet records to return
pageNo
Integer
A number specifying what page of wallets to be retrieved
REQUEST
curl -H "Accept: application/json"{{monnify_base_url}}/api/v1/disbursements/wallet?walletReference=ref1684248425960
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"content": [],"pageable": {"sort": {"sorted": true,"unsorted": false,"empty": false},"pageSize": 10,"pageNumber": 0,"offset": 0,"paged": true,"unpaged": false},"last": true,"totalPages": 0,"totalElements": 0,"sort": {"sorted": true,"unsorted": false,"empty": false},"first": true,"numberOfElements": 0,"size": 10,"number": 0,"empty": true}}
Wallet Transactions
This endpoint returns all the transactions performed by a wallet
GET
{{base_url}}/api/v1/disbursements/wallet/transactions
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
accountNumber
String
The walletAccountNumber
pageSize
Integer
The number of wallet records to return
pageNo
Integer
A number specifying what page of wallets to be retrieved
REQUEST
curl -H "Accept: application/json"{{monnify_base_url}}/api/v1/disbursements/wallet/transactions?accountNumber=9318673649
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"content": [],"pageable": {"sort": {"sorted": false,"unsorted": true,"empty": true},"pageSize": 10,"pageNumber": 0,"offset": 0,"paged": true,"unpaged": false},"last": true,"totalPages": 0,"totalElements": 0,"sort": {"sorted": false,"unsorted": true,"empty": true},"first": true,"numberOfElements": 0,"size": 10,"number": 0,"empty": true}}
Limit Profile
Create Limit Profile(s)
This endpoint creates limit profiles on a customer's account.
POST
{{base_url}}/api/v1/limit-profile/
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
limitProfileName
String
The name of the Limit Profile
singleTransactionValue
Float
The maximum amount that can be allowed per transaction on the reserved accounts.
dailyTransactionValue
Float
The maximum amount per day in all transactions that can be allowed on the reserved accounts
dailyTransactionVolume
Float
The maximum number of transaction count per day allowed on the reserved accounts
REQUEST
{"limitProfileName":"Profile0001","singleTransactionValue":2000,"dailyTransactionVolume":500,"dailyTransactionValue": 150000}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"limitProfileCode": "FSYVVWU8UPBD","limitProfileName": "Profile0001","singleTransactionValue": 2000,"dailyTransactionVolume": 500,"dailyTransactionValue": 150000,"dateCreated": "02/08/2022 02:27:43 AM","lastModified": "02/08/2022 02:27:43 AM"}}
Get Limit Profiles
This endpoint returns the list of all Limit Profiles that have been created for your customers.
GET
{{base_url}}/api/v1/limit-profile/
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/limit-profile/
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"content": [{"limitProfileCode": "3YXDEFS7ZWB4","limitProfileName": "Benji profile","singleTransactionValue": 2000,"dailyTransactionVolume": 500,"dailyTransactionValue": 150000,"dateCreated": "13/07/2022 10:08:00 PM","lastModified": "13/07/2022 10:08:00 PM"},{"limitProfileCode": "HW5YMHPFPS86","limitProfileName": "Profile001","singleTransactionValue": 2000,"dailyTransactionVolume": 500,"dailyTransactionValue": 150000,"dateCreated": "02/08/2022 12:43:56 AM","lastModified": "02/08/2022 12:43:56 AM"},{"limitProfileCode": "FSYVVWU8UPBD","limitProfileName": "prof991","singleTransactionValue": 70000,"dailyTransactionVolume": 4000,"dailyTransactionValue": 100000000,"dateCreated": "02/08/2022 02:27:44 AM","lastModified": "02/08/2022 02:45:26 AM"}],"pageable": {"sort": {"sorted": false,"unsorted": true,"empty": true},"pageSize": 10,"pageNumber": 0,"offset": 0,"paged": true,"unpaged": false},"last": true,"totalElements": 3,"totalPages": 1,"sort": {"sorted": false,"unsorted": true,"empty": true},"first": true,"numberOfElements": 3,"size": 10,"number": 0,"empty": false}}
Update Limit Profile
This endpoint updates the information on an existing Limit Profile.
PUT
{{base_url}}/api/v1/limit-profile/FSYVVWU8UPBD
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
limitProfileName
String
The name of the Limit Profile
singleTransactionValue
Float
The maximum amount that can be allowed per transaction on the reserved accounts.
dailyTransactionValue
Float
The maximum amount per day in all transactions that can be allowed on the reserved accounts
dailyTransactionVolume
Float
The maximum number of transaction count per day allowed on the reserved accounts
limitProfileCode
String
The generated limit profile code passed as path parameter
REQUEST
{"limitProfileName":"prof991","singleTransactionValue":70000,"dailyTransactionVolume":4000,"dailyTransactionValue": 100000000}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"limitProfileCode": "FSYVVWU8UPBD","limitProfileName": "prof991","singleTransactionValue": 70000,"dailyTransactionVolume": 4000,"dailyTransactionValue": 100000000,"dateCreated": "02/08/2022 02:27:44 AM","lastModified": "02/08/2022 02:45:25 AM"}}
Reserve Account with Limit
This endpoint reserves an account for your customers with a transaction limit profile on it.
POST
{{base_url}}/api/v1/bank-transfer/reserved-accounts/limit
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
accountReference
String
A unique reference generated by merchants.
accountName
String
The name to be displayed during name enquiry
currencyCode
String
The currency payments will be received with
contractCode
String
The merchant contract code
customerEmail
String
The customer's email
incomeSplitConfig
Object
A configuration on how payments are to be split among subaccounts
limitProfileCode
String
The unique identifier that references the limit profile to associate with the reserved account
String
REQUEST
{"contractCode":"7059707855","accountName":"Kan Yo' Reserved with Limit ","currencyCode":"NGN","accountReference": "ref-00--7","customerEmail": "[email protected]","customerName": "Kan Yo","limitProfileCode": "FSYVVWU8UPBD"}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "ref-00--7","accountName": "Kan","currencyCode": "NGN","customerEmail": "[email protected]","customerName": "Kan Yo","accountNumber": "5000578928","bankName": "Wema bank","bankCode": "035","collectionChannel": "RESERVED_ACCOUNT","reservationReference": "0B70FP4CNC61U334XFG1","reservedAccountType": "GENERAL","status": "ACTIVE","createdOn": "2022-08-02 02:53:25.617","incomeSplitConfig": [],"restrictPaymentSource": false,"limitProfileConfig": {"limitProfileCode": "FSYVVWU8UPBD","singleTransactionValue": 70000,"dailyTransactionVolume": 4000,"dailyTransactionValue": 100000000}}}
Update Reserve Account Limit
This endpoint updates the information on an existing Limit Profile for a Reserved Account.
PUT
{{base_url}}/api/v1/bank-transfer/reserved-accounts/limit
Headers
Authorization
bearer
Authorize this API call by generating a token here , include the Token in the request header.
Body Params
accountReference
String
A unique reference generated by merchants.
limitProfileCode
String
The unique identifier that references the limit profile to associate with the reserved accounts.
REQUEST
{"accountReference": "ref-00--7","limitProfileCode": "FSYVVWU8UPBD"}
RESPONSE
{"requestSuccessful": true,"responseMessage": "success","responseCode": "0","responseBody": {"contractCode": "7059707855","accountReference": "ref-00--7","currencyCode": "NGN","customerEmail": "[email protected]","customerName&quo