openapi: 3.1.0 info: title: Monnify API Reference version: 2.0.0 description: | ### Get Started The Monnify API provides extensive access to the features available on our dashboard, enabling you to leverage them for your own application.
  1. Create a Monnify account on https://www.monnify.com
  2. Obtain the required API keys on the developers section of the dashboard
> [!IMPORTANT] Please note that the Monnify API is secured through Basic Authentication or OAuth (Bearer Tokens). #### Public Test Credentials - APIKEY: `MK_TEST_GC3B8XG2XX`
- Secret Key: `A663NRZA544DDPEM7KDN7Z8HRV6YXD8S`
- Contract Code: ` 5867418298`
servers: - url: https://sandbox.monnify.com - url: https://api.monnify.com tags: - name: Authentication description: >- This collection enables merchants to authenticate their keys for requests to the Monnify API - name: Transactions description: >- This collection enables merchants to initiate and confirm status of transactions on the Monnify - name: Transfers (Disbursement) description: >- This collection enables merchants to perform all disbursement operations on the Monnify API > [!IMPORTANT] Please note that the usage of the **TRANSFER** API is only available for merchants who meet the regulatory requirements for it. Kindly contact sales@monnify.com to get access to this feature. - name: Customer Reserved Account description: >- This collection enables merchants to create and manage reserved accounts for their customers - name: Direct Debit description: >- This collection enables merchants to create and manage direct debit mandates for their customers - name: Invoice description: >- This collection enables merchants to create and manage invoices for their customers - name: Recurring Payment description: >- This collection enables merchants to create and manage recurring payments for their customers - name: Sub Accounts description: >- This collection enables merchants to create and manage sub accounts on an integration. > [!IMPORTANT] Please note that usage of this API category in live environment requires approval from your relationship manager, kindly reach out to them or contact integration-support@monnify.com to get approval for this feature. - name: Limit Profile description: >- This collection enables merchants to create and manage limit profiles for their customers - name: Refund description: >- This collection enables merchants to Initiate and manage refunds for their customers - name: Settlements description: >- This collection enables merchants to view and manage settlements on their integration - name: Verification APIs description: >- This collection enables merchants to verify the identifies of their customers > [!IMPORTANT] Please note that API category can only be used in Live environment. The sample responses here mirrors the expected response from the API and can be used to setup workflows in your application. - name: Bills Payment APIs description: >- API for integrating with the Bills Payment service. This documentation provides a detailed overview of the available endpoints, including examples for requests and responses. > [!IMPORTANT] By default this is not active for all Monnify Merchants, to activate, kindly reach out to integration-support@monnify.com via email, and it’ll be activated for you. - name: Others description: >- This collection contains endpoints for other miscellaneous operations on the Monnify platform - name: Wallet description: >- This collection enables merchants create and manage subwallets for their customers > [!IMPORTANT] Please note that usage of this API category in live environment requires approval from your relationship manager, kindly reach out to them or contact sales@monnify.com to get approval for this feature. - name: Paycode API description: >- This collection enables merchants to create and manage PayCodes for their customers paths: /api/v1/auth/login: post: tags: - Authentication summary: Generate Access Token description: >- This endpoint generates an access token that would be used to authenticate all other endpoints. security: - basicAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- Basic authentication using apiKey and secretKey passed as a base64 string. `'Basic base64(apiKey:secretKey)'`. example: Basic TUtfVEVTVF9HQzNCOFhHMlhYOkE2NjNOUlpBNTQ0RERQRU03S0RON1o4SFJWNllYRDhT responses: "200 - OK": description: Successful response content: application/json: schema: $ref: "#/components/schemas/AuthResponseSuccess" "401 - Invalid Token": description: Failed Response due to Invalid Token content: application/json: schema: $ref: "#/components/schemas/AuthResponseError" "401 - No header": description: Failed Response due to no header provided content: application/json: schema: $ref: "#/components/schemas/AuthResponseNoHeaderError" components: securitySchemes: basicAuth: type: http scheme: basic description: >- Basic authentication using apiKey and secretKey. The Authorization header must contain 'Basic base64(apiKey:secretKey)'. Example: Authorization: Basic bXlBcGlLZXk6bXlTZWNyZXRLZXk= /api/v1/merchant/transactions/init-transaction: post: tags: - Transactions summary: Initialize Transaction description: >- This endpoint initialises the transaction that would be used for card payments and dynamic transfers. In sandbox mode, You can use our [Web Similator](https://websim.sdk.monnify.com/#/bankingapp) to complete this transaction via the Bank transfer option. > [!IMPORTANT] **NOTE**: It is important to confirm that the values returned by this endpoint (and the SDK) corresponds to the values you provided in the request payload, as bad actors can intercept the request and make alterations to values such as the transaction amount. security: - bearerAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: content: application/json: schema: $ref: "#/components/schemas/InitializeTransactionRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InitializeTransactionSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/merchant/bank-transfer/init-payment: post: tags: - Transactions summary: Pay With Bank Transfer description: >- This endpoint generates a dynamic account number and its associated bank for one time payment. security: - bearerAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: content: application/json: schema: $ref: "#/components/schemas/InitBankTransferPaymentRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InitBankTransferPaymentSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/merchant/cards/charge: post: tags: - Transactions summary: Charge a Card description: >- Initiate a charge on a card. #### Test Card Info:
+ Card Without OTP: `4111111111111111 10/2025 1234 123`
+ Card With OTP: `5060995994247093 12/2025 1234 123`
+ Card With 3DS: `4000000000000002 12/2025 1234 123`
+ Failed Card: `4111111111111110 10/2025 1234 123`
security: - bearerAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChargeRequest" responses: "200": description: Successful charge content: application/json: schema: $ref: "#/components/schemas/ChargeResponse" examples: Successful: value: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: status: "SUCCESS" message: "Transaction Successful" transactionReference: "MNFY|99|20220725110839|000256" paymentReference: "1234567890-abcdef" # Example authorizedAmount: 100 OTP_Required: value: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: status: "OTP_AUTHORIZATION_REQUIRED" message: "OTP Authorization required" otpData: id: "100.00-b66bef0aa8e660863c4e1177a08fefba" message: "Please enter OTP. Use 123456 as token" authData: "5060995994247093" transactionReference: "MNFY|67|20220725114150|000284" paymentReference: "12-3---031kls0a--dkad" authorizedAmount: 100 _3DS_Required: value: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: status: "BANK_AUTHORIZATION_REQUIRED" message: "3D Secure Authorization required" secure3dData: id: "100.00-59077a3e5157fae7ca9dd260d911ccbb" redirectUrl: "http://localhost:10001" transactionReference: "MNFY|65|20220725114351|000289" paymentReference: "12-3-031kls0a--dkad" authorizedAmount: 100 "400": description: Bad Request (e.g., invalid card number) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/merchant/cards/otp/authorize: post: tags: - Transactions summary: Authorize OTP description: >- The endpoint authorizes an OTP to complete a charge on a card. security: - bearerAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: content: application/json: schema: $ref: "#/components/schemas/AuthorizeOTPRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/AuthorizeOTPSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/sdk/cards/secure-3d/authorize: post: tags: - Transactions summary: Authorize 3DS Card description: >- This endpoint authorizes charge on a card that uses 3DS Secure Authentication. security: - bearerAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: content: application/json: schema: $ref: "#/components/schemas/Authorize3DSCardRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/Authorize3DSCardSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Unprocessable Entity. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/transactions/search: get: tags: - Transactions summary: Get All Transactions description: >- This endpoint returns a list of transactions carried out on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: page in: query schema: type: string description: The number of page of to be retrieved. It starts from 0. example: Integer - name: size in: query schema: type: string description: The Size of transactions to be returned per page. example: Integer - name: paymentReference in: query schema: type: string description: Unique reference generated by merchant for each transaction. example: String - name: transactionReference in: query schema: type: string description: >- Unique transaction reference generated by Monnify for each transaction example: String - name: fromAmount in: query schema: type: string description: >- A number indicating minimum amount for the transactions to be returned example: Float - name: toAmount in: query schema: type: string description: >- A number indicating maximum amount for the transactions to be returned example: Float - name: amount in: query schema: type: string description: A number indicating exact amount for the transactions to be returned example: Float - name: customerName in: query schema: type: string description: Name of customer for the transactions to be returned example: String - name: customerEmail in: query schema: type: string description: Email of customer for the transactions be returned. example: String - name: paymentStatus in: query schema: type: string description: Transaction status for transactions to be returned example: String - name: from in: query schema: type: integer format: int64 description: Start time for transactions to be retrieved, as a Unix timestamp in milliseconds. example: 1717200000000 - name: to in: query schema: type: integer format: int64 description: End time for transactions to be retrieved, as a Unix timestamp in milliseconds. example: 1719791999000 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/TransactionSearchResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/transactions/{transactionReference}: get: tags: - Transactions summary: Get Transaction Status description: |- This endpoint returns the status of a transaction parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: transactionReference in: path required: true schema: type: string description: URL encoding of the transaction reference. example: "MNFY%7C67%7C20220725111957%7C000283" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/TransactionStatusResponse" "404": description: Transaction not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/merchant/transactions/query: get: tags: - Transactions summary: Get Transaction Status By Reference description: | This endpoint returns the status of a transaction using either the Monnify transaction reference or the merchant's payment reference as query parameters. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: transactionReference in: query schema: type: string description: The Monnify generated reference URL encoded. example: "MNFY%7C67%7C20220725111957%7C000283" - name: paymentReference in: query schema: type: string description: The merchant generated reference URL encoded. example: "12-3---03--1kls0a--dkad" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/TransactionStatusResponse" "404": description: Transaction not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/single: post: tags: - Transfers (Disbursement) summary: Initiate Transfer (Single) description: >- This endpoint initiats a transfer to specified bank account. > [!IMPORTANT] Please note that the usage of the Transfer feature is only available for merchants who meet the regulatory requirements for it. Kindly contact sales@monnify.com to get access to this feature. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InitiateTransferRequest" responses: "200 (With OTP)": description: Successful response for merchants with OTP requirement (default) content: application/json: schema: $ref: "#/components/schemas/InitiateTransferOTPResponse" "200 (Without OTP)": description: Successful response for merchants who have disabled their OTP. content: application/json: schema: $ref: "#/components/schemas/InitiateTransferSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/batch: post: tags: - Transfers (Disbursement) summary: Initiate Transfer (Bulk) description: >- This endpoint allows merchant to initiate Bulk Transfer transactions. > [!IMPORTANT] Please note that the usage of the Transfer feature is only available for merchants who meet the regulatory requirements for it. Kindly contact sales@monnify.com to get access to this feature. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InitiateBulkTransferRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InitiateBulkTransferSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/single/validate-otp: post: tags: - Transfers (Disbursement) summary: Authorize Single Transfers description: >- This endpoint authorizes single transfers on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AuthorizeTransferRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InitiateTransferSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/batch/validate-otp: post: tags: - Transfers (Disbursement) summary: Authorize Bulk Transfers description: >- This endpoint authorizes bulk transfers on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AuthorizeTransferRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InitiateBulkTransferSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/single/resend-otp: post: tags: - Transfers (Disbursement) summary: Resend OTP (Single) description: >- This endpoint generates a new OTP in the event that there were challenges with the former OTP sent. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ResendOTPRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ResendOTPSuccessResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/batch/resend-otp: post: tags: - Transfers (Disbursement) summary: Resend OTP (Bulk) description: >- This endpoint generates a new OTP in the event that there were challenges with the former OTP sent. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ResendOTPRequestBulk" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ResendOTPSuccessResponseBulk" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/single/summary: get: tags: - Transfers (Disbursement) summary: Single Transfer Status description: >- This endpoint verifies the status of a single transfer on your integration.
**Transaction States:** - PENDING - SUCCESS - FAILED - REVERSED - PENDING_AUTHORIZATION - OTP_EMAIL_DISPATCH_FAILED parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: reference in: query schema: type: string description: The reference used for the transfer example: String required: true responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/SingleTransferStatusResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Transfer not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/single/transactions: get: tags: - Transfers (Disbursement) summary: List All Single Transfers description: >- This endpoint returns the list of all single transfers made on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: pageSize in: query schema: type: integer description: The number of transfer records to return example: Integer - name: pageNo in: query schema: type: integer description: A number specifying what page of transfers to be retrieved example: 3 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListSingleTransfersResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/bulk/transactions: get: tags: - Transfers (Disbursement) summary: List All Bulk Transfers description: >- This endpoint returns the list of all bulk transfers made on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: pageSize in: query schema: type: integer description: The number of transfer records to return example: Integer - name: pageNo in: query schema: type: integer description: A number specifying what page of transfers to be retrieved example: Integer responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ListBulkTransfersResponse" /api/v2/disbursements/bulk/batchreference--12934/transactions: get: tags: - Transfers (Disbursement) summary: Bulk Transfer Status description: >- This endpoint verifies the status of a bulk transfer on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: batchReference in: path schema: type: string required: true description: A unique reference identifying the batch disbursement. example: "batchreference--12934" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BulkTransferTransactionsResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Batch not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/batch/summary: get: tags: - Transfers (Disbursement) summary: Bulk Batch Summary description: >- This endpoint provides the summary of a completed batch transaction. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: reference in: query schema: type: string required: true description: A unique reference identifying the batch disbursement. example: "batchreference--12934" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BulkBatchSummaryResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "404": description: Batch not found. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/search-transactions: get: tags: - Transfers (Disbursement) summary: Search Disbursement Transactions description: >- This endpoint returns the list of all disbursement transactions. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: sourceAccountNumber in: query schema: type: string required: true description: The merchant's WALLET ACCOUNT NUMBER, this parameter is mandatory. example: "3934178936" - name: pageSize in: query schema: type: integer description: The number of records to return. example: 10 - name: pageNo in: query schema: type: integer description: The current page from the total. example: 0 - name: startDate in: query schema: type: string format: unix-timestamp description: A timestamp value specifying the date to start filtering disbursement transactions by the createdAt field. example: "1756767600000" - name: endDate in: query schema: type: string format: unix-timestamp description: A timestamp value specifying the date to stop filtering disbursement transactions by the createdAt field. example: "1756767600000" - name: amountFrom in: query schema: type: string description: A number specifying the lower bound for filtering the transactions by the amount field. example: "200" - name: amountTo in: query schema: type: string description: A number specifying the upper bound for filtering the transactions by the amount field. example: "1300" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/SearchDisbursementTransactionsResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/wallet-balance: get: tags: - Transfers (Disbursement) summary: Get Wallet Balance description: >- This endpoint returns the available balance in your monnify wallet. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountNumber in: query schema: type: string required: true description: The merchant's WALLET ACCOUNT NUMBER, this parameter is mandatory. example: "3934178936" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetWalletBalanceResponse" "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/bank-transfer/reserved-accounts: post: tags: - Customer Reserved Account summary: Create Reserved Account(General) description: >- This endpoint allows the creation of dedicated virtual accounts for your customers. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateReservedAccountRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/CreateReservedAccountResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Unprocessable Entity content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts: post: tags: - Customer Reserved Account summary: Create Reserved Account(Invoice) description: >- This endpoint allows the creation of an invoiced reserved account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateInvoiceReservedAccountRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/CreateInvoiceReservedAccountSuccessResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Unprocessable Entity content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/bank-transfer/reserved-accounts/{accountReference}: get: tags: - Customer Reserved Account summary: Get Reserved Account Details description: >- This endpoint returns details of an account reserved for a customer parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference description: The unique reference used in creating the reserved account. in: path schema: type: string required: true responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetReservedAccountDetailsSuccessResponse" "404": description: Reserved account not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/add-linked-accounts/{accountReference}: put: tags: - Customer Reserved Account summary: Add Linked Accounts description: >- This endpoint links accounts with another partner bank to an existing customer. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference description: The unique reference used in creating the reserved account. in: path schema: type: string required: true requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddLinkedAccountsRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/AddLinkedAccountsSuccessResponse" "404": description: Reserved account not found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/update-customer-bvn/{reservedAccountReference}: put: tags: - Customer Reserved Account summary: Update BVN for a Reserve Account description: >- This endpoint updates BVN of customers reserved account parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: reservedAccountReference in: path description: The unique reference used in creating the reserved account. schema: type: string required: true requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateBvnRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/UpdateBvnSuccessResponse" "400": description: Invalid BVN provided content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/update-payment-source-filter/{accountReference}: put: tags: - Customer Reserved Account summary: Allowed Payment Source(s) description: >- This endpoint manages accounts that can fund a reserved account using either BVNs, Account Name or Account Number. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference in: path description: The unique reference used in creating the reserved account. schema: type: string required: true security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AllowedPaymentSourcesRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/AllowedPaymentSourcesSuccessResponse" "400": description: Invalid request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/update-income-split-config/{accountReference}: put: tags: - Customer Reserved Account summary: Updating Split Config for Reserved Account description: >- This endpoint updates the split config of a customer reserved account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference in: path schema: type: string required: true requestBody: required: true content: application/json: schema: type: array items: $ref: "#/components/schemas/UpdateSplitConfigRequestItem" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/UpdateSplitConfigSuccessResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/reference/{accountReference}: delete: tags: - Customer Reserved Account summary: Deallocating a reserved account description: >- This endpoint allows you to deallocate/delete already created a reserved account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference in: path schema: type: string required: true responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/DeallocateAccountSuccessResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/transactions: get: tags: - Customer Reserved Account summary: Get Reserved Account Transactions description: >- This endpoint returns the list of all transactions done on a reserved account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference in: query required: true schema: type: string description: The unique reference used in creating the reserved account. - name: page in: query required: false schema: type: integer description: The page of data you want returned by Monnify (Starts from 0). default: 0 - name: size in: query required: false schema: type: integer description: The number of records you want returned in a page. default: 10 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetTransactionsSuccessResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/{accountReference}/kyc-info: put: tags: - Customer Reserved Account summary: Update KYC Info description: | This endpoint links customers' BVN/NIN to their respective reserved accounts. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountReference in: path required: true schema: type: string description: The account reference linked to the reserved account being updated. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateKycInfoRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/UpdateKycInfoSuccessResponse" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/invoice/create: post: tags: - Invoice summary: Create an Invoice description: >- This endpoint enables merchant to create an invoice. > [!IMPORTANT] **NOTE**: When creating a Static Invoice, the `accountReference` key is compulsory. Excluding it would create a Dynamic Invoice. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateInvoiceRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/CreateInvoiceSuccessResponse" "422": description: Unprocessable Entity content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/invoice/{invoiceReference}/details: get: tags: - Invoice summary: View Invoice Details description: >- This endpoint returns details of an invoice on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: invoiceReference in: path required: true schema: type: string description: The unique reference used in creating the invoice. responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ViewInvoiceDetailsSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/invoice/all: get: tags: - Invoice summary: Get All Invoices description: >- This endpoint returns the list of all the invoice available on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetAllInvoicesSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/invoice/{invoiceReference}/cancel: delete: tags: - Invoice summary: Cancel an Invoice description: This endpoint cancels an Invoice on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: invoiceReference in: path schema: type: string required: true responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/CancelInvoiceSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/merchant/cards/charge-card-token: post: tags: - Recurring Payment summary: Charge Card Token description: >- This endpoint allows you to charge an already tokenized card with it’s card token. > [!IMPORTANT] **NOTE**: The customer email address used in the first successful charge should be stored along with the card token. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ChargeCardTokenRequest" responses: "200": description: Successful card charge content: application/json: schema: $ref: "#/components/schemas/ChargeCardTokenSuccessResponse" "404": description: Not Found (e.g., Invalid card token) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/direct-debit/mandate/create: post: tags: - Direct Debit summary: Create Mandate description: This endpoint initiates the creation of a mandate. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateMandateRequest" responses: "200": description: Successful mandate creation content: application/json: schema: $ref: "#/components/schemas/CreateMandateSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/direct-debit/mandate/: get: tags: - Direct Debit summary: Get Mandate Status description: This endpoint retrieves the details of a created mandate. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: mandateReferences in: query required: true schema: type: string description: Merchants generated reference to identify a mandate. responses: "200": description: Successful mandate retrieval content: application/json: schema: $ref: "#/components/schemas/GetMandateStatusSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/direct-debit/mandate/debit: post: tags: - Direct Debit summary: Debit Mandate description: This endpoint debits an active mandate. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DebitMandateRequest" responses: "200": description: Successful mandate debit content: application/json: schema: $ref: "#/components/schemas/DebitMandateSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/direct-debit/mandate/debit-status: get: tags: - Direct Debit summary: Get Debit Status description: This endpoint gets the status of a debited mandate. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: paymentReference in: query required: true schema: type: string description: The payment reference used in debiting a mandate. responses: "200": description: Successful debit status retrieval content: application/json: schema: $ref: "#/components/schemas/GetDebitStatusSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/direct-debit/mandate/cancel-mandate/{mandateCode}: patch: tags: - Direct Debit summary: Update Mandate (Cancel Mandate) description: This endpoint cancels/deactivates a mandate. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: mandateCode in: path required: true schema: type: string description: Monnify generated mandate identifier. responses: "200": description: Successful mandate cancellation content: application/json: schema: $ref: "#/components/schemas/UpdateMandateSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/direct-debit/mandates: get: tags: - Direct Debit summary: Get Mandates description: >- This endpoint retrieves a paginated list of mandates created or initiated by the merchant. `startDate` and `endDate` are required and the date range must not exceed 90 days. Use the optional filters to narrow results by customer email, scheme code, or mandate status. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: startDate in: query required: true schema: type: string format: date-time description: >- Start of the date range (inclusive). Format: `YYYY-MM-DDTHH:MM:SS`. The range between `startDate` and `endDate` must not exceed 90 days. example: "2026-01-01T00:00:00" - name: endDate in: query required: true schema: type: string format: date-time description: >- End of the date range (inclusive). Format: `YYYY-MM-DDTHH:MM:SS`. The range between `startDate` and `endDate` must not exceed 90 days. example: "2026-03-31T23:59:59" - name: customerEmail in: query required: false schema: type: string format: email description: Filter results to mandates belonging to this customer email. example: "customer@example.com" - name: schemeCode in: query required: false schema: type: string description: Filter results by direct debit scheme code (e.g. `ADD`). example: "ADD" - name: mandateStatus in: query required: false schema: type: string enum: - PENDING - ACTIVE - FAILED - CANCELLED - EXPIRED description: Filter results by the current status of the mandate. example: "FAILED" - name: page in: query required: false schema: type: integer default: 0 description: Zero-based page number. example: 0 - name: limit in: query required: false schema: type: integer default: 20 description: Number of records to return per page. example: 20 responses: "200": description: Successful mandate list retrieval content: application/json: schema: $ref: "#/components/schemas/GetMandatesListSuccessResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/sub-accounts: post: tags: - Sub Accounts summary: Create Sub Account(s) description: >- This endpoint allows you to create a sub account to enable the spliting of payments between different accounts. > [!IMPORTANT] Please note that usage of this API in live environment requires approval from your relationship manager, kindly reach out to them or contact sales@monnify.com to get approval for this feature. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: type: array items: $ref: "#/components/schemas/CreateSubAccountRequest" responses: "200": description: Successful sub account creation content: application/json: schema: $ref: "#/components/schemas/CreateSubAccountSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" get: tags: - Sub Accounts summary: Get Sub Accounts description: >- This endpoint returns the list of sub accounts that have been created on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetSubAccountsSuccessResponse" put: tags: - Sub Accounts summary: Update Sub Account description: >- This endpoint updates the details of an existing sub account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateSubAccountRequest" responses: "200": description: Successful sub account update content: application/json: schema: $ref: "#/components/schemas/UpdateSubAccountSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/sub-accounts/{subAccountCode}: delete: tags: - Sub Accounts summary: Delete Sub Account description: >- This endpoint deletes a sub account on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: subAccountCode in: query schema: type: string description: The subAccountCode of the sub account you want to delete. example: String - name: subAccountCode in: path schema: type: string required: true responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/DeleteSubAccountSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/limit-profile/: post: tags: - Limit Profile summary: Create Limit Profile(s) description: >- This endpoint creates limit profiles on a customer's account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateLimitProfileRequest" responses: "200": description: Successful limit profile creation content: application/json: schema: $ref: "#/components/schemas/CreateLimitProfileSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" get: tags: - Limit Profile summary: Get Limit Profiles description: >- This endpoint returns the list of all Limit Profiles that have been created for your customers. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer responses: "200": description: Successful limit profiles retrieval content: application/json: schema: $ref: "#/components/schemas/GetLimitProfilesSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/limit-profile/FSYVVWU8UPBD: put: tags: - Limit Profile summary: Update Limit Profile description: >- This endpoint updates the information on an existing Limit Profile. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: limitProfileCode in: path required: true schema: type: string description: The generated limit profile code. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateLimitProfileRequest" responses: "200": description: Successful limit profile update content: application/json: schema: $ref: "#/components/schemas/UpdateLimitProfileSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/bank-transfer/reserved-accounts/limit: post: tags: - Limit Profile summary: Reserve Account with Limit description: >- This endpoint reserves an account for your customers with a transaction limit profile on it. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReserveAccountWithLimitRequest" responses: "200": description: Successful reserved account creation with limit content: application/json: schema: $ref: "#/components/schemas/ReserveAccountWithLimitSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" put: tags: - Limit Profile summary: Update Reserve Account Limit description: >- This endpoint updates the information on an existing Limit Profile for a Reserved Account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateReserveAccountLimitRequest" responses: "200": description: Successful reserved account limit update content: application/json: schema: $ref: "#/components/schemas/UpdateReserveAccountLimitSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/refunds/initiate-refund: post: tags: - Refund summary: Initiate Refund description: >- This endpoint allows you to Initiate a refund. > [!IMPORTANT] Please note that usage of this API in live environment requires approval from your relationship manager, kindly reach out to them or contact sales@monnify.com to get approval for this feature. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InitiateRefundRequest" responses: "200": description: Successful refund initiation content: application/json: schema: $ref: "#/components/schemas/InitiateRefundSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/refunds/202100op3456: get: tags: - Refund summary: Get Refund Status description: >- This endpoint returns the status of an initiated refund. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: refundReference in: path required: true schema: type: string description: The refund reference used for the refund. responses: "200": description: Successful refund status retrieval content: application/json: schema: $ref: "#/components/schemas/GetRefundStatusSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/refunds: get: tags: - Refund summary: Get All Refunds description: >- This endpoint returns the list of all refunds available on your integration. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: page in: query schema: type: string description: >- An integer specifying the page of transactions to be retrieved. Page number starts from 0. example: Integer - name: size in: query schema: type: string description: >- An integer specifying the size of transactions to be returned per page. example: Integer responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetAllRefundsSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/transactions/find-by-settlement-reference: get: tags: - Settlements summary: Get Transactions By Settlement Reference description: |- This endpoint returns all transactions that made up a settlement. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: reference in: query schema: type: string description: The settlement reference example: XUY3FHWRJP3CEM4N17BA required: true - name: page in: query schema: type: string description: The current page of the record example: Integer - name: size in: query schema: type: string description: The number of transactions per page example: Integer responses: "200": description: Successful transaction retrieval by settlement reference content: application/json: schema: $ref: "#/components/schemas/GetTransactionsBySettlementReferenceSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/settlement-detail: get: tags: - Settlements summary: Get Settlement Information for Transaction description: >- This endpoint returns settlement information on transactions made to your settlement account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: transactionReference in: query schema: type: string required: true description: The Monnify transaction reference of the desired transaction example: MNFY%7C28%7C20220718162222%7C066201 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetSettlementInformationForTransactionSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v2/disbursements/account/validate: get: tags: - Verification APIs summary: Validate Bank Account description: >- This endpoint validates a Customer's NUBAN Account. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountNumber in: query required: true schema: type: string description: The account number to be validated. - name: bankCode in: query required: true schema: type: string description: The bank code of the required account number. responses: "200": description: Successful account validation content: application/json: schema: $ref: "#/components/schemas/ValidateBankAccountSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/vas/bvn-details-match: post: tags: - Verification APIs summary: BVN Information Verification description: >- This endpoint verifies the BVN information of your customers. > [!IMPORTANT] Please note that the this API is only available on **LIVE MODE** at the moment. The sample responses here mirrors the expected response from the API and can be used to setup workflows in your application. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BVNVerificationRequest" responses: "200": description: Successful BVN verification content: application/json: schema: $ref: "#/components/schemas/BVNVerificationSuccessResponse" "99": description: Invalid BVN provided content: application/json: schema: $ref: "#/components/schemas/BVNVerificationFailureResponse" /api/v1/vas/bvn-account-match: post: tags: - Verification APIs summary: BVN and Account Name Match description: >- This endpoint verifies that the Bank verification number and the account number supplied by a user match the BVN and account number linked to that account. > [!IMPORTANT] Please note that the this API is only available on **LIVE MODE** at the moment. The sample responses here mirrors the expected response from the API and can be used to setup workflows in your application. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BVNAccountMatchRequest" responses: "200": description: Successful BVN and account match content: application/json: schema: $ref: "#/components/schemas/BVNAccountMatchSuccessResponse" "99": description: Invalid BVN or account provided content: application/json: schema: $ref: "#/components/schemas/BVNAccountMatchFailureResponse" /api/v1/vas/nin-details: post: tags: - Verification APIs summary: NIN Verification description: >- This endpoint verifies the supplied NIN of the customer. > [!IMPORTANT] Please note that the this API is only available on **LIVE MODE** at the moment. The sample responses here mirrors the expected response from the API and can be used to setup workflows in your application. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/NINVerificationRequest" responses: "200": description: Successful NIN verification content: application/json: schema: $ref: "#/components/schemas/NINVerificationSuccessResponse" "400": description: NIN not found content: application/json: schema: $ref: "#/components/schemas/NINVerificationFailureResponse" /api/v1/vas/bills-payment/biller-categories: get: summary: Get Biller Categories description: Retrieves a paginated list of all available biller categories, such as transportation, cable TV, and data services. tags: - Bills Payment APIs security: - bearerAuth: [] parameters: - in: query name: size schema: type: integer default: 10 description: The number of categories to return per page. - in: query name: page schema: type: integer default: 1 description: The page number to retrieve. responses: "200": description: A list of biller categories. content: application/json: schema: $ref: "#/components/schemas/CategoryResponse" example: requestSuccessful: true responseMessage: success responseCode: "0" responseBody: content: - code: TRANSPORTATION name: TRANSPORTATION - code: CABLE_TV name: CABLE_TV - code: DATA name: DATA totalElements: 8 size: 3 number: 1 empty: false nextPage: 2 /api/v1/vas/bills-payment/billers: get: summary: List Billers description: Retrieves a paginated list of all billers. You can optionally filter the list by a specific category code. tags: - Bills Payment APIs security: - bearerAuth: [] parameters: - in: query name: size schema: type: integer default: 20 description: The number of billers to return per page. - in: query name: page schema: type: integer default: 1 description: The page number to retrieve. - in: query name: category_code schema: type: string description: The category code to filter billers by (e.g., 'CABLE_TV'). responses: "200": description: A list of billers. content: application/json: schema: $ref: "#/components/schemas/BillerResponse" example: requestSuccessful: true responseMessage: success responseCode: "0" responseBody: content: - code: "biller-dstv" name: "DSTV" categories: - code: "CABLE_TV" name: "CABLE_TV" - code: "biller-spectranet" name: "Spectranet" categories: - code: "DATA" name: "DATA" totalElements: 66 size: 20 number: 1 empty: false nextPage: null /api/v1/vas/bills-payment/biller-products: get: summary: Get Biller Products description: Retrieves a paginated list of products available for a specific biller by passing their biller code. tags: - Bills Payment APIs security: - bearerAuth: [] parameters: - in: query name: page schema: type: integer default: 1 description: The page number to retrieve. - in: query name: size schema: type: integer default: 20 description: The number of products to return per page. - in: query name: biller_code schema: type: string description: The code of the biller to retrieve products for. responses: "200": description: A list of biller products. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: content: - code: "11" name: "Airtel Mobile Top up" categories: - code: "AIRTIME" name: "AIRTIME" biller: - code: "AIRTEL" name: "AIRTEL" minAmount: null maxAmount: null price: null priceType: "OPEN" metadata: volume: 0 duration: 1 productType: code: "6" name: "Airtime" durationUnit: null productCategory: null - code: "19523" name: "DataPlan 750MB" categories: - code: "DATA_BUNDLE" name: "DATA_BUNDLE" biller: - code: "MTN" name: "MTN" minAmount: null maxAmount: null price: 500.0000 priceType: "FIXED" metadata: volume: 750 duration: 1 productType: code: "9" name: "Data" durationUnit: WEEKLY productCategory: DAILY totalElements: 14 size: 5 number: 0 empty: false nextPage: 1 /api/v1/vas/bills-payment/vend: post: summary: Process Bill Payment description: Initiates a payment or vending transaction for a specific product, such as airtime top-up or a utility bill payment. tags: - Bills Payment APIs security: - bearerAuth: [] requestBody: description: Details of the transaction to be initiated. required: true content: application/json: schema: $ref: "#/components/schemas/VendRequest" example: productCode: "11" customerId: "080123456789" amount: 300 validationReference: "REF-MH0H27YL-966MVT" emailAddress: "customer@example.com" responses: "200": description: Successful vending transaction. content: application/json: schema: $ref: "#/components/schemas/VendResponse" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: vendReference: "REF-MH0H27YL-966MVT" transactionReference: "MFBP251021121937dbf0" vendStatus: "SUCCESS" description: "Okay, purchase was successfully created." vendAmount: 300 payableAmount: 310.00 commission: 10.00 customerId: "080123456789" productCode: "11" productName: "Airtel Mobile Top up" billerCode: "AIRTEL" billerName: "AIRTEL" "400": description: Bad Request, e.g., a required field like 'productCode' is missing. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: requestSuccessful: false responseMessage: "ProductCode is required" responseCode: "99" /api/v1/vas/bills-payment/requery: get: summary: Check Bill Payment Status description: Checks and retrieves the final status of a previously initiated transaction using its unique reference. tags: - Bills Payment APIs security: - bearerAuth: [] parameters: - in: query name: reference required: true schema: type: string description: The unique reference of the transaction to requery. responses: "200": description: Successful requery with transaction details. content: application/json: schema: $ref: "#/components/schemas/RequeryResponse" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: vendReference: "REF-MH0H27YL-966MVT" transactionReference: "MFBP251021121937dbf0" vendStatus: "SUCCESS" description: "Okay, purchase was successfully created." vendAmount: 300 payableAmount: 310.00 commission: 10.00 customerId: "080123456789" productCode: "11" productName: "Airtel Mobile Top up" billerCode: "AIRTEL" billerName: "AIRTEL" "400": description: Bad Request, the provided reference is invalid or poorly formatted. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: requestSuccessful: false responseMessage: "Please ensure that the details supplied in your request are appropriate." responseCode: "99" "404": description: Transaction not found for the given reference. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: requestSuccessful: false responseMessage: "Transaction not found for reference: QA-MGB159DY-5Z2FJ9" responseCode: "99" /api/v1/vas/bills-payment/validate-customer: post: summary: Validate Customer description: >- Validates a customer's details (like a meter number or phone number) for a specific product before initiating a transaction. > [!IMPORTANT] **NOTE**: Some biller products require a validationReference during the Vend request, while others do not. After performing Customer Validation, check the vendInstruction field in the response. If requireValidationRef is true, you must include the provided validationReference when sending the Vend request. If requireValidationRef is false, omit validationReference from the Vend request. This ensures the correct handling of products that require additional verification (e.g., electricity meter validation) versus products that do not (e.g., airtime or open-price utilities). tags: - Bills Payment APIs security: - bearerAuth: [] requestBody: description: The product and customer identifiers to validate. required: true content: application/json: schema: $ref: "#/components/schemas/ValidateCustomerRequest" example: productCode: "11" customerId: "080123456789" responses: "200": description: Successful customer validation. content: application/json: schema: $ref: "#/components/schemas/ValidateCustomerResponse" examples: ValidationNotRequired: summary: Validation without a required reference value: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: priceType: "OPEN" customerName: "+2349135914842" vendInstruction: requireValidationRef: false ValidationRequired: summary: Validation that returns a required reference value: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: customerName: "Mr. John Doe" priceType: "FIXED" price: 44600 vendInstruction: requireValidationRef: true validationReference: "724707993771" "400": description: Bad Request, e.g., invalid customer ID or missing parameters. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" example: requestSuccessful: false responseMessage: "Invalid MSISDN Provided" responseCode: "99" /api/v1/banks: get: tags: - Others summary: Get Banks description: >- This endpoint returns a list of all banks supported by Monnify for collections and disbursements. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [Authentication*](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer 7 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BankListSuccessResponse" "401": description: Failed Response content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/sdk/transactions/banks: get: tags: - Others summary: Get Banks With USSD Short Code description: >- This endpoint returns the list of all supported banks with their valid USSD short code. security: - bearerAuth: [] # Define the security scheme directly here parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the **[Authentication](#tag/authentication/POST/api/v1/auth/login)** endpoint to generate one. example: Bearer 7 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/BankListSuccessResponse" "401": description: Failed Response content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/disbursements/wallet: post: tags: - Wallet summary: Create Wallet description: | This endpoint enables a merchant to creates wallets for their customers > [!IMPORTANT] > Please note that the wallet creation is only available for merchants who have been granted access to the wallet feature. Kindly contact sales@monnify.com to get access to this feature. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer 7 requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateWalletRequest" responses: "200": description: Wallet created successfully content: application/json: schema: $ref: "#/components/schemas/CreateWalletSuccessResponse" "422": description: Unprocessable Entity (Validation Error) content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" get: tags: - Wallet summary: Get Wallets description: >- This endpoint returns all the wallets created by a merchant security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - in: query name: walletReference schema: type: string description: The unique identifier of the wallet example: "ref16842048425966d" - in: query name: pageSize schema: type: integer description: The number of wallet records to return - in: query name: pageNo schema: type: integer description: A number specifying what page of wallets to be retrieved responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/GetWalletsResponse" "401": description: Unauthorized Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/disbursements/wallet/balance: get: tags: - Wallet summary: Wallet Balance description: |- This endpoint returns the balance associated with a wallet parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountNumber in: query schema: type: string description: The unique identifier of the wallet example: String responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WalletBalanceResponse" "401": description: Unauthorized Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/disbursements/wallet/transactions: get: tags: - Wallet summary: Wallet Transactions description: >- This endpoint returns all the transactions performed by a wallet parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer - name: accountNumber in: query schema: type: string description: The walletAccountNumber minLength: 10 maxLength: 10 example: 1234567890 - name: pageSize in: query schema: type: string description: The number of wallet records to return example: 20 - name: pageNo in: query schema: type: string description: A number specifying what page of wallets to be retrieved example: 3 responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/WalletTransactionsResponse" "401": description: Unauthorized Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/paycode: post: tags: - Paycode API summary: Create Paycode description: The endpoint allows merchant create paycodes via API. parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePaycodeRequest" responses: "200": description: Successful paycode creation content: application/json: schema: $ref: "#/components/schemas/CreatePaycodeSuccessResponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" get: tags: - Paycode API summary: Fetch Paycodes description: This endpoint returns a history of generated Paycodes over a period of time using some search criteria. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer 7 - name: transactionReference in: query schema: type: string description: The Monnify transactionReference. - name: beneficiaryName in: query schema: type: string description: The customer name. - name: transactionStatus in: query schema: type: string description: The status of the paycode. - name: from in: query schema: type: integer description: A unix timestamp for the start date being considered. - name: to in: query schema: type: integer description: A unix timestamp for the end date being considered. responses: "200": description: Successful paycode history retrieval content: application/json: schema: $ref: "#/components/schemas/FetchPaycodesSuccessResponse" /api/v1/paycode/{paycodeReference}: get: tags: - Paycode API summary: Get Paycode description: This endpoint returns paycode information for a given paycode reference. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer 7 - name: paycodeReference in: path required: true schema: type: string description: The unique reference for the paycode. responses: "200": description: Successful paycode retrieval content: application/json: schema: $ref: "#/components/schemas/GetPaycodeSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" delete: tags: - Paycode API summary: Delete Paycode description: This endpoint cancels or invalidates a generated Paycode. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer 7 - name: paycodeReference in: path required: true schema: type: string description: The unique reference for the paycode. responses: "200": description: Successful paycode deletion/cancellation content: application/json: schema: $ref: "#/components/schemas/CreatePaycodeSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" /api/v1/paycode/{paycodeReference}/authorize: get: tags: - Paycode API summary: Get Clear Paycode description: This endpoint is used to get an unmasked paycode information. security: - bearerAuth: [] parameters: - in: header name: Authorization schema: type: string required: true description: >- This endpoint requires a valid JWT authorization token. Use the [**Authentication**](#tag/authentication/POST/api/v1/auth/login) endpoint to generate one. example: Bearer 7 - name: paycodeReference in: path required: true schema: type: string description: The unique reference for the paycode. responses: "200": description: Successful clear paycode retrieval content: application/json: schema: $ref: "#/components/schemas/GetPaycodeSuccessResponse" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" components: securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer bearerFormat: JWT required: true schemas: AuthResponseSuccess: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseCode: type: integer description: A response code. example: "success" responseBody: type: object properties: accessToken: type: string expiresIn: type: integer description: "expiry figure in seconds" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: accessToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTYyNzQwNjYwM30.7 expiresIn: 3600 AuthResponseError: type: object properties: requestSuccessful: type: boolean example: "false" responseCode: type: integer example: 99 responseMessage: type: string example: requestSuccessful: false responseCode: 99 responseMessage: "" AuthResponseNoHeaderError: type: object properties: requestSuccessful: type: boolean example: "false" responseCode: type: integer example: 99 responseMessage: type: string example: "Unauthorized, supply authorization header" example: requestSuccessful: false responseCode: 99 responseMessage: "Unauthorized, supply authorization header" BankListSuccessResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseMessage: type: string description: A message describing the response. example: "success" responseCode: type: string description: The response code. example: "0" responseBody: type: array description: An array of objects with list of banks supported by Monnify. items: $ref: "#/components/schemas/Bank" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: - name: "Rolez Microfinance Bank" code: "50515" ussdTemplate: null baseUssdCode: null transferUssdTemplate: null - name: "Access bank" code: "044" ussdTemplate: "*901*Amount*AccountNumber#" baseUssdCode: "*901#" transferUssdTemplate: "*901*AccountNumber#" - name: "Kuda Microfinance Bank" code: "50211" ussdTemplate: null baseUssdCode: "*5573#" transferUssdTemplate: "*5573*AccountNumber#" CreateWalletRequest: type: object properties: walletReference: type: string description: A unique identifier for the wallet example: "ref1684248425966" walletName: type: string description: The desired wallet name example: "Staging Wallet - ref1684248425966" customerName: type: string description: The customer's name example: "John Doe" customerEmail: type: string description: The customer's email example: "johndoe@example.com" bvnDetails: type: object description: The customer's BVN details properties: bvn: type: integer description: The user's 11 digit bank verification number minLength: 11 maxLength: 11 example: "22222222226" bvnDateOfBirth: type: string format: date description: The user's date of birth associated with the BVN example: "1994-09-07" CreateWalletSuccessResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseMessage: type: string description: A message describing the response. example: "Success" responseCode: type: string description: The response code. example: "0" responseBody: type: object description: The response body containing the wallet details properties: walletName: type: string description: The name of the wallet example: "Staging Wallet - ref1684248425966" walletReference: type: string description: The unique identifier for the wallet example: "ref1684248425966" customerName: type: string description: The customer's name example: "John Doe" customerEmail: type: string description: The customer's email example: "johndoe@example.com" feeBearer: type: string example: "SELF" bvnDetails: type: object description: The customer's BVN details properties: bvn: type: integer description: The user's 11 digit bank verification number minLength: 11 maxLength: 11 example: "22222222226" bvnDateOfBirth: type: string format: date example: "1994-09-07" accountNumber: type: string description: The account number associated with the wallet example: "1234567890" accountName: type: string description: The account name associated with the wallet example: "John Doe" topUpAccountDetails: type: object description: The top-up account details properties: accountNumber: type: string description: The top-up account number example: "1234567890" accountName: type: string description: The top-up account name example: "John Doe" bankCode: type: string description: The top-up bank code example: "50515" bankName: type: string description: The top-up bank name example: "Moniepoint MFB" createdOn: type: string format: date-time description: The date and time when the wallet was created example: "2025-11-12T11:40:25.344+00:00" WalletBalanceResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: availableBalance: type: integer ledgerBalance: type: integer example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: availableBalance: 5000000000 ledgerBalance: 5000000000 GetWalletsResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string example: "success" responseCode: type: string responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/Wallet" pageable: type: object properties: sort: type: object properties: empty: type: boolean sorted: type: boolean unsorted: type: boolean offset: type: integer pageNumber: type: integer pageSize: type: integer paged: type: boolean unpaged: type: boolean last: type: boolean totalElements: type: integer totalPages: type: integer size: type: integer number: type: integer sort: type: object properties: empty: type: boolean sorted: type: boolean unsorted: type: boolean first: type: boolean numberOfElements: type: integer empty: type: boolean WalletTransactionsResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/WalletTransactions" pageable: type: object properties: sort: type: object properties: empty: type: boolean sorted: type: boolean unsorted: type: boolean offset: type: integer pageNumber: type: integer pageSize: type: integer paged: type: boolean unpaged: type: boolean last: type: boolean totalElements: type: integer totalPages: type: integer size: type: integer number: type: integer sort: type: object properties: empty: type: boolean sorted: type: boolean unsorted: type: boolean first: type: boolean numberOfElements: type: integer empty: type: boolean WalletTransactions: type: object properties: walletTransactionReference: type: string example: "MFDS60520251111091433348001YWN0D9_DEBIT_0" monnifyTransactionReference: type: string example: "MFDS60520251111091433348001YWN0D9_DEBIT_0" availableBalanceBefore: type: number format: float example: 5000000000 availableBalanceAfter: type: number format: float example: 4900000000 amount: type: float example: 1000000000 transactionDate: type: date-time example: "2025-11-11T08:14:33.000+00:00" transactionType: type: string example: "DEBIT" message: type: string | null example: null narration: type: string example: "MFDS60520251111091433348001YWN0D9/#/reference---12d9d0034fr/#/911 Transactionn/#/Moniepoint Micr/#/0000001723" status: type: string example: "COMPLETED" InitializeTransactionRequest: type: object properties: amount: type: number format: float description: The amount (in Naira) to be paid. Minimum is N20. example: 100.00 customerName: type: string description: The name of the customer. example: "John Doe" customerEmail: type: string description: The customer email. example: "stephen@ikhane.com" paymentReference: type: string description: A unique string of characters that identifies each transaction. example: "123-03hjsj--1klsa--dkad" paymentDescription: type: string description: A description of the payment. example: "Trial transaction" currencyCode: type: string description: The currency code. Defaults to NGN but USD available for enabled merchant. example: "NGN" contractCode: type: string description: The merchant contract code. example: "5867418298" redirectUrl: type: string description: A URL to redirect to after payment completion. example: "https://my-merchants-page.com/transaction/confirm" paymentMethods: type: array description: The method of payment collection. Defaults to all available methods. items: type: string description: The method of payment collection. Defaults to all available methods. enum: - "CARD" - "ACCOUNT_TRANSFER" - "USSD" - "PHONE_NUMBER" example: - "CARD" - "ACCOUNT_TRANSFER" - "USSD" - "PHONE_NUMBER" incomeSplitConfig: type: array items: type: object properties: subAccountCode: type: string description: The unique reference for the sub account that should receive the split. Required if income split is enabled. example: "MFY_SUB_319452883228" feePercentage: type: number description: The percentage of the fee to be borne by the subAccount. format: float example: 10.5 splitAmount: type: number description: The constant amount to be sent to the subAccount for each transaction. Expected if splitPercentage is not provided format: float example: 20 splitPercentage: type: number description: The percent amount to be splitted into the subAccount for each transaction. Expected if splitAmount is not provided format: float example: 20 feeBearer: type: boolean description: Indicates if the subAccount bears the fee. example: true description: A way to split payments among subAccounts. metadata: type: object properties: name: type: string description: The name of the customer. example: "John Doe" age: type: integer description: The age of the customer. example: 45 description: Extra information from customers. example: name: "John Doe" age: 45 required: - amount - customerEmail - paymentReference - currencyCode - contractCode example: amount: 100.00 customerEmail: "stephen@ikhane.com" paymentReference: "123-03hjsj--1klsa--dkad" paymentDescription: "Trial transaction" currencyCode: "NGN" contractCode: "5867418298" redirectUrl: "https://my-merchants-page.com/transaction/confirm" paymentMethods: - "CARD" - "ACCOUNT_TRANSFER" - "USSD" - "PHONE_NUMBER" metadata: name: "John Doe" age: 45 incomeSplitConfig: - subAccountCode: "MFY_SUB_319452883228" feePercentage: 10.5 splitAmount: 20 feeBearer: true InitializeTransactionSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: transactionReference: type: string example: "MNFY|20190915200044|000090" paymentReference: type: string example: "123-03hjsj--1klsa--dkad" merchantName: type: string example: "Test Limited" merchantLogoUrl: type: string example: "https://www.monnify.com/images/logo.png" apiKey: type: string example: "MK_TEST_VR7J3UAACH" enabledPaymentMethod: type: array items: type: string enum: - "ACCOUNT_TRANSFER" - "CARD" example: - "ACCOUNT_TRANSFER" - "CARD" checkoutUrl: type: string example: "https://sandbox.sdk.monnify.com/checkout/MNFY|20190915200044|000090" incomeSplitConfig: type: array items: type: object properties: subAccountCode: type: string description: The subAccount code available on merchant dashboard. example: "MFY_SUB_319452883968" splitAmount: type: number description: The amount to split to the subAccount. format: float example: 20 feePercentage: type: number description: The percentage of the fee to be borne by the subAccount. format: float example: 10.5 feeBearer: type: boolean description: Indicates if the subAccount bears the fee. example: true splitPercentage: type: integer description: The percentage of the split to be made to the subAccount. example: 0 example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: transactionReference: "MNFY|20190915200044|000090" paymentReference: "123-03hjsj--1klsa--dkad" merchantName: "Test Limited" apiKey: "MK_TEST_VR7J3UAACH" enabledPaymentMethod: - "ACCOUNT_TRANSFER" - "CARD" checkoutUrl: "https://sandbox.sdk.monnify.com/checkout/MNFY|20190915200044|000090" incomeSplitConfig: - subAccountCode: "MFY_SUB_319452883968" splitAmount: 20 feePercentage: 10.5 feeBearer: true splitPercentage: 0 InitBankTransferPaymentRequest: type: object properties: transactionReference: type: string description: A unique Monnify reference from the initialize transaction endpoint. example: "MNFY|20190915200044|000090" bankCode: type: string description: A valid bank code for USSD string generation (optional). example: "50515" required: - transactionReference example: transactionReference: "MNFY|20190915200044|000090" bankCode: "50515" InitBankTransferPaymentSuccessResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseMessage: type: string description: A message describing the response. example: "success" responseCode: type: string description: The response code. example: "0" responseBody: type: object properties: accountNumber: type: string description: The account number to be credited. example: "6795542937" accountName: type: string description: The account name to be credited. example: "John Doe" bankName: type: string description: The bank name to be credited. example: "Moniepoint Microfinance Bank" bankCode: type: string description: The bank code to be credited. example: "50515" accountDurationSeconds: type: integer description: The duration in seconds for which the account number is valid. example: 2400 ussdPayment: type: string description: The USSD code to be dialed to initiate the transfer. example: "*901*100.00*6795542937#" requestTime: type: string format: date-time description: The time the request was made. example: "2026-06-30T09:31:46.814667464" expiresOn: type: string format: date-time description: The time the account number expires. example: "2026-06-30T10:11:46" transactionReference: type: string description: The transaction reference. example: "MNFY|20190915200044|000090" paymentReference: type: string description: The payment reference. example: "9070fdf1-e28f-4836-82e6-c9a5b042e4d1" amount: type: number description: The amount to be paid. example: 100.00 fee: type: number description: The fee charged for the transaction. example: 0.00 totalPayable: type: number description: The total amount payable including fees. example: 100.00 collectionChannel: type: string description: The channel through which payment was collected. example: "API_NOTIFICATION" productInformation: type: object nullable: true description: Additional product information, if any. example: null example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: accountNumber: "6795542937" accountName: "jiggyjiggy-Trial transaction" bankName: "Moniepoint Microfinance Bank" bankCode: "50515" accountDurationSeconds: 2400 ussdPayment: "*901*100.00*6795542937#" requestTime: "2026-06-30T09:31:46.814667464" expiresOn: "2026-06-30T10:11:46" transactionReference: "MNFY|20190915200044|000090" paymentReference: "9070fdf1-e28f-4836-82e6-c9a5b042e4d1" amount: 100.00 fee: 0.00 totalPayable: 100.00 collectionChannel: "API_NOTIFICATION" productInformation: null ChargeRequest: type: object required: - transactionReference - card - deviceInformation properties: transactionReference: type: string description: The transaction reference. example: "MNFY|99|20220725125351|000271" collectionChannel: type: string description: The collection channel (optional, defaults to API_NOTIFICATION). example: "API_NOTIFICATION" card: $ref: "#/components/schemas/CardInfo" deviceInformation: $ref: "#/components/schemas/DeviceInformation" CardInfo: type: object required: - number - expiryMonth - expiryYear - pin - cvv properties: number: type: string description: The card number. example: "4111111111111111" expiryMonth: type: string description: The card expiry month. example: "12" expiryYear: type: string description: The card expiry year. example: "2025" pin: type: string description: The card PIN. example: "1234" cvv: type: string description: The card CVV. example: "123" DeviceInformation: type: object properties: httpBrowserLanguage: type: string description: The browser language. example: "en-US" httpBrowserJavaEnabled: type: boolean description: Indicates if Java is enabled in the browser. example: false httpBrowserJavaScriptEnabled: type: boolean description: Indicates if JavaScript is enabled in the browser. example: true httpBrowserColorDepth: type: integer description: The browser color depth. example: 24 httpBrowserScreenHeight: type: integer description: The browser screen height. example: 1203 httpBrowserScreenWidth: type: integer description: The browser screen width. example: 2138 httpBrowserTimeDifference: type: string description: The browser time difference. example: "" userAgentBrowserValue: type: string description: The browser's user agent example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" required: - httpBrowserLanguage - httpBrowserJavaEnabled - httpBrowserJavaScriptEnabled - httpBrowserColorDepth - httpBrowserScreenHeight - httpBrowserScreenWidth - httpBrowserTimeDifference - userAgentBrowserValue ChargeResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseMessage: type: string description: A message describing the response. example: "success" responseCode: type: string description: The response code. example: "0" responseBody: type: object description: The response body containing the payment details. properties: status: type: string description: The payment status. example: "SUCCESS" message: type: string description: A message describing the payment status. example: "Transaction Successful" transactionReference: type: string description: The transaction reference. example: "MNFY|99|20220725125351|000271" paymentReference: type: string description: The payment reference. example: "12-3---03--1klsa--dkad" authorizedAmount: type: integer description: The authorized amount. example: 2000 otpData: # Optional, for OTP flow type: object description: For cards with OTP requirements properties: id: type: string description: The OTP ID. example: "100.00-b66bef0aa8e660863c4e1177a08fefba" message: type: string description: The OTP message. example: "Enter OTP sent to your device. Use 123456" authData: type: string description: The auth data. example: "5060995994247093" secure3dData: # Optional, for 3DS flow type: object description: For cards with 3DS requirements properties: id: type: string description: The 3DS ID. example: "100.00-59077a3e5157fae7ca9dd260d911ccbb" redirectUrl: type: string description: The 3DS redirect URL. example: localhost:3000 AuthorizeOTPRequest: type: object properties: transactionReference: type: string description: The transaction reference from the initialize transaction endpoint. example: "MNFY|67|20220725114827|000285" collectionChannel: type: string description: The channel of collection (defaults to "API_NOTIFICATION"). example: "API_NOTIFICATION" tokenId: type: string description: The token ID from the charge card endpoint response. example: "100.00-b66bef0aa8e660863c4e1177a08fefba" token: type: string description: The OTP sent to the user's device. example: "123456" required: - transactionReference - tokenId - token example: transactionReference: "MNFY|67|20220725114827|000285" collectionChannel: "API_NOTIFICATION" tokenId: "100.00-b66bef0aa8e660863c4e1177a08fefba" token: "123456" AuthorizeOTPSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: paymentStatus: type: string example: "SUCCESSFUL" paymentDescription: type: string example: "Payment Successful" transactionReference: type: string example: "MNFY|67|20220725114827|000285" paymentReference: type: string example: "1568577644707" amountPaid: type: number format: float example: 100.00 currencyPaid: type: string example: "NGN" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: paymentStatus: "SUCCESSFUL" paymentDescription: "Payment Successful" transactionReference: "MNFY|67|20220725114827|000285" paymentReference: "1568577644707" amountPaid: 100.00 currencyPaid: "NGN" Authorize3DSCardRequest: type: object properties: transactionReference: type: string description: The transaction reference. example: "MNFY|99|20220725125351|000271" apiKey: type: string description: The merchant API key. example: "MK_TEST_JRQAZRFD2W" collectionChannel: type: string description: The collection channel. example: "API_NOTIFICATION" card: type: object properties: number: type: integer description: The card number. example: "4000000000000" expiryMonth: type: integer description: The card expiry month. example: 12 expiryYear: type: integer description: The card expiry year. example: 2025 cvv: type: integer description: The card CVV. example: 123 pin: type: integer description: The card pin. example: 1234 required: - transactionReference - apiKey - card Authorize3DSCardSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: paymentStatus: type: string example: "SUCCESSFUL" paymentDescription: type: string example: "Payment Successful" transactionReference: type: string example: "MNFY|99|20220725125351|000271" paymentReference: type: string example: "1568577644707" amountPaid: type: number format: float example: 100.00 currencyPaid: type: string example: "NGN" example: requestSuccessful: true responseMessage: "success" responseCode: "0" responseBody: paymentStatus: "SUCCESSFUL" paymentDescription: "Payment Successful" transactionReference: "MNFY|99|20220725125351|000271" paymentReference: "1568577644707" amountPaid: 100.00 currencyPaid: "NGN" TransactionSearchResponse: type: object properties: content: type: array items: type: object properties: transactionReference: type: string example: "MNFY|123|20231027|000001" paymentReference: type: string example: "merchant-ref-123" amount: type: number format: float example: 50.00 customerName: type: string example: "John Doe" customerEmail: type: string example: "john.doe@example.com" paymentStatus: type: string example: "SUCCESSFUL" transactionDate: type: string format: date-time example: "2023-10-27T10:00:00Z" pageable: type: object properties: sort: type: object properties: empty: type: boolean example: true sorted: type: boolean example: false unsorted: type: boolean example: true offset: type: integer example: 0 pageSize: type: integer example: 10 pageNumber: type: integer example: 0 unpaged: type: boolean example: false paged: type: boolean example: true last: type: boolean example: true totalPages: type: integer example: 1 totalElements: type: integer example: 1 size: type: integer example: 10 number: type: integer example: 0 sort: type: object properties: empty: type: boolean example: true sorted: type: boolean example: false unsorted: type: boolean example: true first: type: boolean example: true numberOfElements: type: integer example: 1 empty: type: boolean example: true example: content: - transactionReference: "MNFY|123|20231027|000001" paymentReference: "merchant-ref-123" amount: 50.00 customerName: "John Doe" customerEmail: "john.doe@example.com" paymentStatus: "SUCCESSFUL" transactionDate: "2023-10-27T10:00:00Z" pageable: sort: empty: true sorted: false unsorted: true offset: 0 pageSize: 10 pageNumber: 0 unpaged: false paged: true last: true totalPages: 1 totalElements: 1 size: 10 number: 0 sort: empty: true sorted: false unsorted: true first: true numberOfElements: 1 empty: true TransactionStatusResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseMessage: type: string description: A message describing the response. example: "success" responseCode: type: string description: The response code. example: "0" responseBody: type: object properties: transactionReference: type: string description: The transaction reference. example: "MNFY|67|20220725111957|000283" paymentReference: type: string description: The payment reference. example: "12-3---03--1kls0a--dkad" amountPaid: type: string description: The amount paid. example: "100.00" totalPayable: type: string description: The total payable amount. example: "100.00" settlementAmount: type: string description: The settlement amount. example: "90.00" paidOn: type: string description: The date and time the payment was made. example: "25/07/2022 11:20:20 AM" paymentStatus: type: string description: The payment status. example: "PAID" paymentDescription: type: string description: A description of the payment. example: "Trial transaction" currency: type: string description: The currency. example: "NGN" paymentMethod: type: string description: The payment method. example: "CARD" product: type: object properties: type: type: string description: The product type. example: "WEB_SDK" reference: type: string description: The product reference. example: "12-3---03--1kls0a--dkad" cardDetails: type: object properties: cardType: type: string description: The card type. example: "Sandbox Card Scheme" last4: type: string description: The last 4 digits of the card number. example: "1111" expMonth: type: string description: The card expiry month. example: "10" expYear: type: string description: The card expiry year. example: "22" bin: type: string description: The card BIN. example: "411111" bankCode: type: "null" description: The bank code. example: null bankName: type: "null" description: The bank name. example: null reusable: type: boolean description: Indicates if the card is reusable. example: false countryCode: type: "null" description: The country code. example: null cardToken: type: "null" description: The card token. example: null supportsTokenization: type: boolean description: Indicates if the card supports tokenization. example: false maskedPan: type: string description: The masked card PAN. example: "411111******1111" accountDetails: type: "null" description: Account details. example: null accountPayments: type: array items: {} description: Account payments. example: [] customer: type: object properties: email: type: string description: The customer email. example: "stephen@ikhane.com" name: type: string description: The customer name. example: "Stephen Ikhane" metaData: type: object description: Metadata. example: {} example: 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: "stephen@ikhane.com" name: "Stephen Ikhane" metaData: {} InitiateTransferRequest: type: object properties: amount: type: number format: float description: Amount to disburse. example: 200 reference: type: string description: The unique reference for the transaction. example: "reference---1290034" narration: type: string description: The Narration for the transactions being processed. example: "911 Transaction" destinationBankCode: type: string description: The destination bank code representing the destination bank. example: "50515" destinationAccountNumber: type: string description: The beneficiary account number. example: "2085886393" destinationAccountName: type: string description: The beneficiary account name. example: "Ciroma Chukwuka Adekunle" currency: type: string description: The currency of the transaction being initialized - "NGN". example: "NGN" sourceAccountNumber: type: string description: Your Wallet Account Number. example: "3934178936" senderInfo: type: object properties: sourceAccountNumber: type: string description: The sender account number. Must be 10 digits for Nigerian accounts example: "3934178936" sourceAccountName: type: string description: The sender account name. This can be changed to any name. Useful when you are sending on behalf of a business. example: "Marvelous Benji" sourceAccountBvn: type: string description: The sender account bvn. Must be valid 11-digit BVN example: "1234567890" senderBankCode: type: string description: The sender bank code. Must be valid Nigerian bank code example: "50515" required: - sourceAccountNumber - sourceAccountName - senderBankCode async: type: boolean description: Indicates if the transfer should be asynchronous. example: false required: - amount - reference - narration - destinationBankCode - destinationAccountNumber - destinationAccountName - currency - sourceAccountNumber optional: - senderInfo - async InitiateTransferSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: amount: type: integer example: 200 reference: type: string example: "referen00ce---1290034" status: type: string example: "SUCCESS" dateCreated: type: string format: date-time example: "2022-07-31T14:31:33.759+0000" totalFee: type: integer example: 35 destinationAccountName: type: string example: "Ciroma Chukwuka Adekunle" destinationBankName: type: string example: "Moniepoint Microfinance bank" destinationAccountNumber: type: string example: "2085886393" destinationBankCode: type: string example: "50515" senderInfo: type: object properties: sourceAccountNumber: type: string example: "3934178936" sourceAccountName: type: string example: "Marvelous Benji" senderBankCode: type: string example: "50515" InitiateTransferOTPResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: amount: type: integer example: 200 reference: type: string example: "refere--n00ce---1290034" status: type: string example: "PENDING_AUTHORIZATION" dateCreated: type: string format: date-time example: "2022-07-31T15:36:16.398+0000" totalFee: type: integer example: 35 destinationAccountName: type: string example: "Ciroma Chukwuka Adekunle" destinationBankName: type: string example: "Moniepoint Microfinance bank" destinationAccountNumber: type: string example: "2085886393" destinationBankCode: type: string example: "50515" InitiateBulkTransferRequest: type: object properties: title: type: string description: The title of the batch disbursement. example: "Game of Batches" batchReference: type: string description: A unique reference identifying the batch disbursement. example: "batchreference--12934" narration: type: string description: A narration for the disbursement. example: "911 Transaction" sourceAccountNumber: type: string description: The merchant WALLET ACCOUNT NUMBER. example: "9624937372" onValidationFailure: type: string enum: - CONTINUE - BREAK description: Decision to be taken if any of the disbursement batches fail. Either BREAK or CONTINUE. example: "CONTINUE" notificationInterval: type: integer description: This determines how often Monnify should notify the merchant of its progress when processing a batch transfer. example: 10 transactionList: type: array items: type: object properties: amount: type: integer description: Amount to disburse. example: 1300 reference: type: string description: The unique reference for the transaction. example: "Final-Refere-nce-1a" narration: type: string description: The Narration for the transactions being processed. example: "911 Transaction" destinationBankCode: type: string description: The 3-5 digit bank code representing the destination bank. example: "50515" destinationAccountNumber: type: string description: The beneficiary account number. example: "0111946768" destinationAccountName: type: string description: The beneficiary account name. example: "Ciroma Chukwuka Adekunle" currency: type: string description: The currency of the transaction being initialized - "NGN". example: "NGN" required: - amount - reference - narration - destinationBankCode - destinationAccountNumber - destinationAccountName - currency description: A list of transactions to be processed. senderInfo: type: object properties: sourceAccountNumber: type: string description: The sender account number. Must be 10 digits for Nigerian accounts example: "3934178936" sourceAccountName: type: string description: The sender account name. This can be changed to any name. Useful when you are sending on behalf of a business. example: "Marvelous Benji" sourceAccountBvn: type: string description: The sender account bvn. Must be valid 11-digit BVN example: "1234567890" senderBankCode: type: string description: The sender bank code. Must be valid Nigerian bank code example: "50515" required: - title - batchReference - narration - sourceAccountNumber - onValidationFailure - notificationInterval - transactionList InitiateBulkTransferSuccessResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: true responseMessage: type: string description: A message describing the response. example: "success" responseCode: type: string description: The response code. example: "0" responseBody: type: object description: The response body containing the batch disbursement details. properties: totalAmount: type: integer description: The total amount disbursed. example: 2100 totalFee: type: integer description: The total fee charged. example: 105 batchReference: type: string description: The batch reference. example: "batchreference--12934" batchStatus: type: string description: The disbursement status of the batch. example: "AWAITING_PROCESSING" totalTransactionsCount: type: integer description: The total number of transactions in the batch. example: 3 dateCreated: type: string description: The date and time the batch was created. format: date-time example: "2022-07-31T14:41:19.588+0000" AuthorizeTransferRequest: type: object properties: reference: type: string description: The unique reference for the transfer. example: "refere--n00ce---1290034" authorizationCode: type: string description: The OTP sent to merchant's email. example: "491763" required: - reference - authorizationCode AuthorizeSingleTransferSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: amount: type: integer example: 200 reference: type: string example: "refere--n00ce---1290034" status: type: string example: "SUCCESS" dateCreated: type: string format: date-time example: "2022-07-31T15:36:16.000+0000" totalFee: type: integer example: 35 destinationAccountName: type: string example: "Marvelous Benji" destinationBankName: type: string example: "Moniepoint Microfinance bank" destinationAccountNumber: type: string example: "2085886393" destinationBankCode: type: string example: "50515" ResendOTPRequest: type: object properties: reference: type: string description: The reference used for the transfer. example: "refere--n00ce---1290--034" required: - reference ResendOTPSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: message: type: string example: "Authorization code will be processed and sent to predefined email addresses(s)" ResendOTPRequestBulk: type: object properties: batchReference: type: string description: The batch reference used for the transfer. example: "batch-refere--n00ce---1290--034" required: - batchReference ResendOTPSuccessResponseBulk: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: message: type: string example: "Authorization code will be processed and sent to predefined email addresses(s)" SingleTransferStatusResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: amount: type: integer example: 200 reference: type: string example: "referen00ce---1290034" narration: type: string example: "911 Transaction" currency: type: string example: "NGN" fee: type: integer example: 35 twoFaEnabled: type: boolean example: "false" status: type: string example: "SUCCESS" transactionDescription: type: string example: "Transaction successful" transactionReference: type: string example: "MFDS20220731033133AABQGN" createdOn: type: string format: date-time example: "2022-07-31T14:31:34.000+0000" sourceAccountNumber: type: string example: "3934178936" destinationAccountNumber: type: string example: "2085886393" destinationAccountName: type: string example: "Marvelous Benji" destinationBankCode: type: string example: "50515" destinationBankName: type: string example: "Moniepoint Microfinance bank" ListSingleTransfersResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/SingleTransferDetails" pageable: type: object properties: sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false pageSize: type: integer example: 20 pageNumber: type: integer example: 1 offset: type: integer example: 20 paged: type: boolean example: true unpaged: type: boolean example: false last: type: boolean example: false totalPages: type: integer example: 3 totalElements: type: integer example: 54 sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false first: type: boolean example: false numberOfElements: type: integer example: 20 size: type: integer example: 20 number: type: integer example: 1 empty: type: boolean example: false SingleTransferDetails: type: object properties: amount: type: integer example: 10 reference: type: string example: "hjkdd0odood0pl" narration: type: string example: "911 Transaction" currency: type: string example: "NGN" fee: type: integer example: 35 twoFaEnabled: type: boolean example: false status: type: string example: "SUCCESS" transactionDescription: type: string example: "Transaction successful" transactionReference: type: string example: "MFDS20220516012053AAAYYN" createdOn: type: string format: date-time example: "2022-05-16T12:20:54.000+0000" sourceAccountNumber: type: string example: "3934178936" destinationAccountNumber: type: string example: "0111946768" destinationAccountName: type: string example: "MEKILIUWA SMART CHINONSO" destinationBankCode: type: string example: "50515" destinationBankName: type: string example: "Moniepoint Microfinance Bank" ListBulkTransfersResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/BulkTransferDetails" pageable: type: object properties: sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false pageSize: type: integer example: 3 pageNumber: type: integer example: 0 offset: type: integer example: 0 unpaged: type: boolean example: false paged: type: boolean example: true totalPages: type: integer example: 3 last: type: boolean example: false totalElements: type: integer example: 7 sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false first: type: boolean example: true numberOfElements: type: integer example: 3 size: type: integer example: 3 number: type: integer example: 0 empty: type: boolean example: false BulkTransferDetails: type: object properties: totalAmount: type: integer example: 45 totalFee: type: integer example: 80 batchReference: type: string example: "Batch-1596666798811" batchStatus: type: string example: "COMPLETED" totalTransactionsCount: type: integer example: 4 dateCreated: type: string format: date-time example: "2020-08-05T22:33:21.000+0000" BulkBatchSummaryResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: title: type: string example: "Game of Batches" totalAmount: type: integer example: 210000 totalFee: type: integer example: 105 batchReference: type: string example: "batchreference--12934" totalTransactionsCount: type: integer example: 30 initiator: type: string example: "Monnify" failedCount: type: integer example: 10 successfulCount: type: integer example: 20 pendingCount: type: integer example: 0 pendingAmount: type: integer example: 0.00 failedAmount: type: integer example: 47600.00 successfulAmount: type: integer example: 162400.00 batchStatus: type: string example: "COMPLETED" dateCreated: type: string format: date-time BulkTransferTransactionsResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/BulkTransferTransactionDetails" pageable: type: object properties: sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false pageSize: type: integer example: 10 pageNumber: type: integer example: 0 offset: type: integer example: 0 paged: type: boolean example: true unpaged: type: boolean example: false last: type: boolean example: true totalPages: type: integer example: 1 totalElements: type: integer example: 3 sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false first: type: boolean example: true numberOfElements: type: integer example: 3 size: type: integer example: 10 number: type: integer example: 0 empty: type: boolean example: false BulkTransferTransactionDetails: type: object properties: amount: type: integer example: 230 reference: type: string example: "Final-Refer-ence-3a" narration: type: string example: "911 Transaction" currency: type: string example: "NGN" fee: type: integer example: 35 twoFaEnabled: type: boolean example: false status: type: string example: "SUCCESS" transactionDescription: type: string example: "Transaction successful" transactionReference: type: string example: "MFDS20220731034121AABQGQ" createdOn: type: string format: date-time example: "2022-07-31T14:41:21.000+0000" sourceAccountNumber: type: string example: "3934178936" destinationAccountNumber: type: string example: "0111946768" destinationAccountName: type: string example: "MEKILIUWA SMART CHINONSO" destinationBankCode: type: string example: "50515" destinationBankName: type: string example: "Moniepoint Microfinance Bank" SearchDisbursementTransactionsResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/DisbursementTransactionDetails" pageable: type: object properties: sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false pageSize: type: integer example: 10 pageNumber: type: integer example: 0 offset: type: integer example: 0 paged: type: boolean example: true unpaged: type: boolean example: false last: type: boolean example: false totalPages: type: integer example: 6 totalElements: type: integer example: 54 sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false first: type: boolean example: true numberOfElements: type: integer example: 10 size: type: integer example: 10 number: type: integer example: 0 empty: type: boolean example: false GetWalletBalanceResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: availableBalance: type: string example: "4919798101.36" ledgerBalance: type: string example: "4919798101.36" DisbursementTransactionDetails: type: object properties: amount: type: integer example: 200 reference: type: string example: "refere--n00ce---1290--034" narration: type: string example: "911 Transaction" currency: type: string example: "NGN" fee: type: integer example: 35 twoFaEnabled: type: boolean example: true status: type: string example: "EXPIRED" transactionDescription: type: string example: "Transaction has expired" transactionReference: type: string example: "MFDS20220731044951AABQGV" createdOn: type: string format: date-time example: "2022-07-31T15:49:51.000+0000" sourceAccountNumber: type: string example: "3934178936" destinationAccountNumber: type: string example: "2085886393" destinationAccountName: type: string example: "Marvelous Benji" destinationBankCode: type: string example: "50515" destinationBankName: type: string example: "Moniepoint Microfinance bank" CreateReservedAccountRequest: type: object properties: accountReference: type: string description: A unique reference generated by the merchant example: "abc1niui23" accountName: type: string description: The name to be displayed during name enquiry example: "Test Reserved Account" currencyCode: type: string description: The currency code of the account example: "NGN" contractCode: type: string description: The merchant contract code example: "5867418298" customerEmail: type: string description: The email of the customer example: "test@tester.com" customerName: type: string description: The name of the customer example: "John Doe" bvn: type: string description: The customer's BVN to be associated with the account example: "21212121212" getAllAvailableBanks: type: boolean description: Indicates if all available banks should be returned example: "true" preferredBanks: type: array description: The preferred banks for the customer. Currently defaults to 50515 (Moniepoint Microfinance Bank) items: type: string example: ["50515"] incomeSplitConfig: type: array description: The income split configuration for the account items: $ref: "#/components/schemas/IncomeSplitConfig" restrictPaymentSource: type: boolean description: Indicates if payment source should be restricted example: true default: true allowedPaymentSources: description: The allowed payment sources for the account $ref: "#/components/schemas/AllowedPaymentSources" nin: type: string description: The customer's NIN to be associated with the account example: "12345678901" required: - accountReference - accountName - currencyCode - contractCode - customerEmail - customerName - bvn - getAllAvailableBanks - preferredBanks IncomeSplitConfig: type: object properties: subAccountCode: type: string example: "MFY_SUB_319452883228" feePercentage: type: number format: float example: 10.5 splitPercentage: type: number format: float example: 20 feeBearer: type: boolean example: true splitAmount: type: number format: float example: 100.0 AllowedPaymentSources: type: object properties: bvns: type: array items: type: string example: ["21212121212", "20202020202"] bankAccounts: type: array items: $ref: "#/components/schemas/BankAccount" accountNames: type: array items: type: string example: ["SAMUEL DAMILARE OGUNNAIKE"] BankAccount: type: object properties: accountNumber: type: string example: "0068687503" bankCode: type: string example: "232" CreateReservedAccountResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/ReservedAccountDetails" ReservedAccountDetails: type: object properties: contractCode: type: string example: "5867418298" accountReference: type: string example: "abc1niui23" accountName: type: string example: "MARVELOUS BENJI" currencyCode: type: string example: "NGN" customerEmail: type: string example: "test@tester.com" customerName: type: string example: "John Doe" accounts: type: array items: $ref: "#/components/schemas/Account" collectionChannel: type: string example: "RESERVED_ACCOUNT" reservationReference: type: string example: "96ZPXECUD84UQTB00931" reservedAccountType: type: string example: "GENERAL" status: type: string example: "ACTIVE" createdOn: type: string format: date-time example: "2024-11-25 07:35:17.566" incomeSplitConfig: type: array items: $ref: "#/components/schemas/IncomeSplitConfigResponse" bvn: type: string example: "21212121212" restrictPaymentSource: type: boolean example: false allowedPaymentSources: $ref: "#/components/schemas/AllowedPaymentSources" Account: type: object properties: bankCode: type: string example: "50515" bankName: type: string example: "Moniepoint Microfinance Bank" accountNumber: type: string example: "6839490147" accountName: type: string example: "MARVELOUS BENJI" IncomeSplitConfigResponse: type: object properties: subAccountCode: type: string example: "MFY_SUB_399360552679" feePercentage: type: number format: float example: 10.5 feeBearer: type: boolean example: true splitPercentage: type: number format: float example: 20 reservedAccountConfigCode: type: string example: "N3NT809NUK" CreateInvoiceReservedAccountRequest: type: object properties: contractCode: type: string description: "The merchant's contract code." example: "5867418298" accountName: type: string description: "The name to be displayed during name enquiry." example: "Jane Doe" currencyCode: type: string description: "The currency allowed, 'NGN'." example: "NGN" accountReference: type: string description: "A unique reference generated by the merchant." example: "javnedoe12233" customerEmail: type: string description: "Email address of the customer." example: "janedoe@gmail.com" customerName: type: string description: "Full name of the customer." example: "Jane Doe" bvn: type: string description: "The customer's BVN." example: "21212121212" nin: type: string description: "The customer's NIN." example: "11212121212" reservedAccountType: type: string description: "This should be 'INVOICE'." example: "INVOICE" required: - contractCode - accountName - currencyCode - accountReference - customerEmail - customerName - reservedAccountType - bvn CreateInvoiceReservedAccountSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/InvoiceReservedAccountDetails" InvoiceReservedAccountDetails: type: object properties: contractCode: type: string example: "5867418298" accountReference: type: string example: "javnedoe12233" accountName: type: string example: "MARVELOUS BENJI" currencyCode: type: string example: "NGN" customerEmail: type: string example: "janedoe@gmail.com" customerName: type: string example: "Jane Doe" accountNumber: type: string example: "6842287969" bankName: type: string example: "Moniepoint Microfinance Bank" bankCode: type: string example: "50515" collectionChannel: type: string example: "RESERVED_ACCOUNT" reservationReference: type: string example: "LE7ZT2NR510PAM0WTYTK" reservedAccountType: type: string example: "INVOICE" status: type: string example: "INACTIVE" createdOn: type: string format: date-time example: "2024-11-27T04:35:50.054Z" incomeSplitConfig: type: array items: {} bvn: type: string example: "21212121212" restrictPaymentSource: type: boolean example: false GetReservedAccountDetailsSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/ReservedAccountDetails" AddLinkedAccountsRequest: type: object properties: getAllAvailableBanks: type: boolean description: "Determine if all necessary banks should be used." example: false preferredBanks: type: array items: type: string description: "Contains bank codes of desired banks." example: ["50515"] required: - getAllAvailableBanks AddLinkedAccountsSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/LinkedAccountDetails" LinkedAccountDetails: type: object properties: contractCode: type: string example: "5867418298" accountReference: type: string example: "abc1niui23" accountName: type: string example: "MARVELOUS BENJI" currencyCode: type: string example: "NGN" customerEmail: type: string example: "test@tester.com" customerName: type: string example: "John Doe" accounts: type: array items: $ref: "#/components/schemas/Account" collectionChannel: type: string example: "RESERVED_ACCOUNT" reservationReference: type: string example: "96ZPXECUD84UQTB00931" reservedAccountType: type: string example: "GENERAL" status: type: string example: "ACTIVE" createdOn: type: string format: date-time example: "2024-11-25T07:35:18.000Z" bvn: type: string example: "21212121212" restrictPaymentSource: type: boolean example: false UpdateBvnRequest: type: object properties: bvn: type: string description: "The BVN used in creating the reserved account." example: "21212121212" required: - bvn UpdateBvnSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/UpdatedBvnAccountDetails" UpdatedBvnAccountDetails: type: object properties: contractCode: type: string example: "5867418298" accountReference: type: string example: "abc1023" currencyCode: type: string example: "NGN" customerEmail: type: string example: "test@tester.com" customerName: type: string example: "John Doe" accountNumber: type: string example: "6842287615" bankName: type: string example: "Moniepoint Microfinance Bank" bankCode: type: string example: "50515" collectionChannel: type: string example: "RESERVED_ACCOUNT" reservationReference: type: string example: "06MCYE1991Q1X9102093" reservedAccountType: type: string example: "GENERAL" status: type: string example: "ACTIVE" createdOn: type: string format: date-time example: "2024-11-27T04:32:08.000Z" incomeSplitConfig: type: array items: $ref: "#/components/schemas/IncomeSplitConfig" bvn: type: string example: "21212121212" restrictPaymentSource: type: boolean example: true AllowedPaymentSourcesRequest: type: object properties: restrictPaymentSource: type: boolean description: "This field activates or deactivates restricting of payment sources for a reserved account." example: true allowedPaymentSources: type: object properties: bvns: type: array items: type: string description: "List of BVNs that should be validated." example: ["21212121212", "20202020202"] bankAccounts: type: array items: $ref: "#/components/schemas/BankAccount" description: "List of account numbers that can fund the reserved account." accountNames: type: array items: type: string description: "List of account names for accounts from which reserved accounts can be funded." example: ["DAMILARE OGUNNAIKE SAMUEL"] required: - restrictPaymentSource - allowedPaymentSources AllowedPaymentSourcesSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/AllowedPaymentSourcesDetails" AllowedPaymentSourcesDetails: type: object properties: restrictPaymentSource: type: boolean example: true allowedPaymentSources: type: object properties: bvns: type: array items: type: string example: ["21212121212", "20202020202"] bankAccounts: type: array items: $ref: "#/components/schemas/BankAccount" accountNames: type: array items: type: string example: "DAMILARE OGUNNAIKE SAMUEL" UpdateSplitConfigRequestItem: type: object properties: subAccountCode: type: string description: "The unique reference for the sub account that should receive the split." example: "MFY_SUB_762212281785" feeBearer: type: boolean description: "This field determines if the sub account should bear transaction fees or not." default: false example: false feePercentage: type: number format: float description: "The percentage of the transaction fee to be borne by the sub account." default: 0 example: 10.50 splitPercentage: type: number format: float description: "The percentage of the amount paid to be split into the sub account." default: 0 example: 30 required: - subAccountCode UpdateSplitConfigSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/UpdatedSplitConfigDetails" UpdatedSplitConfigDetails: type: object properties: code: type: string example: "HRCNXDSAYX" reservedAccountCode: type: string example: "HRCNXDSAYX" feeBearer: type: string example: "MERCHANT_ONLY" configDetails: type: array items: $ref: "#/components/schemas/SplitConfigDetail" SplitConfigDetail: type: object properties: subAccountCode: type: string example: "MFY_SUB_762212281785" feePercentage: type: number format: float example: 10.5 feeBearer: type: boolean example: false splitPercentage: type: number format: float example: 0 reservedAccountConfigCode: type: string example: "HRCNXDSAYX" DeallocateAccountSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/DeallocatedAccountDetails" DeallocatedAccountDetails: type: object properties: contractCode: type: string example: "5867418298" accountReference: type: string example: "abc1niui23" accountName: type: string example: "MARVELOUS BENJI" currencyCode: type: string example: "NGN" customerEmail: type: string example: "test@tester.com" customerName: type: string example: "John Doe" accountNumber: type: string example: "6839490147" bankName: type: string example: "Moniepoint Microfinance Bank" bankCode: type: string example: "50515" collectionChannel: type: string example: "RESERVED_ACCOUNT" reservationReference: type: string example: "96ZPXECUD84UQTB00931" reservedAccountType: type: string example: "GENERAL" status: type: string example: "ACTIVE" createdOn: type: string format: date-time example: "2024-11-25T07:35:18.000Z" bvn: type: string example: "21212121212" restrictPaymentSource: type: boolean example: false GetTransactionsSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/TransactionsResponseBody" TransactionsResponseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/Transaction" pageable: $ref: "#/components/schemas/Pageable" totalElements: type: integer example: 2 totalPages: type: integer example: 1 last: type: boolean example: true sort: $ref: "#/components/schemas/Sort" first: type: boolean example: true numberOfElements: type: integer example: 2 size: type: integer example: 10 number: type: integer example: 0 empty: type: boolean example: false Transaction: type: object properties: customerDTO: $ref: "#/components/schemas/CustomerDTO" providerAmount: type: number format: float example: 0.21 paymentMethod: type: string example: "ACCOUNT_TRANSFER" createdOn: type: string format: date-time example: "2019-07-24T14:12:27.000+0000" amount: type: number format: float example: 100.00 flagged: type: boolean example: false providerCode: type: string example: "98271" fee: type: number format: float example: 0.79 currencyCode: type: string example: "NGN" completedOn: type: string format: date-time example: "2019-07-24T14:12:28.000+0000" paymentDescription: type: string example: "Test Reserved Account" paymentStatus: type: string example: "PAID" transactionReference: type: string example: "MNFY|20190724141227|003374" paymentReference: type: string example: "MNFY|20190724141227|003374" merchantCode: type: string example: "ALJKHDALASD" merchantName: type: string example: "Test Limited" payableAmount: type: number format: float example: 100.00 amountPaid: type: number format: float example: 100.00 completed: type: boolean example: true settleInstantly: type: boolean example: true CustomerDTO: type: object properties: email: type: string example: "test@tester.com" name: type: string example: "Test Reserved Account" merchantCode: type: string example: "ALJKHDALASD" Pageable: type: object properties: sort: $ref: "#/components/schemas/Sort" pageSize: type: integer example: 10 pageNumber: type: integer example: 0 offset: type: integer example: 0 unpaged: type: boolean example: false paged: type: boolean example: true Sort: type: object properties: sorted: type: boolean example: true unsorted: type: boolean example: false empty: type: boolean example: false UpdateKycInfoRequest: type: object properties: bvn: type: string description: "The customer's BVN." example: "22222222222" nin: type: string description: "The customer's NIN." example: "121212121212" required: - bvn - nin UpdateKycInfoSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/UpdatedKycInfoDetails" UpdatedKycInfoDetails: type: object properties: accountReference: type: string example: "a1fe1c73c6f985eb43e8ef35ec0d6a398698cdea" accountName: type: string example: "MARVELOUS BENJI" customerEmail: type: string example: "test@tester.com" customerName: type: string example: "mao Zhang" bvn: type: string example: "21212121212" CreateInvoiceRequest: type: object properties: amount: type: number format: float description: "The amount to be paid by the customer" example: 999 currencyCode: type: string description: 'The currency of the transaction being initialized. "NGN"' example: "NGN" invoiceReference: type: string description: "Merchant's Unique reference for the invoice" example: "183891300182" customerName: type: string description: "Full name of the customer" example: "John Snow" customerEmail: type: string description: "Email of the customer" example: "johnsnow@gmail.com" contractCode: type: string description: "Merchant's contract code" example: "7059707855" description: type: string description: "Description of the transaction. Will be used as the account name for bank transfer payments" example: "test invoice" expiryDate: type: string format: date-time description: "The expiry date for the invoice. The format is: YYYY-MM-DD HH:MM:SS" example: "2022-10-30 12:00:00" paymentMethods: type: array items: type: string example: incomeSplitConfig: type: array items: $ref: "#/components/schemas/IncomeSplitConfig" description: "This field contains specifications on how payments to this reserve account should be split." redirectUrl: type: string description: "A URL which customer will be redirected to when payment is successfully completed" example: "http://app.monnify.com" accountReference: type: string description: "Your unique reference used to identify this reserved account. Required if a reserved account is to be attached" required: - amount - currencyCode - invoiceReference - customerName - customerEmail - contractCode - description - expiryDate CreateInvoiceSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/InvoiceDetails" InvoiceDetails: type: object properties: amount: type: number format: float example: 999 invoiceReference: type: string example: "183891300182" invoiceStatus: type: string example: "PENDING" description: type: string example: "test invoice" contractCode: type: string example: "7059707855" customerEmail: type: string example: "johnsnow@gmail.com" customerName: type: string example: "John Snow" expiryDate: type: string format: date-time example: "2022-10-30 12:00:00" createdBy: type: string example: "MK_TEST_JRQAZRFD2W" createdOn: type: string format: date-time example: "2022-07-31 12:14:14" checkoutUrl: type: string example: "https://sandbox.sdk.monnify.com/checkout/MNFY|99|20220731121414|000867" accountNumber: type: string example: "5000588061" accountName: type: string example: "tes" bankName: type: string example: "Moniepoint Microfinance bank" bankCode: type: string example: "50515" redirectUrl: type: string example: "http://app.monnify.com" transactionReference: type: string example: "MNFY|99|20220731121414|000867" incomeSplitConfig: type: array items: $ref: "#/components/schemas/InvoiceSplitConfig" InvoiceSplitConfig: type: object properties: subAccountCode: type: string example: "MFY_SUB_322165393053" splitAmount: type: number format: float example: 20 feePercentage: type: number format: float example: 10.5 feeBearer: type: boolean example: true splitPercentage: type: number format: float nullable: true example: null ViewInvoiceDetailsSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/InvoiceDetails" GetAllInvoicesSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/InvoiceList" InvoiceList: type: object properties: content: type: array items: $ref: "#/components/schemas/InvoiceListItem" pageable: $ref: "#/components/schemas/Pageable" last: type: boolean example: true totalElements: type: integer example: 6 totalPages: type: integer example: 1 sort: $ref: "#/components/schemas/Sort" first: type: boolean example: true numberOfElements: type: integer example: 6 size: type: integer example: 10 number: type: integer example: 0 empty: type: boolean example: false InvoiceListItem: type: object properties: amount: type: number format: float example: 999 invoiceReference: type: string example: "18389130010082" invoiceStatus: type: string example: "PENDING" description: type: string example: "test invoice" contractCode: type: string example: "7059707855" customerEmail: type: string example: "johnsnow@gmail.com" customerName: type: string example: "John Snow" expiryDate: type: string format: date-time example: "2022-10-30 12:00:00" createdBy: type: string example: "MK_TEST_JRQAZRFD2W" createdOn: type: string format: date-time example: "2022-07-31 12:29:26" accountNumber: type: string example: "5000588060" bankName: type: string example: "Moniepoint Microfinance bank" bankCode: type: string example: "50515" CancelInvoiceSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/CancelledInvoiceDetails" CancelledInvoiceDetails: type: object properties: amount: type: number format: float example: 999 invoiceReference: type: string example: "18389130010082" invoiceStatus: type: string example: "CANCELLED" description: type: string example: "test invoice" contractCode: type: string example: "7059707855" customerEmail: type: string example: "johnsnow@gmail.com" customerName: type: string example: "John Snow" expiryDate: type: string format: date-time example: "2022-10-30 12:00:00" createdBy: type: string example: "MK_TEST_JRQAZRFD2W" createdOn: type: string format: date-time example: "2022-07-31 12:29:26" accountNumber: type: string example: "5000588060" bankName: type: string example: "Moniepoint Microfinance bank" bankCode: type: string example: "50515" ChargeCardTokenRequest: type: object properties: cardToken: type: string description: "Card token gotten by performing a re-query on a card transaction using the Get Transaction Status API." example: "MNFY_0CD0138B45F7478E941C3EC6D3698969" amount: type: number format: float description: "The amount(in Naira) to be paid, minimum is N20" example: 20 customerName: type: string description: "Full name of the customer" example: "Marvelous Benji" customerEmail: type: string description: "Email of the customer. The customer email used in the first charge" format: email example: "benjikali29@gmail.com" paymentReference: type: string description: "A unique string of characters that identifies each transaction" example: "1642776mml0068n2937" paymentDescription: type: string description: "A description of the payment" example: "Paying for Product A" currencyCode: type: string description: "The currency code" default: "NGN" example: "NGN" contractCode: type: string description: "The merchant contract code" example: "5867418298" apiKey: type: string description: "The merchant API key" example: "MK_PROD_WTZLS10MX6" metaData: $ref: "#/components/schemas/MetaData" incomeSplitConfig: type: array items: $ref: "#/components/schemas/IncomeSplitConfig" description: "A way to split payments among subAccounts." required: - cardToken - amount - customerEmail - paymentReference - contractCode - apiKey MetaData: type: object properties: ipAddress: type: string description: "Customer's IP Address" example: "127.0.0.1" deviceType: type: string description: "Customer's Device Type" example: "mobile" ChargeCardTokenSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/ChargeCardTokenResponseBody" ChargeCardTokenResponseBody: type: object properties: transactionReference: type: string example: "MNFY|87|20230602223418|007039" paymentReference: type: string example: "1642776mml0068n2937" amountPaid: type: string example: "20.00" totalPayable: type: string example: "20.00" settlementAmount: type: string example: "19.68" paidOn: type: string example: "02/06/2023 10:34:26 PM" paymentStatus: type: string example: "PAID" paymentDescription: type: string example: "Paying for Product A" currency: type: string example: "NGN" paymentMethod: type: string example: "CARD" product: $ref: "#/components/schemas/Product" cardDetails: $ref: "#/components/schemas/CardDetails" accountDetails: type: "object" nullable: true accountPayments: type: array items: type: object customer: $ref: "#/components/schemas/CustomerDetails" metaData: $ref: "#/components/schemas/MetaData" Product: type: object properties: type: type: string example: "API_NOTIFICATION" reference: type: string example: "1642776mml0068n2937" CardDetails: type: object properties: cardType: type: string example: "MasterCard" last4: type: string example: "9098" expMonth: type: string example: "07" expYear: type: string example: "23" bin: type: string example: "539941" bankCode: type: string example: "057" bankName: type: string example: "Zenith bank" reusable: type: boolean example: true countryCode: type: "string" nullable: true cardToken: type: string example: "MNFY_0CD0138B45F7478E941C3EC6D3698969" supportsTokenization: type: boolean example: false maskedPan: type: string example: "539941******9098" CustomerDetails: type: object properties: email: type: string format: email example: "benjikali29@gmail.com" name: type: string example: "Marvelous Benji" CreateMandateRequest: type: object properties: contractCode: type: string description: "The merchant’s Monnify contract code" example: "4934121686" mandateReference: type: string description: "Merchants generated reference to identify a mandate" example: "unique_ref3_02s600972" mandateAmount: type: number format: float description: "Total lifetime amount debitable on the mandate." example: 50000 autoRenew: type: boolean description: "This informs Monnify wether the mandate will be renewed once it reaches end date." example: false customerCancellation: type: boolean description: "Informs Monnify if the Mandate can be cancelled by the customer" example: true customerName: type: string description: "The customer's name" example: "Ankit Kushwaha" customerPhoneNumber: type: string description: "The customer's phone number" example: "1234567890" customerEmailAddress: type: string format: email description: "The customer's email address" example: "test@moniepoint.com" customerAddress: type: string description: "The customer's home address" example: "123 Example Street, City, Country" customerAccountNumber: type: string description: "The customer's bank account number" example: "0051762787" customerAccountBankCode: type: string description: "The bank code of the customer’s bank account" example: "044" mandateDescription: type: string description: "The description of the payment the mandate is associated to" example: "Subscription Fee" mandateStartDate: type: string format: date-time description: "The start date for the mandate. The date format is: YYYY-MM-DDTHH:MM:SS" example: "2024-12-19T10:15:30" mandateEndDate: type: string format: date-time description: "The end date for the mandate. The date format is: YYYY-MM-DDTHH:MM:SS" example: "2025-12-19T10:15:30" redirectUrl: type: string description: A URL to redirect to after payment completion. example: "https://my-merchants-page.com/direct-debit/success" debitAmount: type: number format: float description: "The amount to be debited periodically." nullable: true example: null required: - contractCode - mandateReference - customerName - customerEmailAddress - customerPhoneNumber - customerAddress - customerAccountNumber - customerAccountBankCode - mandateDescription - mandateStartDate - mandateEndDate CreateMandateSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/MandateCreationResponseBody" MandateCreationResponseBody: type: object properties: responseMessage: type: string example: "Your request for creating a mandate is submitted. An authorization instruction will be sent to the customer email." mandateReference: type: string example: "unique_ref3_02s600972" mandateCode: type: string example: "MTDD|01HY8W3FBKHTFBZP9DQ9KNHR1G" mandateStatus: type: string example: "INITIATED" redirectUrl: type: string example: "https://my-merchants-page.com/transaction/confirm" GetMandateStatusSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: array items: $ref: "#/components/schemas/MandateStatusDetails" MandateStatusDetails: type: object properties: mandateCode: type: string example: "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0" mandateReference: type: string example: "unique_ref3_02gs600s972" startDate: type: string format: date-time example: "2024-05-19T09:15:30.000+0000" endDate: type: string format: date-time example: "2024-09-22T09:15:30.000+0000" mandateStatus: type: string example: "ACTIVE" mandateAmount: type: integer example: 50000 contractCode: type: string example: "4934121686" autoRenew: type: boolean example: false customerPhoneNumber: type: string example: "1234567890" customerEmailAddress: type: string format: email example: "test@moniepoint.com" customerAddress: type: string example: "123 Example Street, City, Country" customerName: type: string example: "Ankit Kushwaha" customerAccountName: type: string example: "Ankit Kushwaha" customerAccountNumber: type: string example: "0051762787" customerAccountBankCode: type: string example: "998" mandateDescription: type: string example: "Subscription Fee" debitAmount: type: "integer" nullable: true example: null authorizationMessage: type: "string" example: "Request Ankit Kushwaha to kindly proceed with a token payment of N50.00 into account number 9020025928 with Fidelity Bank. This transfer must be initiated from the account in the mandate request. This payment will trigger the authentication of customer and will authorize this mandate." nullable: true authorizationLink: type: "string" example: "https://paylink.monnify.com/mandate-auth/MTDD%7C01K7M2Y6BN6QZ9KF0WEEG7YPVP?accountNumber=9020025928&bankName=Fidelity+Bank&customerAccountName=ANKIT++KUSHWAHA&amount=50.00" nullable: true DebitMandateRequest: type: object properties: paymentReference: type: string description: "Merchants unique reference to identify a single direct debit payment" example: "PR1234567991002" mandateCode: type: string description: "Monnify generated mandate identifier" example: "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0" debitAmount: type: number format: float description: "Payment amount to be debited from a single debit transaction" example: 1000.00 narration: type: string description: "Description of the single debit" example: "Payment for Services" customerEmail: type: string format: email description: "The customer's email address" example: "ahsan.saleem@gmail.com" incomeSplitConfig: type: array items: type: object properties: subAccountCode: type: string description: The unique reference for the sub account that should receive the split. Required if income split is enabled. example: "MFY_SUB_319452883228" feePercentage: type: number description: The percentage of the fee to be borne by the subAccount. format: float example: 10.5 splitAmount: type: number description: The constant amount to be sent to the subAccount for each transaction. Expected if splitPercentage is not provided format: float example: 20 splitPercentage: type: number description: The percent amount to be splitted into the subAccount for each transaction. Expected if splitAmount is not provided format: float example: 20 feeBearer: type: boolean description: Indicates if the subAccount bears the fee. example: true description: A way to split payments among subAccounts. required: - paymentReference - mandateCode - debitAmount - narration - customerEmail DebitMandateSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/DebitMandateResponseBody" DebitMandateResponseBody: type: object properties: transactionStatus: type: string example: "PENDING" responseMessage: type: string example: "Debit mandate request accepted for processing" transactionReference: type: string example: "MNFY|20240519180055|000001" paymentReference: type: string example: "PR1234567991002" debitAmount: type: integer example: 1000 narration: type: string example: "Payment for Services" mandateCode: type: string example: "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0" GetDebitStatusSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/DebitStatusDetails" DebitStatusDetails: type: object properties: transactionStatus: type: string example: "PAID" responseMessage: type: "object" nullable: true transactionReference: type: string example: "MNFY|20240519180055|000001" paymentReference: type: string example: "PR1234567991002" debitAmount: type: integer example: 1000 narration: type: string example: "Payment for Services" mandateCode: type: string example: "MTDD|01HY8WMN8JYKDRJC67QPQVS1N0" UpdateMandateSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/UpdateMandateResponseBody" UpdateMandateResponseBody: type: object properties: responseMessage: type: string example: "Mandate has been requested to be cancelled." mandateReference: type: string example: "unique_ref3_02s600972" mandateCode: type: string example: "MTDD|01HY8W3FBKHTFBZP9DQ9KNHR1G" mandateStatus: type: string example: "ACTIVE" GetMandatesListSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: content: type: array items: $ref: "#/components/schemas/MandateStatusDetails" totalElements: type: integer example: 42 totalPages: type: integer example: 3 pageNumber: type: integer example: 0 pageSize: type: integer example: 20 first: type: boolean example: true last: type: boolean example: false numberOfElements: type: integer example: 20 empty: type: boolean example: false CreateSubAccountRequest: type: object properties: currencyCode: type: string description: 'Settlement currency. "NGN"' example: "NGN" accountNumber: type: string description: "The account number that should be created as a sub account." example: "0211319282" bankCode: type: string description: "The 3 digit bank code of the bank where the account number is domiciled" example: "058" email: type: string format: email description: "The email tied to the sub account" example: "tamira1@gmail.com" defaultSplitPercentage: type: number format: float description: "The default percentage to be split into the sub account on any transaction." example: 20.87 required: - currencyCode - accountNumber - bankCode - email - defaultSplitPercentage CreateSubAccountSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: array items: $ref: "#/components/schemas/SubAccountDetails" SubAccountDetails: type: object properties: subAccountCode: type: string example: "MFY_SUB_811397375865" accountNumber: type: string example: "0211319282" accountName: type: string example: "ALEMOH DANIEL MOSES" currencyCode: type: string example: "NGN" email: type: string format: email example: "tamira1@gmail.com" bankCode: type: string example: "058" bankName: type: string example: "GTBank" defaultSplitPercentage: type: number format: float example: 20.87 settlementProfileCode: type: string example: "8717495899" settlementReportEmails: type: array items: type: string DeleteSubAccountSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" GetSubAccountsSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: array items: $ref: "#/components/schemas/SubAccountDetails" UpdateSubAccountRequest: type: object properties: subAccountCode: type: string description: "The sub account code of the account to be updated." example: "MFY_SUB_811397375865" currencyCode: type: string description: 'Settlement currency. "NGN"' example: "NGN" accountNumber: type: string description: "The account number that should be created as a sub account." example: "0211319282" bankCode: type: string description: "The 3 digit bank code of the bank where the account number is domiciled" example: "058" email: type: string format: email description: "The email tied to the sub account" example: "kali@gmail.com" defaultSplitPercentage: type: number format: float description: "The default percentage to be split into the sub account on any transaction." example: 25 required: - subAccountCode - currencyCode - accountNumber - bankCode - email - defaultSplitPercentage UpdateSubAccountSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/SubAccountDetails" CreateLimitProfileRequest: type: object properties: limitProfileName: type: string description: "The name of the Limit Profile" example: "Profile0001" singleTransactionValue: type: number format: float description: "The maximum amount that can be allowed per transaction on the reserved accounts." example: 2000 dailyTransactionValue: type: number format: float description: "The maximum amount per day in all transactions that can be allowed on the reserved accounts" example: 150000 dailyTransactionVolume: type: integer description: "The maximum number of transaction count per day allowed on the reserved accounts" example: 500 required: - limitProfileName - singleTransactionValue - dailyTransactionValue - dailyTransactionVolume CreateLimitProfileSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/LimitProfileDetails" LimitProfileDetails: type: object properties: limitProfileCode: type: string example: "FSYVVWU8UPBD" limitProfileName: type: string example: "Profile0001" singleTransactionValue: type: integer example: 2000 dailyTransactionVolume: type: integer example: 500 dailyTransactionValue: type: integer example: 150000 dateCreated: type: string example: "02/08/2022 02:27:43 AM" lastModified: type: string example: "02/08/2022 02:27:43 AM" GetLimitProfilesSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/LimitProfilePage" LimitProfilePage: type: object properties: content: type: array items: $ref: "#/components/schemas/LimitProfileDetails" pageable: $ref: "#/components/schemas/PageableObject" last: type: boolean example: true totalElements: type: integer example: 3 totalPages: type: integer example: 1 sort: $ref: "#/components/schemas/SortObject" first: type: boolean example: true numberOfElements: type: integer example: 3 size: type: integer example: 10 number: type: integer example: 0 empty: type: boolean example: false UpdateLimitProfileRequest: type: object properties: limitProfileName: type: string description: "The name of the Limit Profile" example: "prof991" singleTransactionValue: type: number format: float description: "The maximum amount that can be allowed per transaction on the reserved accounts." example: 70000 dailyTransactionValue: type: number format: float description: "The maximum amount per day in all transactions that can be allowed on the reserved accounts" example: 100000000 dailyTransactionVolume: type: integer description: "The maximum number of transaction count per day allowed on the reserved accounts" example: 4000 required: - limitProfileName - singleTransactionValue - dailyTransactionValue - dailyTransactionVolume UpdateLimitProfileSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/LimitProfileDetails" ReserveAccountWithLimitRequest: type: object properties: contractCode: type: string description: "The merchant contract code" example: "7059707855" accountName: type: string description: "The name to be displayed during name enquiry" example: "Kan Yo' Reserved with Limit" currencyCode: type: string description: "The currency payments will be received with" example: "NGN" accountReference: type: string description: "A unique reference generated by merchants." example: "ref-00--7" customerEmail: type: string format: email description: "The customer's email" example: "KanYo@monnify.com" customerName: type: string description: "customer name" example: "Kan Yo" getAllAvailableBanks: type: boolean description: "if you want to get all available banks" example: false preferredBanks: type: array items: type: string description: "list of preferred banks" example: ["50515"] limitProfileCode: type: string description: "The unique identifier that references the limit profile to associate with the reserved accounts." example: "FSYVVWU8UPBD" required: - contractCode - accountName - accountReference - limitProfileCode ReserveAccountWithLimitSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/ReservedAccountDetailsWithLimit" ReservedAccountDetailsWithLimit: type: object properties: contractCode: type: string example: "7059707855" accountReference: type: string example: "ref-00--7" accountName: type: string example: "Kan" currencyCode: type: string example: "NGN" customerEmail: type: string format: email example: "KanYo@monnify.com" customerName: type: string example: "Kan Yo" accountNumber: type: string example: "5000578928" bankName: type: string example: "Moniepoint Microfinance bank" bankCode: type: string example: "50515" collectionChannel: type: string example: "RESERVED_ACCOUNT" reservationReference: type: string example: "0B70FP4CNC61U334XFG1" reservedAccountType: type: string example: "GENERAL" status: type: string example: "ACTIVE" createdOn: type: string format: date-time example: "2022-08-02T02:53:25.617Z" incomeSplitConfig: type: array items: type: object restrictPaymentSource: type: boolean example: false limitProfileConfig: $ref: "#/components/schemas/LimitProfileConfigDetails" UpdateReserveAccountLimitRequest: type: object properties: accountReference: type: string description: "A unique reference generated by merchants." example: "ref-00--7" limitProfileCode: type: string description: "The unique identifier that references the limit profile to associate with the reserved accounts." example: "FSYVVWU8UPBD" required: - accountReference - limitProfileCode UpdateReserveAccountLimitSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/ReservedAccountDetailsWithLimit" InitiateRefundRequest: type: object properties: transactionReference: type: string description: "Unique identifier for the transaction generated by Monnify." example: "MNFY|65|20220727094724|000477" refundAmount: type: number format: float description: "Amount to refund." example: 100 refundReference: type: string description: "Unique identifier for the transaction refund generated by the merchant." example: "202100op3456" refundReason: type: string description: "A note describing reason why this transaction is being refunded." example: "Order cancelled!" customerNote: type: string description: "This field serves as a narration in credit to the customer's bank account." example: "Refund for Purchase #2873872" destinationAccountNumber: type: string description: "The account number to be refunded" example: "3270005594" destinationAccountBankCode: type: string description: "The bank code for the destinationAccountNumber." example: "050" required: - transactionReference - refundAmount - refundReference - refundReason - customerNote InitiateRefundSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/RefundDetails" RefundDetails: type: object properties: refundReference: type: string example: "202100op3456" reference: type: string example: "TRFD|49|20220727094724|0006" transactionReference: type: string example: "MNFY|65|20220727094724|000477" refundReason: type: string example: "Order cancelled!" customerNote: type: string example: "Refund for Purchase #2873872" refundAmount: type: integer example: 100 refundType: type: string example: "PARTIAL_REFUND" refundStatus: type: string example: "COMPLETED" refundStrategy: type: string example: "MERCHANT_WALLET" comment: type: string example: "Transaction refund is in progress." createdOn: type: string format: date-time example: "02/08/2022 03:35:22 AM" destinationAccountName: type: string example: "John Doe" destinationAccountNumber: type: string example: "0123456789" destinationBankName: type: string example: "Moniepoint MFB" currencyCode: type: string example: "NGN" # Wallet schema used for arrays/listing endpoints Wallet: type: object description: A wallet object returned in lists (mirrors the CreateWalletSuccessResponse.responseBody) properties: walletName: type: string description: The name of the wallet example: "Staging Wallet - ref1684248425966" walletReference: type: string description: The unique identifier for the wallet example: "ref1684248425966" customerName: type: string description: The customer's name example: "John Doe" customerEmail: type: string description: The customer's email example: "johndoe@example.com" feeBearer: type: string example: "SELF" bvnDetails: type: object properties: bvn: type: integer minLength: 11 maxLength: 11 example: "22222222226" bvnDateOfBirth: type: string format: date example: "1994-09-07" accountNumber: type: string description: The account number associated with the wallet example: "1234567890" accountName: type: string description: The account name associated with the wallet example: "John Doe" topUpAccountDetails: type: object properties: accountNumber: type: string example: "1234567890" accountName: type: string example: "John Doe" bankCode: type: string example: "50515" bankName: type: string example: "Moniepoint MFB" createdOn: type: string format: date-time example: "2025-11-12T11:40:25.344+00:00" GetRefundStatusSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/RefundDetails" GetAllRefundsSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/RefundPage" RefundPage: type: object properties: content: type: array items: $ref: "#/components/schemas/RefundDetails" pageable: $ref: "#/components/schemas/PageableObject" last: type: boolean example: false totalElements: type: integer example: 17 totalPages: type: integer example: 2 sort: $ref: "#/components/schemas/SortObject" first: type: boolean example: true numberOfElements: type: integer example: 10 size: type: integer example: 10 number: type: integer example: 0 empty: type: boolean example: false GetSettlementInformationForTransactionSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: type: object properties: transaction: type: object properties: transactionReference: type: string example: "MNFY|28|20220718162222|066201" paymentReference: type: string example: "1658157741945" amountPaid: type: string example: "20.32" totalPayable: type: string example: "20.32" settlementAmount: type: string example: "20.00" paidOn: type: string example: "18/07/2022 04:23:55 PM" paymentStatus: type: string example: "PAID" paymentDescription: type: string example: "lets pay" currency: type: string example: "NGN" paymentMethod: type: string example: "CARD" product: type: object properties: type: type: string example: "WEB_SDK" reference: type: string example: "1658157741945" cardDetails: type: object nullable: true properties: cardType: type: string example: "MasterCard" last4: type: string example: "9098" expMonth: type: string example: "07" expYear: type: string example: "23" bin: type: string example: "539941" bankCode: type: string example: "057" bankName: type: string example: "Zenith bank" reusable: type: boolean example: true countryCode: type: string nullable: true example: null cardToken: type: string example: "MNFY_1B4B8224C4A847DE847B094AB7B979F9" supportsTokenization: type: boolean example: true maskedPan: type: string example: "539941******9098" accountDetails: type: object nullable: true example: null accountPayments: type: array items: {} customer: type: object properties: email: type: string example: "customer@example.com" name: type: string example: "John Doe" metaData: type: object additionalProperties: type: string example: name: "Damilare" age: "45" beneficiaries: type: array items: type: object properties: beneficiaryType: type: string example: "MERCHANT_CONTRACT" beneficiaryCode: type: string example: "100693167467" beneficiaryIncome: type: number example: 20 incurredFee: type: number example: 0.32 settlementStatus: type: string example: "SUCCESS" settlementInformation: type: object properties: settledDate: type: string example: "2022-07-20T21:01:06.000+0000" settlementReference: type: string example: "XUY3FHWRJP3CEM4N17BA" settlementAmount: type: number example: 79.68 settlementFee: type: number example: 0 destinationAccountNumber: type: string example: "2085886393" destinationAccountName: type: string example: "BENJAMIN CHUKWUEMEKA ONONOGBU" destinationBankName: type: string example: "Zenith bank" destinationBankCode: type: string example: "057" GetTransactionsBySettlementReferenceSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/TransactionPage" TransactionPage: type: object properties: content: type: array items: $ref: "#/components/schemas/TransactionDetails" pageable: $ref: "#/components/schemas/PageableObject" last: type: boolean example: true totalElements: type: integer example: 4 totalPages: type: integer example: 1 sort: $ref: "#/components/schemas/SortObject" first: type: boolean example: true numberOfElements: type: integer example: 4 size: type: integer example: 20 number: type: integer example: 0 empty: type: boolean example: false TransactionDetails: type: object properties: transactionReference: type: string example: "MNFY|28|20220718162222|066201" paymentReference: type: string example: "1658157741945" amountPaid: type: string example: "20.32" totalPayable: type: string example: "20.32" settlementAmount: type: string example: "20.00" paidOn: type: string example: "18/07/2022 04:23:55 PM" paymentStatus: type: string example: "PAID" paymentDescription: type: string example: "lets pay" transactionHash: type: string example: "218523babb5416ed29477d618c315f458d6a7e881edf9d7a7cfb5fa7a61a16857f80cb1a795ee07cdfd92f9502970cb71d59c4b21017952feacff99f17cbdb92" currency: type: string example: "NGN" paymentMethod: type: string example: "CARD" product: type: object properties: type: type: string example: "WEB_SDK" reference: type: string example: "1658157741945" cardDetails: type: object properties: cardType: type: string example: "MasterCard" last4: type: string example: "9098" expMonth: type: string example: "07" expYear: type: string example: "23" bin: type: string example: "539941" bankCode: type: string example: "057" bankName: type: string example: "Zenith bank" reusable: type: boolean example: true countryCode: type: "null" cardToken: type: string example: "MNFY_1B4B8224C4A847DE847B094AB7B979F9" supportsTokenization: type: boolean example: true maskedPan: type: string example: "539941******9098" accountDetails: type: "null" accountPayments: type: array items: type: object customer: type: object properties: email: type: string example: "test@teamapt.com" name: type: string example: "Marvelous Benji" metaData: type: object example: name: "Damilare" age: "45" ValidateBankAccountSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/AccountValidationDetails" AccountValidationDetails: type: object properties: accountNumber: type: string example: "0123456789" accountName: type: string example: "Damilare Ogunnaike" bankCode: type: string example: "057" BVNVerificationRequest: type: object required: - bvn - name - dateOfBirth - mobileNo properties: bvn: type: string example: "22222222226" description: "The user's bvn" name: type: string example: "OLATUNDE JOSIAH OGUNBOYEJO" description: "The user’s name" dateOfBirth: type: string example: "27-Apr-1993" description: "The user’s date of birth" mobileNo: type: string example: "08142223149" description: "The user's mobile number" BVNVerificationSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/BVNVerificationDetails" BVNVerificationFailureResponse: type: object properties: requestSuccessful: type: boolean example: false responseMessage: type: string example: "Unable to process request. Invalid BVN provided" responseCode: type: string example: "99" BVNVerificationDetails: type: object properties: bvn: type: string example: "22228945899" name: type: object properties: matchStatus: type: string enum: - "FULL_MATCH" - "PARTIAL_MATCH" - "NO_MATCH" example: "FULL_MATCH" matchPercentage: type: integer example: 100 dateOfBirth: type: string enum: - "FULL_MATCH" - "NO_MATCH" example: "NO_MATCH" mobileNo: type: string enum: - "FULL_MATCH" - "NO_MATCH" example: "FULL_MATCH" BVNAccountMatchRequest: type: object required: - bankCode - accountNumber - bvn properties: bankCode: type: string example: "057" description: "The user’s bank code" accountNumber: type: string example: "2191802645" description: "The user's account number" bvn: type: string example: "22222222226" description: "The user’s bvn" BVNAccountMatchSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/BVNAccountMatchDetails" BVNAccountMatchFailureResponse: type: object properties: requestSuccessful: type: boolean example: false responseMessage: type: string example: "Unable to process request. Invalid BVN provided" responseCode: type: string example: "99" BVNAccountMatchDetails: type: object properties: bvn: type: string example: "22222222226" accountNumber: type: string example: "0103284175" accountName: type: string example: "OLATUNDE JOSIAH OGUNBOYEJO" matchStatus: type: string enum: - "FULL_MATCH" - "NO_MATCH" example: "FULL_MATCH" matchPercentage: type: integer example: 100 NINVerificationRequest: type: object required: - nin properties: nin: type: string example: "94646622685" description: "The customer’s NIN number" NINVerificationSuccessResponse: type: object properties: requestSuccessful: type: boolean example: true responseMessage: type: string example: "success" responseCode: type: string example: "0" responseBody: $ref: "#/components/schemas/NINVerificationDetails" NINVerificationFailureResponse: type: object properties: requestSuccessful: type: boolean example: false responseMessage: type: string example: "NIN not found. Please check and try again." responseCode: type: string example: "99" NINVerificationDetails: type: object properties: nin: type: string example: "91919191913" lastName: type: string example: "WILES" firstName: type: string example: "BENJAMIN" middleName: type: string example: "CHUKS" dateOfBirth: type: string example: "1996-10-08" gender: type: string example: "OTHER" mobileNumber: type: string example: "2348107248890" CategoryResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: content: type: array items: type: object properties: code: type: string name: type: string totalElements: type: integer size: type: integer number: type: integer empty: type: boolean BillerResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: content: type: array items: type: object properties: code: type: string name: type: string categories: type: array items: type: object properties: code: type: string name: type: string ProductResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: content: type: array items: type: object properties: code: type: string name: type: string minAmount: type: number nullable: true maxAmount: type: number nullable: true price: type: number nullable: true priceType: type: string VendRequest: type: object required: - productCode - customerId - amount - reference properties: productCode: type: string description: The unique code for the product being purchased. example: "245" customerId: type: string description: The customer's identifier (e.g., phone number, meter number). example: "08130211113" validationReference: type: string description: A reference obtained from the customer validation endpoint, if required. example: "724707993771" amount: type: number description: The amount for the transaction. example: 300 emailAddress: type: string format: email description: The customer's email address for notifications. example: "customer@example.com" phoneNumber: type: string description: The customer's phone number. example: "09135914842" reference: type: string description: A unique reference for this transaction. example: "REF-MH0H27YL-966MVT" VendResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: vendReference: type: string transactionReference: type: string vendStatus: type: string description: type: string vendAmount: type: number payableAmount: type: number commission: type: number customerId: type: string productCode: type: string productName: type: string billerCode: type: string billerName: type: string RequeryResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: transactionReference: type: string vendStatus: type: string description: type: string ValidateCustomerRequest: type: object required: - productCode - customerId properties: productCode: type: string description: The unique code for the product. example: "13" customerId: type: string description: The customer's identifier to validate. example: "08130211113" ValidateCustomerResponse: type: object properties: requestSuccessful: type: boolean responseMessage: type: string responseCode: type: string responseBody: type: object properties: customerName: type: string priceType: type: string price: type: number nullable: true vendInstruction: type: object properties: requireValidationRef: type: boolean validationReference: type: string CreatePaycodeRequest: type: object required: - beneficiaryName - amount - paycodeReference - expiryDate - clientId properties: beneficiaryName: type: string description: "The customer's name" example: "Marvelous Benji" amount: type: number format: float description: "The amount to be withdrawn" example: 30 paycodeReference: type: string description: "A unique reference generated by the merchant" example: "ur749o04jhke993u93o" expiryDate: type: string description: "The expiry date for the paycode. The format is:YYYY-MM-DD HH:MM:SS" example: "2023-10-18 19:00:26" clientId: type: string description: "The merchant's APIKey" example: "MK_PROD_GFVLE0PZTQ" CreatePaycodeSuccessResponse: type: object properties: responseMessage: type: string example: "success" responseCode: type: string example: "M00" responseBody: $ref: "#/components/schemas/PaycodeDetails" PaycodeDetails: type: object properties: paycode: type: string example: "11467409" transactionReference: type: string example: "MFY-39A78F78E6C341759ACA344297A8CF70" paycodeReference: type: string example: "ghehdekdkefkefjekjfejj" beneficiaryName: type: string example: "Marvelous Benji" amount: type: number format: float example: 50 fee: type: integer example: 100 transactionStatus: type: string example: "PENDING" expiryDate: type: string example: "2023-02-19 11:00:26" createdOn: type: string format: date-time example: "2023-02-16T12:32:01.591+0000" createdBy: type: string example: "MK_PROD_WTZLS10MX6" modifiedBy: type: string example: "MK_PROD_WTZLS10MX6" GetPaycodeSuccessResponse: type: object properties: responseMessage: type: string example: "success" responseCode: type: string example: "M00" responseBody: $ref: "#/components/schemas/PaycodeDetails" FetchPaycodesSuccessResponse: type: object properties: responseMessage: type: string example: "success" responseCode: type: string example: "M00" responseBody: $ref: "#/components/schemas/PaycodeHistory" PaycodeHistory: type: object properties: content: type: array items: $ref: "#/components/schemas/PaycodeDetails" pageable: $ref: "#/components/schemas/Pageable" last: type: boolean example: true totalPages: type: integer example: 1 totalElements: type: integer example: 1 sort: $ref: "#/components/schemas/Sort" first: type: boolean example: true numberOfElements: type: integer example: 1 size: type: integer example: 50 number: type: integer example: 0 empty: type: boolean example: false ErrorResponse: type: object properties: requestSuccessful: type: boolean description: Indicates if the request was successful. example: "false" responseCode: type: integer description: A response code. example: 99 responseMessage: type: string description: A message describing the response. example: "Failure reason is specified here" example: requestSuccessful: false responseCode: 99 responseMessage: "I failed because of this reason"