Payment integration in Nigeria: a practical guide for businesses

Adding "pay online" to a website or app looks simple: pick a payment gateway, drop in their checkout, done. The checkout is rarely the problem. The problems start afterwards, when a customer has been debited and your system doesn't know it, or knows it twice.

This guide explains how payment integration works in Nigeria and how to build one that doesn't lose money.

The main pieces

Payment providers and gateways. Companies such as Flutterwave give you a checkout for cards, bank transfers and other methods, plus APIs to confirm transactions.

NIBSS. The Nigeria Inter-Bank Settlement System sits behind interbank transfers in Nigeria. Many transfer-based payment flows ultimately move money over NIBSS rails.

Your system. Your website, app, ERP or school management system: the place that needs to know "invoice 1042 has been paid".

Payment integration is the work of connecting these reliably.

The payment lifecycle

Every online payment goes through roughly the same steps:

1. Initiate. Your system creates a payment for a specific invoice, customer or student, with a unique reference.
2. Pay. The customer pays through the provider's checkout, by transfer, card or QR code.
3. Confirm. The provider knows the payment succeeded.
4. Notify. Your system is told about it.
5. Record. Your system marks the invoice paid, exactly once.
6. Settle and reconcile. Money reaches your account, and your records match your bank statement.

Most payment bugs live in steps 4 and 5.

Why payments go "missing"

The classic mistake is trusting the browser. The customer pays, the provider redirects them back to your site, and your site marks the order paid. But customers close tabs, networks drop, and phones die mid-redirect. The money is gone from their account; your system never heard about it.

The fix is to rely on a server-to-server notification, usually a webhook: the provider (or a payment layer in the middle) calls an endpoint on your server when a payment is confirmed. But webhooks have failure modes too:

• Your server is down or slow when the webhook arrives.
• The webhook arrives twice, and you credit the customer twice.
• The webhook is spoofed, if you accept notifications without checking them.

What a reliable integration does

A payment integration you can trust has a few non-negotiable properties.

Verify every payment with the provider

Don't take a notification at face value. Before crediting anything, confirm the transaction status and amount with the provider's API using your own credentials.

Retry deliveries until they are acknowledged

If your system doesn't respond with success, the notification must be sent again, with sensible gaps between attempts, until it is acknowledged or a person is alerted.

Process each payment exactly once

Use the unique transaction reference as a key. If the same payment arrives twice, the second one should be recognised and ignored, not credited again. This property is called idempotency, and it is what makes retries safe.

Log every attempt

Keep a record of every delivery attempt and its result. When a customer says "I paid", you can see exactly what happened and when, instead of guessing.

Reconcile automatically

Match payments to invoices by reference, and match settlements to your bank statement. Anything that doesn't match should be flagged, not left for someone to discover at month end.

QR payments

QR codes remove typing from payments. The QR carries the reference and amount, so the customer can't pay the wrong invoice or the wrong amount. They work especially well on printed documents such as school bills, report sheets and invoices.

Choosing between one provider and several

Integrating a single gateway is quickest. Integrating through a payment layer that supports several providers adds flexibility: you are not stuck if one provider has an outage or changes its pricing, and you can offer the methods your customers prefer.

How we approach it

We built Penney, our payment platform, with these failure modes in mind: it collects through NIBSS, Flutterwave and Mizan, confirms each transaction, and delivers it to the receiving system by webhook, retrying until acknowledged, with every attempt logged. It runs school fees collection for schools on CollegeDreams, where a missing payment means a parent being told they owe money they have already paid.

If you need payments wired into your product, see our payment integration services or talk to us.