Integrating Monnify

Integrating Monnify is straightforward, but jumping straight into code without a clear plan can cause delayed launches.

To help your team begin production on time, we've broken the pre-integration process into three focused steps:

1. Step 1: Account Setup
2. Step 2: Plan With the Documentation
3. Step 3: Incorporate the Code Integration Guidelines

Step 1: Account Setup

Before you begin coding, you need a properly configured Monnify account.

1. Complete Your KYC Verification: Sign up on Monnify and submit your business details. Not sure what documents you need? See the KYC Checklist.
2. Retrieve Your Credentials: For API integrations, you'll need your unique identifiers. On your Monnify dashboard menu, navigate to Developers to copy your API Key, Secret Key, and Contract Code.

Step 2: Plan With the Documentation

Don't just build, build the right thing for your business.

1. Map Your Payment Use Case: Are you assigning virtual accounts to returning customers (reserved accounts)? Building a checkout page? Automating bulk payouts to vendors? Defining your use case upfront helps you select the right integration method and avoid rework later.
2. Read What’s relevant to You: You don’t need to read the entire API Docs, but you must read the guide for the specific feature you’re implementing. Security requirements vary by feature; for example, our Disbursement (Payout) API requires OTPs to protect your funds.
3. Understand Your Environments: Always begin in Test Mode (Sandbox). Understand the key differences between the sandbox and live (production) environments before you begin processing real transactions.

Step 3: Incorporate the Code Integration Guidelines

When integrating Monnify, your engineering team should integrate the following guidelines to protect your revenue:

1. Secure Every Request: All calls to the Monnify API must be authenticated using an OAuth 2.0 Bearer Token.
2. Use Unique Payment References: To initialize a payment, your backend will call the Initialize Transaction endpoint, then pass the amount, customer details, and a paymentReference. Your paymentReference must be strictly unique for every payment attempt. Reusing the same reference is a common cause of failed API calls.
3. Leverage Webhooks: Most payment methods are asynchronous (confirmation doesn't happen in real time), so do not fulfil an order based solely on a client-side success message. Instead, configure a Webhook URL so Monnify can notify your server the moment a payment is confirmed. Always verify the payment status on the server.
4. Test Beyond the “Happy Path”: The happy path (a customer pays, everything works) is only one scenario. Before going live, test for real-world edge cases such as expired accounts, partial payments, duplicate webhooks, and network delays. Handling these gracefully in Test mode (Sandbox) mode means your system is ready when they happen in Live mode (Production).

Ready to start building?

With your foundation in place, choose your next step:

Zero engineering required. Start collecting money in minutes.

The No-Code method is built entirely within your Monnify Dashboard. You get to generate secure, shareable links and send them directly to your customers to close sales faster.

Strategic Features to Boost Your Business

1. Sell Anywhere: Paste your Payment Link into WhatsApp chats, Instagram DMs, SMS, or email newsletters. When the customer clicks it, they are taken to a secure Monnify checkout page hosted by us.
2. Flexible Pricing Controls: Selling products with a set price? Create a Fixed Amount link. Running a fundraiser or accepting installments? Create an Open Amount link where the customer types in how much they are paying.
3. Perfect Reconciliation: Know who paid. When creating a link, you can mandate that the customer enters their Name, Phone Number, or a specific Order ID before they can pay. This ensures your dashboard reconciliation is always 100% accurate.

Ready to Start?

Skip the code and start making money right now:

Build your own native experience.

If your platform requires flexibility, our options for integrating give you the keys to the engine. You get to offer your customers access to pay via Bank Transfer, Cards, USSD, and Phone Number.

Choose Your Code Integration Stack

Choose the tool that fits your platform:

Need to reset your API keys? You can reset your API Key and Secret key by following these steps:

To use our APIs, you must provide us with your server’s exact IP address so we can whitelist it on our end. Our APIs are seamless to integrate, but we enforce this security so that you alone can authorize critical features.

Why is IP Whitelisting Mandatory?

API keys can get stolen, exposed in public repositories or accidentally leak. But with IP Whitelisting, stolen keys are useless to a hacker.

If a bad actor gets your keys and tries to initiate a transfer from their own computer, Monnify will reject the request because it is not originating from your pre-approved server. It is your ultimate fail-safe.

How to Whitelist Your Server IP

Send an email from the email address linked to your Monnify account:

By default, Monnify requires an OTP (One-Time Password) for every payout (disbursement) attempt. This provides an excellent layer of manual security for businesses doing occasional transfers.

However, if your team is building an automated system like a payroll processor or a bulk vendor disbursement flow, requiring a manual OTP for every transaction will break your automation.

The Fix: Send an email to our Integration Support team requesting that we waive OTPs for your account.

Email Template for Requesting an OTP Waiver

Note: For security reasons, an OTP waiver must be requested directly by the business owner or the primary technical admin.

Using the template below, send an email from the email address linked to your Monnify account:

Dynamic virtual accounts and one-time invoices are built for speed and security, and that comes with a strict validity window. When a customer misses that window and pays after expiry, it can feel like a lost sale.

Here is how Monnify handles late payments, and how to resolve them cleanly.

What Happens to the Transaction?

When a customer pays after the expiry of a Monnify virtual account or dynamic invoice, the payment is treated as invalid. Here's what that means:

1. The payment is not recognised as successful. Since the account number is no longer active, the system treats the transaction as failed.
2. No value is delivered. Because the invoice is already closed, your system will not fulfil the order; the customer will not receive their goods or services.
3. The funds are reversed. In most cases, the banking network rejects the transfer outright and the funds are automatically returned to the customer's source account.

To complete the order, the customer needs to generate a new invoice or payment link. Do not ask them to retry the expired account, it will not work.

Best Practices to Prevent Expired Payments

Stop late payments before they happen by optimizing your checkout flow:

Every payment that flows through Monnify has identifiers, and knowing what the identifiers mean can save you from certain reconciliation headaches. This guide covers the identifiers and status field your team may encounter when collecting payments.

The Two Reference IDs

1. paymentReference: This is the internal tracking number that your system generates for each transaction. It must be strictly unique for every payment attempt. Reusing a reference is one of the most common causes of failed API calls.
2. transactionReference: This is generated by Monnify. The moment a transaction enters our system, we assign it this identifier and return it to you in our API response. Use it when querying or referencing a transaction on our end.

Payment Status

Payment Status is the field that reflects the outcome of a collection attempt. It is visible on your Monnify Dashboard and is the primary tool your finance and operations teams will use for day-to-day reconciliation.

A status of PAID is the confirmation that a customer has successfully completed their payment.

The full list of valid Payment Statuses:

PAID · OVERPAID · PARTIALLY_PAID · PENDING · UNDERPAID, REFUNDED, ABANDONED · CANCELLED · FAILED · REVERSED · EXPIRED

Developer Note: Use the payment status field in the JSON object to drive your application logic, updating a database record, releasing a product, or prompting a retry.