Online payments
How online top-ups work, what the states mean and how operators test them.
Customers can top up online with Airtel Money, TNM Mpamba or card. The money goes through the online payment gateway chosen by the operator. Customers pick a method, not a gateway.
How a payment works
- The customer picks an amount and a method (mobile money or card).
- The account service creates the payment with the gateway and sends the customer to pay.
- The gateway tells our server about the payment. The customer also comes back to our site.
- Our server asks the gateway directly if the payment succeeded. Only then is the balance credited, once.
The return page in the browser is never trusted on its own.
Payment states
| State | Meaning |
|---|---|
pending | Started, not confirmed yet. Checked again with the gateway on a schedule. |
success | The gateway confirmed it with the right reference, amount and currency. Credited once. |
failed | The gateway says it failed or was cancelled. Nothing credited. |
review | The gateway says paid, but the amount, currency or reference does not match. Never credited automatically. An admin must look. See Stuck top-ups. |
Endpoints (for developers)
| Method | Path on auth.smsyanu.com | What it does |
|---|---|---|
GET | /payments/methods | Which methods are on, their limits and the currency. |
POST | /payments/initiate | Start a payment. Fields method (mobile_money or card), amount, currency, and mobile for mobile money. |
GET | /payments/verify/{reference} | Our server checks the payment with the gateway. |
For operators
The gateway keys and switches live in the account service env file on the server, never in git. Their names are in yanu-infra/env/yanu-auth.env.example. PAYMENTS_ENABLED is the master switch for all payments.
A gateway shows as a payment method only when it is switched on and its secret key is set. Admins pick which gateway serves new payments. A payment is always verified with the gateway that took it, whatever is selected later.
If the webhook secret is empty, every webhook is refused. Payments still settle, because a background job asks the gateway about each unfinished payment every few minutes.
Test first, then go live
Put the gateway's test keys in the env file and switch payments on.
Restart the account service. Check that the methods appear in Top up.
Make test payments with each method. Check that the balance goes up once, and that a cancelled payment adds nothing.
Swap in the live keys. Restart. Make one small real payment and check it.