Initiate single and bulk NIP transfers to any Nigerian bank account, with two-factor OTP authorization, wallet-balance lookup, transfer status, list/search, and resend-OTP. As of April 2026 the request flow follows Name Inquiry → Disbursement Request and requires a verified beneficiary account name. Sender-information object supported since October 2025. Endpoints under /api/v2/disbursements/single, /api/v2/disbursements/bulk, /api/v2/disbursements/wallet-balance.
openapi: 3.1.0
info:
title: Monnify Disbursements API
description: >
Initiate single and bulk NIP transfers to Nigerian bank accounts. As of
April 2026 the disbursement flow requires Name Inquiry first then a
Disbursement Request that carries the verified beneficiary account name.
A sender-information object has been supported on initiation since
October 2025. Two-factor authorization with OTP applies to single
transfers.
version: '2.0'
contact:
name: Monnify Developer Support
url: https://developers.monnify.com
servers:
- url: https://api.monnify.com
description: Production
- url: https://sandbox.monnify.com
description: Sandbox
security:
- BearerAuth: []
tags:
- name: Single Transfers
description: Initiate, authorize, and query single transfers.
- name: Bulk Transfers
description: Initiate and query bulk transfer batches.
- name: Wallet
description: Disbursement wallet balance and metadata.
- name: Banks
description: NIP bank directory and account validation.
paths:
/api/v2/disbursements/single:
post:
summary: Monnify Initiate Single Transfer
description: Initiate a single-bank-account payout. Requires beneficiary account name verified by Name Inquiry.
operationId: initiateSingleTransfer
tags: [Single Transfers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SingleTransferRequest'
responses:
'200':
description: Transfer initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnvelope'
/api/v2/disbursements/single/validate-otp:
post:
summary: Monnify Authorize Single Transfer OTP
description: Submit the OTP returned to the merchant to authorize a pending transfer.
operationId: authorizeSingleTransferOtp
tags: [Single Transfers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizeTransferRequest'
responses:
'200':
description: Transfer authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnvelope'
/api/v2/disbursements/single/resend-otp:
post:
summary: Monnify Resend Transfer OTP
operationId: resendTransferOtp
tags: [Single Transfers]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [reference]
properties:
reference: { type: string }
responses:
'200':
description: OTP resent.
content:
application/json:
schema:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody: { type: object }
/api/v2/disbursements/single/summary:
get:
summary: Monnify Get Single Transfer Status
description: Look up the current status of a single transfer.
operationId: getSingleTransferStatus
tags: [Single Transfers]
parameters:
- name: reference
in: query
required: true
schema: { type: string }
responses:
'200':
description: Transfer status.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnvelope'
/api/v2/disbursements/single/transactions:
get:
summary: Monnify List Single Transfers
operationId: listSingleTransfers
tags: [Single Transfers]
parameters:
- name: pageNo
in: query
schema: { type: integer, default: 0 }
- name: pageSize
in: query
schema: { type: integer, default: 10 }
responses:
'200':
description: Single transfers page.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferPageEnvelope'
/api/v2/disbursements/bulk:
post:
summary: Monnify Initiate Bulk Transfer
description: Initiate a batch of transfers in one call.
operationId: initiateBulkTransfer
tags: [Bulk Transfers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkTransferRequest'
responses:
'200':
description: Bulk transfer accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkTransferEnvelope'
/api/v2/disbursements/bulk/summary:
get:
summary: Monnify Get Bulk Transfer Summary
operationId: getBulkTransferSummary
tags: [Bulk Transfers]
parameters:
- name: batchReference
in: query
required: true
schema: { type: string }
responses:
'200':
description: Bulk transfer summary.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkTransferEnvelope'
/api/v2/disbursements/bulk/{batchReference}/transactions:
get:
summary: Monnify List Bulk Transfer Items
operationId: listBulkTransferItems
tags: [Bulk Transfers]
parameters:
- name: batchReference
in: path
required: true
schema: { type: string }
- name: pageNo
in: query
schema: { type: integer, default: 0 }
- name: pageSize
in: query
schema: { type: integer, default: 10 }
responses:
'200':
description: Bulk transfer items page.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferPageEnvelope'
/api/v2/disbursements/wallet-balance:
get:
summary: Monnify Get Disbursement Wallet Balance
operationId: getWalletBalance
tags: [Wallet]
parameters:
- name: accountNumber
in: query
required: true
schema: { type: string, description: Merchant disbursement wallet account number. }
responses:
'200':
description: Wallet balance.
content:
application/json:
schema:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody:
type: object
properties:
availableBalance: { type: number }
ledgerBalance: { type: number }
/api/v1/sdk/transactions/banks:
get:
summary: Monnify List NIP Banks
description: Returns the list of supported Nigerian banks with bank codes.
operationId: listBanks
tags: [Banks]
responses:
'200':
description: Bank list.
content:
application/json:
schema:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody:
type: array
items:
type: object
properties:
code: { type: string }
name: { type: string }
ussdTemplate: { type: string }
nibssBankCode: { type: string }
/api/v1/disbursements/account/validate:
get:
summary: Monnify Validate Bank Account (Name Inquiry)
description: Return the registered account name for a bank account number.
operationId: validateBankAccount
tags: [Banks]
parameters:
- name: accountNumber
in: query
required: true
schema: { type: string }
- name: bankCode
in: query
required: true
schema: { type: string }
responses:
'200':
description: Account holder name.
content:
application/json:
schema:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody:
type: object
properties:
accountNumber: { type: string }
accountName: { type: string }
bankCode: { type: string }
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
SenderInformation:
type: object
description: Optional sender details (added October 2025).
properties:
fullName: { type: string }
phoneNumber: { type: string }
email: { type: string, format: email }
senderRef: { type: string }
IncomeSplit:
type: object
properties:
subAccountCode: { type: string }
feePercentage: { type: number }
splitAmount: { type: number }
feeBearer: { type: boolean }
SingleTransferRequest:
type: object
required: [amount, reference, narration, destinationBankCode, destinationAccountNumber, currency, sourceAccountNumber]
properties:
amount: { type: number }
reference: { type: string, description: Unique merchant reference. }
narration: { type: string, maxLength: 100 }
destinationBankCode: { type: string }
destinationAccountNumber: { type: string }
destinationAccountName:
type: string
description: Required as of March 2026 — must match the Name Inquiry result.
currency: { type: string, example: NGN }
sourceAccountNumber: { type: string, description: Merchant wallet account number. }
async: { type: boolean }
senderInformation: { $ref: '#/components/schemas/SenderInformation' }
AuthorizeTransferRequest:
type: object
required: [reference, authorizationCode]
properties:
reference: { type: string }
authorizationCode: { type: string }
BulkTransferRequest:
type: object
required: [title, batchReference, narration, sourceAccountNumber, transactionList]
properties:
title: { type: string }
batchReference: { type: string }
narration: { type: string }
sourceAccountNumber: { type: string }
onValidationFailure:
type: string
enum: [BREAK, CONTINUE]
notificationInterval:
type: integer
description: Webhook batch notification interval as a percentage (10, 20, 50, 100).
transactionList:
type: array
items:
type: object
properties:
amount: { type: number }
reference: { type: string }
narration: { type: string }
destinationBankCode: { type: string }
destinationAccountNumber: { type: string }
destinationAccountName: { type: string }
currency: { type: string, example: NGN }
Transfer:
type: object
properties:
reference: { type: string }
amount: { type: number }
destinationAccountName: { type: string }
destinationAccountNumber: { type: string }
destinationBankCode: { type: string }
currency: { type: string }
status:
type: string
enum: [SUCCESS, FAILED, REVERSED, PENDING, OTP_EMAIL_DISPATCH, PENDING_AUTHORIZATION]
narration: { type: string }
fee: { type: number }
dateCreated: { type: string, format: date-time }
BulkTransferSummary:
type: object
properties:
batchReference: { type: string }
batchStatus: { type: string }
totalAmount: { type: number }
totalFee: { type: number }
totalReceivedAmount: { type: number }
totalCount: { type: integer }
successfulCount: { type: integer }
failedCount: { type: integer }
pendingCount: { type: integer }
dateCreated: { type: string, format: date-time }
TransferEnvelope:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody: { $ref: '#/components/schemas/Transfer' }
BulkTransferEnvelope:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody: { $ref: '#/components/schemas/BulkTransferSummary' }
TransferPageEnvelope:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody:
type: object
properties:
content:
type: array
items: { $ref: '#/components/schemas/Transfer' }
number: { type: integer }
size: { type: integer }
totalElements: { type: integer }
totalPages: { type: integer }