@monnify/mcp-server

Creates one or more Sub Accounts, used to automatically split payments across multiple bank accounts. WHEN TO USE: Before using incomeSplitConfig on monnify_initiate_payment, monnify_reserve_account, monnify_charge_card_token, or monnify_debit_mandate — a subAccountCode must already exist before it can receive a split. Also use for marketplace or multi-vendor setups where each vendor needs their own settlement account. PREREQUISITES: Sub Accounts are disabled by default — email integration-support@monnify.com to have this feature enabled on your account before use. SIDE EFFECTS: Creates one or more sub-account records tied to real bank accounts on Monnify. Each sub-account receives its own subAccountCode. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: subAccountCode (use this in incomeSplitConfig), accountNumber, accountName, bankCode, bankName, defaultSplitPercentage.

Lists all Sub Accounts created on your integration. WHEN TO USE: To look up an existing subAccountCode before configuring an incomeSplitConfig, or to audit which sub-accounts are currently set up. PREREQUISITES: Sub Accounts must be enabled on your account — email integration-support@monnify.com if this returns "not permitted". SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: subAccountCode (use this in incomeSplitConfig), accountNumber, accountName, bankCode, bankName, defaultSplitPercentage.

Updates the details of an existing Sub Account. WHEN TO USE: When a sub-account's linked bank account, email, or default split percentage changes. PREREQUISITES: The sub-account must already exist — obtain its subAccountCode from monnify_create_sub_accounts or monnify_get_sub_accounts. Sub Accounts must be enabled on your account — email integration-support@monnify.com if this returns "not permitted". SIDE EFFECTS: Overwrites the sub-account's stored bank details, email, and default split percentage. Existing incomeSplitConfig references to this subAccountCode are unaffected — only the destination account and split behaviour change going forward. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: subAccountCode, accountNumber, accountName, bankCode, bankName, defaultSplitPercentage.

Permanently deletes a Sub Account. WHEN TO USE: When a vendor or partner is offboarded and should no longer receive split payments. PREREQUISITES: The sub-account must exist. Any incomeSplitConfig still referencing this subAccountCode will fail on future transactions once deleted. SIDE EFFECTS: DESTRUCTIVE — permanently removes the sub-account. Cannot be undone. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: subAccountCode (confirms which sub-account was deleted).

Search and list transactions with optional filters. WHEN TO USE: For reporting, reconciliation, or finding a specific transaction when you have partial information (e.g. customer email or date range but not the full reference). PREREQUISITES: None. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: content (array of transactions), totalElements, totalPages, size, number (current page).

Returns all Nigerian banks supported by Monnify for payments and verification. WHEN TO USE: Before calling monnify_verify_bank_account, monnify_create_mandate, or monnify_process_refund to look up the correct 3-digit bank code for a given bank name. Also useful to present bank choices to users. PREREQUISITES: None. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: name (bank display name), code (3-digit bank code used in other API calls).

Verifies whether the provided name, date of birth, and mobile number match the BVN record, returning a single boolean result. WHEN TO USE: When you need a holistic match check against a BVN — all supplied details must match for bvnInformationMatch to be true. Useful for onboarding flows, KYC, and direct debit mandate validation. PREREQUISITES: None. Requires Monnify Identity Verification API access enabled on your account. Live environment only — costs ₦10 per successful request. SIDE EFFECTS: None. Read-only — does not store any data. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: bvn, name, dateOfBirth, mobileNo, bvnInformationMatch (boolean — true if all provided details match the BVN record).

Verifies that a customer's BVN details match the provided name, date of birth, and phone number. WHEN TO USE: For KYC (Know Your Customer) verification flows, onboarding with identity checks, or before creating a direct debit mandate where BVN validation is required. PREREQUISITES: None. Requires Monnify Identity Verification API access to be enabled on your account. Live environment only — not available in sandbox, so this call will fail with --env=sandbox regardless of BVN validity. SIDE EFFECTS: None. Read-only — does not store any data. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: bvn, nameMatch (boolean), mobileNoMatch (boolean), dateOfBirthMatch (boolean). A result of true means the provided value matches the BVN record.

Verifies a Nigerian bank account number and returns the account holder name. WHEN TO USE: Before initiating a refund, creating a direct debit mandate, or confirming account details provided by a user. Always verify account details before committing them to a mandate or refund. PREREQUISITES: None. Call monnify_get_supported_banks first to look up the correct bankCode. SIDE EFFECTS: None. Read-only — does not move any funds or create any records. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: accountName (name of account holder), accountNumber, bankCode, bankName.

Verifies a customer's National Identification Number (NIN) by matching it against the provided name and date of birth. WHEN TO USE: For strong identity verification flows where NIN is required, such as high-value onboarding, compliance checks, or regulatory KYC requirements that mandate NIN validation. PREREQUISITES: None. Requires Monnify Identity Verification API access enabled on your account. Live environment only — costs ₦60 per successful request. SIDE EFFECTS: None. Read-only — does not store any data. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: nin, firstName, lastName, dateOfBirth, gender, phoneNumber, ninInformationMatch (boolean — true if the provided name and date of birth match the NIN record).

Cancels an existing Direct Debit mandate, permanently stopping future debits. WHEN TO USE: When a customer requests cancellation of their subscription or recurring billing, or when a mandate needs to be revoked for compliance reasons. PREREQUISITES: The mandate must exist. The mandate can be in any status (PENDING_AUTHORIZATION, ACTIVATED). SIDE EFFECTS: IRREVERSIBLE — once cancelled, the mandate cannot be reactivated. The customer must create and authorise a new mandate to resume recurring billing. No refunds are triggered — only future scheduled debits are stopped. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: mandateReference, mandateStatus (will be CANCELLED).

Retrieves the current status of a Direct Debit mandate. WHEN TO USE: After creating a mandate to check if the customer has authorised it (mandateStatus = ACTIVATED), or before attempting a debit. You MUST confirm mandateStatus = ACTIVATED before calling monnify_debit_mandate. PREREQUISITES: A mandate must exist — call monnify_create_mandate first. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: mandateReference, mandateCode, mandateStatus (PENDING_AUTHORIZATION | ACTIVATED | CANCELLED | REJECTED), mandateAmount, mandateType, customerName, customerAccountNumber, startDate, endDate, authorizationLink.

Retrieves the status of a specific Direct Debit debit attempt. WHEN TO USE: After calling monnify_debit_mandate to check whether the debit succeeded, is still pending, or has failed. Debit operations are asynchronous — poll this endpoint to confirm the final status. PREREQUISITES: A debit attempt must exist — call monnify_debit_mandate first. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: paymentReference, debitStatus (PENDING | SUCCESS | FAILED), amount, debitDate.

Debits a customer's bank account using an activated Direct Debit mandate. WHEN TO USE: To collect a payment from a customer who has an ACTIVATED mandate. Call monnify_get_mandate_status first to confirm the mandate is ACTIVATED before attempting a debit. PREREQUISITES: monnify_get_mandate_status must return mandateStatus = ACTIVATED. Never attempt to debit a PENDING_AUTHORIZATION or CANCELLED mandate. SIDE EFFECTS: Initiates a real debit from the customer's bank account. This is an irreversible financial operation. Use a unique paymentReference per debit attempt — the same reference can be safely resubmitted to check status without double-charging. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: debitReference, mandateReference, debitStatus (PENDING | SUCCESS | FAILED), amount, debitDate.

Creates a Direct Debit mandate on a customer's bank account, enabling recurring payments. WHEN TO USE: When setting up recurring billing for a customer — subscriptions, instalments, or utility collection. This is always the first step in the Direct Debit lifecycle. PREREQUISITES: Direct Debit is disabled by default — email integration-support@monnify.com to have it enabled on your account before use. Also verify the customer's bank account with monnify_verify_bank_account first to confirm account details before committing them to a mandate. SIDE EFFECTS: Generates a mandateReference and a 30-day authorization link. The mandate status starts as PENDING_AUTHORIZATION — no debiting can occur until the customer clicks the link and authorises via their bank. Monnify automatically routes to TeamApt or NIBSS based on the customer's bank. MFA NOTE: Not applicable at this stage. Customer authorisation is handled externally via the authorizationLink — share this link with the customer via email, SMS, or in-app. KEY OUTPUT FIELDS: mandateReference, mandateCode, mandateStatus (PENDING_AUTHORIZATION), authorizationLink (valid 30 days), startDate, endDate.

Initiates a refund for a previously completed payment transaction. WHEN TO USE: To reverse a charge at a customer's request, after an order cancellation, or when a duplicate or suspicious charge is detected. Can be a full or partial refund. PREREQUISITES: The original transaction must have paymentStatus = PAID AND paymentMethod = ACCOUNT_TRANSFER — check both via monnify_get_transaction_status or monnify_get_transaction_details first. Transactions paid by CARD or USSD cannot be refunded through this API at all; the request will be rejected regardless of amount. Verify the destination account with monnify_verify_bank_account first. The Refund API is also disabled by default — a "not permitted" response means it needs to be enabled on your account by emailing integration-support@monnify.com, not that the request was malformed. SIDE EFFECTS: Initiates a real fund transfer back to the customer's bank account. This is a financial operation — confirm the transaction reference and refund amount carefully before proceeding. Using the same refundReference is safe (idempotent — will not double-refund). MFA NOTE: Not applicable. KEY OUTPUT FIELDS: refundReference, transactionReference, refundStatus (INITIATED | PENDING | REFUNDED | FAILED), refundAmount, refundReason, destinationAccountNumber, createdOn.

Charges a previously tokenized card using its card token, without requiring the customer to re-enter card details. WHEN TO USE: For recurring or repeat charges on a card the customer has already paid with. The card token is obtained from monnify_get_transaction_status after a previous successful card charge — look for the cardToken field in the response. PREREQUISITES: A card token from a prior successful charge. Store the cardToken alongside the customerEmail used in that original charge — both are required here. The token is tied to the merchant's contractCode and apiKey. SIDE EFFECTS: Initiates a real card charge immediately. This is a financial transaction — use a unique paymentReference per charge attempt. The same paymentReference can be safely resubmitted to deduplicate retries without double-charging. MFA NOTE: Token charges bypass OTP and 3DS — the customer authorised recurring charges when they first paid. Ensure you have the customer's explicit consent to store and reuse their card token. KEY OUTPUT FIELDS: transactionReference, paymentReference, amountPaid, totalPayable, settlementAmount, paidOn, paymentStatus (PAID | FAILED), paymentMethod, currency.

Initialises a bank transfer payment for an existing pending transaction and returns a one-time virtual account for the customer to transfer to. WHEN TO USE: After calling monnify_initiate_payment, use this tool when the customer wants to pay by direct bank transfer instead of card or USSD. Returns a virtual account number the customer must transfer the exact amount to. PREREQUISITES: A pending transaction must already exist — call monnify_initiate_payment first and pass its transactionReference here. The bankCode must be a valid Monnify-supported bank (call monnify_get_supported_banks to retrieve codes). SIDE EFFECTS: Creates a one-time virtual bank account tied to the transaction. The account expires at expiryDate. If the customer fails to transfer before expiry the transaction will remain pending. Calling this endpoint again with the same transactionReference and bankCode is safe (idempotent). MFA NOTE: No OTP is required from the customer on your end. The customer's own bank may require 2FA to complete the transfer. KEY OUTPUT FIELDS: accountNumber (tell the customer to transfer to this), accountName, bankName, bankCode, expiryDate (inform customer of deadline), amount (exact amount customer must send), fee, totalPayableFee, transactionReference.

Initiates 3D Secure (3DS) authorisation for a card transaction and returns the redirect URL for the customer to complete bank authentication. WHEN TO USE: Only when monnify_charge_card returns status THREE_DS_TRANSACTION_INITIATED. Call this tool with the transactionReference and apiKey from the charge response to obtain the 3DS redirect URL, then direct the customer to that URL to complete authentication on their bank's page. PREREQUISITES: monnify_charge_card must have been called and returned status THREE_DS_TRANSACTION_INITIATED. Both transactionReference and apiKey from that charge response are required. SIDE EFFECTS: Prepares the 3DS authentication session on Monnify's end. After the customer completes authentication on the bank's 3DS page, the bank will redirect them back to the merchant's configured redirectUrl. Call monnify_get_transaction_status afterwards to confirm the final payment outcome. MFA NOTE: 3DS authentication happens entirely on the customer's bank page — the bank issues and validates the OTP or biometric challenge. The merchant does not see the 3DS credential. KEY OUTPUT FIELDS: redirectUrl (send the customer to this URL to complete 3DS authentication), status, transactionReference, paymentReference, authorizedAmount.

Permanently deletes a reserved account. The virtual account numbers will no longer accept payments. WHEN TO USE: When a customer closes their account, a wallet is terminated, or a reserved account is no longer needed. This action is irreversible. PREREQUISITES: The reserved account must exist and be in an active state. SIDE EFFECTS: DESTRUCTIVE — permanently removes the reserved account. Any payments sent to the virtual account numbers after deallocation will be rejected or returned. Cannot be undone. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: accountReference, accountName, status (confirms deallocation).

Returns a paginated list of all transactions received on a reserved account. WHEN TO USE: To review payment history for a customer's dedicated virtual account — e.g. checking what has been paid into a wallet, reconciling a subscription account, or investigating a missing payment. PREREQUISITES: The reserved account must exist. Use monnify_get_reserved_account to confirm it is active. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: transactionReference, paymentReference, amountPaid, totalPayable, paymentStatus, paidOn, paymentMethod, currencyCode.

Completes a card transaction that is awaiting OTP (one-time password) authorisation. WHEN TO USE: Only when monnify_charge_card returns status OTP_TRANSACTION_INITIATED. Collect the OTP the customer receives via SMS from their bank and pass it here to finalise the payment. PREREQUISITES: monnify_charge_card must have been called and returned status OTP_TRANSACTION_INITIATED. The customer must have received and provided their bank OTP. SIDE EFFECTS: Submits the OTP to the card network for verification. A SUCCESS status means the payment is complete. A FAILED status means the OTP was incorrect or expired — the customer must retry the charge. MFA NOTE: The OTP is issued by the customer's bank, not Monnify. It is typically 6 digits and valid for a short window (1–5 minutes). Never store or log OTP values. KEY OUTPUT FIELDS: status (SUCCESS or FAILED), transactionReference, paymentReference, authorizedAmount, message.

Returns the details of an existing reserved account including its virtual account numbers. WHEN TO USE: To look up a reserved account by its reference — e.g. to show a customer their dedicated payment account, confirm the account is still active, or retrieve virtual account numbers for display. PREREQUISITES: The reserved account must have been created with monnify_reserve_account. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: accountName, accountReference, status, accounts (virtual account numbers per bank), customerName, customerEmail, createdOn.

Reserves a dedicated virtual bank account for a customer to pay into at any time. WHEN TO USE: For persistent payment collection — wallets, top-up accounts, or business collection accounts. Unlike one-time checkouts, reserved accounts allow customers to pay anytime by bank transfer. PREREQUISITES: Reserved Accounts feature must be enabled on your Monnify account. Contact Monnify support if unavailable. SIDE EFFECTS: Creates a persistent reserved account on Monnify's banking partners. The account persists until explicitly deleted. Using the same accountReference is safe (idempotent). MFA NOTE: Not applicable. KEY OUTPUT FIELDS: accountReference, accountName, accounts (array of virtual account numbers per bank), reservationReference, status, createdOn.

Creates a payment invoice and returns a URL the customer can use to pay. WHEN TO USE: When you need to send a customer a formal invoice with a fixed amount and expiry date. Suitable for B2B billing, service charges, or any scenario where you want a shareable payment link with a deadline. PREREQUISITES: None. A Monnify contract code is required. SIDE EFFECTS: Creates an invoice record on Monnify. The invoice remains active until the expiryDate or until paid. Using the same invoiceReference is safe (idempotent). MFA NOTE: Not applicable at the invoice creation stage. KEY OUTPUT FIELDS: invoiceReference, invoiceStatus, checkoutUrl (share with customer), invoiceUrl, offlinePaymentCode, expiryDate, createdOn.

Returns a paginated list of all transactions on your integration, with optional filters. WHEN TO USE: For reporting, reconciliation, or finding transactions when you have partial information (e.g. date range, customer email, amount range, or status) rather than a specific reference. PREREQUISITES: None. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: content (array of transactions — each with transactionReference, paymentReference, amountPaid, totalPayable, paymentStatus, paidOn, paymentMethod, currencyCode), totalElements, totalPages, size, number (current page).

Retrieves the full status and details of a transaction directly by its Monnify transaction reference. WHEN TO USE: When you have the Monnify transactionReference and need to confirm the payment outcome. Use monnify_get_transaction_status if you only have your own paymentReference. PREREQUISITES: A valid Monnify transactionReference from a prior transaction. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: transactionReference, paymentReference, amountPaid, totalPayable, settledAmount, paidOn, paymentStatus (PAID | PENDING | CANCELLED | FAILED), currencyCode, paymentMethod.

Charges a customer's card against an existing pending transaction using card details collected by the merchant. WHEN TO USE: After calling monnify_initiate_payment, use this tool to directly charge a card when you have collected card details on your own payment form (not via the checkoutUrl). The transaction must already exist and be in PENDING status. PREREQUISITES: A pending transaction must already exist — call monnify_initiate_payment first and pass its transactionReference here. Card details and browser deviceInformation must be collected from the customer's browser. Never log or store raw card numbers, CVVs, or PINs. SIDE EFFECTS: Attempts to charge the card immediately. The response status determines the next step: - SUCCESS → payment is complete, no further action needed - OTP_AUTHORIZATION_REQUIRED → card requires OTP; otpData.message tells the customer where to get it. Collect the OTP and call monnify_authorise_card_otp - BANK_AUTHORIZATION_REQUIRED → card requires 3DS; redirect customer to secure3dData.redirectUrl, then call monnify_authorise_card_3ds - FAILED → charge failed; surface the message to the customer MFA NOTE: Nigerian-issued cards require card.pin and may also trigger OTP or 3DS. Always handle all three non-SUCCESS statuses. KEY OUTPUT FIELDS: status (determines next step), transactionReference, paymentReference, authorizedAmount, message, otpData (for OTP flow — contains id and message), secure3dData (for 3DS flow — contains id and redirectUrl).

Initiates a payment transaction and returns a checkout URL for the customer. WHEN TO USE: When a customer needs to make a one-time payment. Returns a checkoutUrl — redirect the customer to this URL to complete payment via card, bank transfer, USSD, or other methods. PREREQUISITES: None. A Monnify contract code is required (from Dashboard → Settings → Contract Codes). SIDE EFFECTS: Creates a pending transaction on Monnify. Does not charge the customer — the customer must visit checkoutUrl and complete payment. Providing the same paymentReference again is safe (idempotent — returns the existing transaction). MFA NOTE: Not applicable at this stage. The customer may encounter card 3DS (OTP) authentication on the checkout page. KEY OUTPUT FIELDS: transactionReference (Monnify's ref), paymentReference (your ref), checkoutUrl (send this to the customer), enabledPaymentMethod.

Queries the status of a payment transaction. WHEN TO USE: After initiating a payment to check if it has been completed (paymentStatus = PAID), or when a customer reports a payment issue. Poll this endpoint after the customer's redirect back from checkout. PREREQUISITES: A transaction must exist — call monnify_initiate_payment first, or have a known paymentReference. SIDE EFFECTS: None. Read-only operation. MFA NOTE: Not applicable. KEY OUTPUT FIELDS: transactionReference, paymentReference, amountPaid, totalPayable, paymentStatus (PAID | PENDING | CANCELLED | FAILED), paidOn, currencyCode, paymentMethod.