Integrating Monnify

To build safely and test edge cases, you will start your integration in our Test (Sandbox) environment. Ensure your codebase points to the correct Base URL:

1. Test Environment (Sandbox): https://sandbox.monnify.com
2. Live Environment (Production): https://api.monnify.com

Developer Note: One of the most common errors is using Sandbox API Keys while pointing your code to the Live Base URL. Always double-check your environment variables.

Dynamic virtual accounts and one-time invoices are designed for speed and security. Due to this, they come with a strict validity window.

But what happens if a customer makes payment after expiry?

Here is how Monnify handles late payments, and how you can resolve them without losing the sale.

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 an invalid transaction.

1. Not successful: The system will not recognize the payment as successful. It is treated as a failed or invalid transaction because the account number is no longer active.
2. No Value Delivered: Because the invoice is closed, your automated system will not confirm the order, and the customer will not receive their goods or services.
3. Funds are Reversed: In most cases, the banking network will instantly reject the transfer, and the funds will automatically reverse back to the customer's source account.

To actually complete the order, your customer has to generate a new invoice or payment link. Never ask the customer to try paying into the expired account again.

Best Practices to Prevent Expired Payments

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

1. Communicate the Urgency: Add a simple warning: "This account number expires in 30 minutes. Do not save for later use."
2. Upgrade to Reserved Accounts: If you have repeat customers who pay you frequently, stop using one-off dynamic accounts. Assign them a Reserved Account. Read more about Reserved Accounts.
3. Connect with Your Webhooks: Ensure your backend is actively listening for the EXPIRED webhook status. If you receive this status, your frontend should immediately hide the account number and prompt the user to "Generate a New Payment Method."

Your server shouldn't use up resources constantly asking Monnify if a transaction is completed. Instead, Monnify uses Webhooks to actively notify your server once a transaction is executed.

Supported Webhook Events

An “event” refers to the change in status of a request. Monnify will push real-time responses to your server for the following events:

1. Successful Payment
2. Payouts (Disbursements): Successful Disbursement, Failed Disbursement, Reversed Disbursement.
3. Refunds: Successful Refund, Failed Refund.
4. Settlements & Wallets: Settlement Completion (successful transfers to your bank account), Wallet Activity Notification (credits and debits to your Main or Sub-Wallets).
5. Mandate Status Change (e.g., from PENDING to ACTIVATED, FAILED, or CANCELLED).

Security when Dealing with Webhooks

When your server receives a webhook, you must verify that it actually came from Monnify before processing any value. You have to implement these two security layers:

1. Verify the Webhook Signature: Every valid webhook contains a signature header. You must hash the payload using your Client Secret Key and ensure it matches the signature sent in the header.
2. IP Whitelisting: To prevent bad actors from sending fake requests to your webhook URL, you must whitelist our exact IP address on your server. Monnify webhook notifications will only come from this IP: 35.242.133.146. Drop requests from any other origin.

Acknowledgement & Timeouts

When Monnify sends a webhook, we wait for your server to acknowledge that it was received.

1. You must acknowledge receipt of the webhook by returning a standard 200 OK HTTP status code.
2. Monnify webhook requests time out within a few seconds. If your server is doing heavy background processing (like generating PDF receipts or querying slow databases) before sending the 200 OK response, the Monnify server may time out.
3. If we do not get the expected response, we assume you did not receive the webhook and will retry after 5 minutes.

Best Practice: Receive the webhook, verify the authenticity, return the 200 OK response while delegating your heavy processing in the background.

Idempotency (Handling Duplicates)

Sometimes, network fluctuations happen so your system could receive duplicate webhooks for the exact same transaction. Here’s how to handle such:

1. When you receive a new webhook, always check to ensure that event has not been processed.
2. If you have already processed that event, disregard it. However, you must still return the expected status code so Monnify knows to stop retrying.

Pro-Tip for Developers: We heavily advise caching your processed notifications or maintaining a strict "Processed Transactions" log in your database to make these duplicate checks fast.

Not sure which integration method fits your team? Merchants and developers often choose their path based on technical capacity, customization needs, and desired speed to market.

Choose the path that best fits your current setup:

1. No-Code: Payment Links

1. Best for: Non-technical team, simple service businesses, or teams that want to start collecting payments immediately
2. How It Works: Maximum speed, zero coding required. You generate links directly from your dashboard and share them with customers via WhatsApp, other social media platforms, or email

2. Code: Mobile SDKs, Web SDKs, Plugins, Direct APIs

1. Best for: Technical teams who want flexibility, custom checkout UIs, or backend services.
2. How It Works: You build exactly what you want, and Monnify securely processes the funds in the background.