The verdict in three sentences
Airtel Money is a key secondary operator in Uganda, with a collection fee around 1 % plus a UGX 0 entry tier (2026 order of magnitude). Its API integration rests on four pillars: authentication, asynchronous callback, timeout handling and idempotency. Wired well, it reaches a target success rate of 98.5 %; wired badly, it produces double debits and cascading refunds.
The API parameters to master
| Parameter | Value / range | Role |
|---|---|---|
| Collection fee | ~1 % + UGX 0 tier | Merchant cost |
| Callback latency | 2 to 6 s | Asynchronous confirmation |
| Timeout retry window | 90 s | Replay the request |
| Sandbox setup | ~1 to 2 days | Testing before prod |
| Idempotency key | UUID per order | Prevent double debits |
| Target success rate | 98.5 % | Integration KPI |
The golden rule: one idempotency key per order. If the callback is slow and the customer retries, the same key blocks a second debit.
Airtel vs Moov: two secondary operators compared
| Criterion | Airtel Money (Uganda) | Moov Money (Benin/Togo/Niger) |
|---|---|---|
| Collection fee | 1 % + UGX 0 tier | ~1.2 % |
| Callback latency | 2 to 6 s | 3 to 8 s |
| Sandbox | ~1 to 2 days | ~2 days |
| Idempotency | Recommended | Recommended |
| Coverage | East Africa | 3 WAEMU countries |
Both demand the same discipline: never confirm an order on the immediate HTTP response, only on the signed callback.
Mini case study
Mukasa, who runs an airtime shop in Kampala, processes 900 Airtel payments/month. Without idempotency, a slow callback caused 1.5 % double debits, about 14 refunds/month to handle manually (30 min each = 7 h). After adding an idempotency key and a 90 s retry window, double debits fell to 0.1 %, freeing nearly 7 hours/month and stabilising cash at a 98.6 % success rate.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
FAQ
Why not confirm on the immediate HTTP response?
Because Airtel confirms payment asynchronously via a 2 to 6 second callback. Confirming on the initial response risks orders marked paid then rejected.
What is the idempotency key for?
It guarantees that a replayed order (customer retry, flaky network) produces a single debit. It is the number-one protection against double payments.
How long for a working sandbox?
Budget about 1 to 2 days for Airtel: obtaining keys, testing the callback and simulating a timeout. Never go live without testing the timeout scenario.
What if the callback never arrives?
Trigger an active status check (polling) within the 90 s window, then mark the order "to verify" rather than "failed" to avoid cancelling a payment that actually went through.
Let's talk about your project. We integrate Airtel Money and Moov Money with idempotency and retry for a 98.5 % success checkout. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionate about digital and entrepreneurship in Africa, Mohamed has been helping Sénégalese businesses with their digital transformation since 2020. Founder of Kolonell, he believes every SME deserves a professional and accessible online présence.
