openapi: 3.1.0
info:
title: Monnify Collections API
description: >
Accept money from customers in Nigeria via Monnify Checkout, server-to-
server card capture with 3-D Secure / OTP, charge stored card tokens,
complete bank-transfer payments, and look up transaction status.
version: '1.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: Transactions
description: Initialize, charge, query, and list collection transactions.
paths:
/api/v1/merchant/transactions/init-transaction:
post:
summary: Monnify Initialize Transaction
description: Create a pending transaction and return a checkoutUrl plus paymentReference.
operationId: initializeTransaction
tags: [Transactions]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitializeTransactionRequest'
responses:
'200':
description: Transaction initialized.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
/api/v1/merchant/bank-transfer/init-payment:
post:
summary: Monnify Pay With Bank Transfer
description: Generate a one-time NUBAN to complete an initialized transaction by bank transfer.
operationId: payWithBankTransfer
tags: [Transactions]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayWithTransferRequest'
responses:
'200':
description: Bank-transfer instructions returned.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
/api/v1/merchant/cards/charge:
post:
summary: Monnify Charge Card
description: Server-to-server card capture; returns secure-3D / OTP next step when required.
operationId: chargeCard
tags: [Transactions]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeCardRequest'
responses:
'200':
description: Card charge processed or pending authorization.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
/api/v1/merchant/cards/otp/authorize:
post:
summary: Monnify Authorize OTP
description: Submit the OTP returned by the cardholder to complete a card charge.
operationId: authorizeOtp
tags: [Transactions]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizeOtpRequest'
responses:
'200':
description: Card charge authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
/api/v1/merchant/cards/charge-card-token:
post:
summary: Monnify Charge Tokenized Card
description: Charge a stored card token previously returned on a successful card collection.
operationId: chargeCardToken
tags: [Transactions]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeCardTokenRequest'
responses:
'200':
description: Tokenized card charged.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
/api/v2/merchant/transactions/query:
get:
summary: Monnify Get Transaction Status
description: Query a transaction by paymentReference or transactionReference.
operationId: getTransactionStatus
tags: [Transactions]
parameters:
- name: paymentReference
in: query
schema: { type: string }
- name: transactionReference
in: query
schema: { type: string }
responses:
'200':
description: Transaction details.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEnvelope'
/api/v1/transactions/search:
get:
summary: Monnify Search Transactions
description: Paginated search across collection transactions by date range, status, and reference.
operationId: searchTransactions
tags: [Transactions]
parameters:
- name: page
in: query
schema: { type: integer, default: 0 }
- name: size
in: query
schema: { type: integer, default: 20 }
- name: from
in: query
schema: { type: string, format: date }
- name: to
in: query
schema: { type: string, format: date }
- name: paymentStatus
in: query
schema: { type: string, enum: [PAID, OVERPAID, PARTIALLY_PAID, PENDING, FAILED, EXPIRED] }
responses:
'200':
description: Paginated transaction page.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionPageEnvelope'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
InitializeTransactionRequest:
type: object
required: [amount, customerName, customerEmail, paymentReference, paymentDescription, contractCode, currencyCode]
properties:
amount: { type: number, example: 1500 }
customerName: { type: string, example: Jane Customer }
customerEmail: { type: string, format: email }
paymentReference: { type: string }
paymentDescription: { type: string }
contractCode: { type: string }
currencyCode: { type: string, example: NGN }
redirectUrl: { type: string, format: uri }
paymentMethods:
type: array
items: { type: string, enum: [CARD, ACCOUNT_TRANSFER, USSD, PHONE_NUMBER] }
incomeSplitConfig:
type: array
items: { $ref: '#/components/schemas/IncomeSplit' }
metaData:
type: object
additionalProperties: { type: string }
PayWithTransferRequest:
type: object
required: [transactionReference]
properties:
transactionReference: { type: string }
bankCode: { type: string }
ChargeCardRequest:
type: object
required: [transactionReference, collectionChannel, card]
properties:
transactionReference: { type: string }
collectionChannel: { type: string, example: API_NOTIFICATION }
card:
type: object
required: [number, expiryMonth, expiryYear, pin, cvv]
properties:
number: { type: string }
expiryMonth: { type: string }
expiryYear: { type: string }
pin: { type: string }
cvv: { type: string }
AuthorizeOtpRequest:
type: object
required: [transactionReference, collectionChannel, tokenId, token]
properties:
transactionReference: { type: string }
collectionChannel: { type: string }
tokenId: { type: string }
token: { type: string, description: OTP returned by the cardholder's bank. }
ChargeCardTokenRequest:
type: object
required: [cardToken, amount, customerName, customerEmail, paymentReference, contractCode]
properties:
cardToken: { type: string }
amount: { type: number }
customerName: { type: string }
customerEmail: { type: string, format: email }
paymentReference: { type: string }
contractCode: { type: string }
currencyCode: { type: string, default: NGN }
IncomeSplit:
type: object
properties:
subAccountCode: { type: string }
feePercentage: { type: number }
splitAmount: { type: number }
feeBearer: { type: boolean }
Transaction:
type: object
properties:
transactionReference: { type: string }
paymentReference: { type: string }
merchantName: { type: string }
apiKey: { type: string }
redirectUrl: { type: string }
enabledPaymentMethod: { type: array, items: { type: string } }
checkoutUrl: { type: string, format: uri }
amount: { type: number }
currencyCode: { type: string }
paymentStatus:
type: string
enum: [PAID, OVERPAID, PARTIALLY_PAID, PENDING, FAILED, EXPIRED]
paidOn: { type: string, format: date-time }
paymentMethod: { type: string }
TransactionEnvelope:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody: { $ref: '#/components/schemas/Transaction' }
TransactionPageEnvelope:
type: object
properties:
requestSuccessful: { type: boolean }
responseMessage: { type: string }
responseCode: { type: string }
responseBody:
type: object
properties:
content:
type: array
items: { $ref: '#/components/schemas/Transaction' }
number: { type: integer }
size: { type: integer }
totalElements: { type: integer }
totalPages: { type: integer }