The verdict in three sentences
In Uganda, a mobile money payment that "fails" usually hasn't failed: the USSD prompt expired before the customer entered their PIN. On weak networks this hits 15 to 20% of attempts — sales lost even though the money sometimes moved. The fix: a clear state machine, a paced status polling loop, and a safe customer retry that never re-triggers an existing charge, for +8 to +12% completion.
The state machine that saves payments
The classic trap: showing "failed" the moment the USSD prompt doesn't answer in time, when the operator may confirm 30 seconds later. Every transaction must be modelled as a state, never as a success/failure boolean.
| State | Trigger | Next action |
|---|---|---|
| pending | USSD prompt sent | Wait for callback or start polling |
| polling | No callback within 20 s | Query status every 5 s |
| confirmed | Status SUCCESS | Validate the order |
| reconcile | Timeout exceeded, ambiguous status | Check operator side before any retry |
| failed | Confirmed FAILED status | Allow a clean new attempt |
The customer only sees a clear waiting screen ("Approve on your phone…"), and the retry is offered only after the reconcile state, which guarantees no charge has already gone through.
Thresholds and cadence: the numbers that matter
2026 order of magnitude for an Airtel/MTN checkout in Kampala on 3G, recommended settings and observed gains.
| Parameter | Recommended setting | Effect |
|---|---|---|
| Delay before polling | 20 seconds | Gives the customer time to enter PIN |
| Polling cadence | Every 5 s, max 24 attempts | Confirms without hammering the API |
| Total timeout | 2 minutes | Beyond this, move to reconcile |
| Initial expiry rate | 15 to 20% | Target: recover most of them |
| Recovered payments | +8 to +12% | Otherwise lost sales |
| Average confirmation latency | 8 to 25 s | Waiting screen is essential |
The secret isn't speeding up the operator — it's not concluding failure too early and reconciling before offering a fresh attempt.
Mini case study
Nakato, who runs an online shop in Kampala, receives 1,500 Airtel/MTN payment attempts a month. Before, 18% expired (270 attempts) and she counted them as lost — on an average basket of UGX 45,000, roughly UGX 12,150,000 of orders shown as "failed".
After deploying the state machine and polling, she recovers 10 points of completion: 150 previously lost payments now confirm, i.e. UGX 6,750,000 recovered per month, with not a single double charge thanks to the reconcile state.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
Become a Kolonell referral partner
Do you meet Ugandan online sellers complaining that Airtel or MTN payments "crash"? It's usually just a timeout problem. Introduce them to Kolonell through our referral partner program: 15% + 5% recurring on a showcase site, 12% on e-commerce, 10% on a marketplace, 8% on institutional. You refer, we deliver, you get paid.
FAQ
Why not just make the timeout longer?
A too-long timeout traps the customer on a waiting screen and doesn't improve the real rate. The right answer is status polling, which confirms as soon as the operator responds, often within 8 to 25 seconds.
Won't the retry cause a double charge?
No, because a new attempt is offered only after the reconcile state, which checks operator-side that no charge went through. That is the double-charge guarantee.
How many payments can really be recovered?
As an order of magnitude, +8 to +12% completion on weak networks, which on volumes of several hundred attempts means millions of UGX per month.
Does it also work for other wallets?
Yes, the state machine is agnostic: same principles for Airtel, MTN or others, only the polling thresholds adjust.
Let's talk about your project. We turn your Airtel and MTN timeouts into confirmed payments, with no double charge. 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.
