9 min read
Mobile Money Payments: How the Checkout Flow Works
Key takeaways
- A mobile money checkout runs in seven steps: order confirmation, API call, STK push or USSD prompt, PIN entry, synchronous response, asynchronous callback, and fulfilment, usually in under a minute.
- Treat the gateway callback as the only source of truth for a paid order, verify its authenticity, and poll the transaction status endpoint if no callback arrives within your timeout window.
- M-Pesa is the primary rail in Kenya, MTN MoMo covers Uganda, Ghana, and Cameroon, and Airtel Money is a secondary rail across Uganda, Tanzania, and Kenya, each requiring a separate integration.
- Mobile money has no chargeback mechanism; refunds are manual pushes from your merchant wallet, so publish a clear refund policy.
- Aggregators are usually the fastest path for solo developers, wrapping MTN, Airtel, and sometimes cards behind one API at the cost of a per-transaction margin.
Mobile money payments let a customer pay by confirming a USSD prompt on their phone, and for your checkout the whole flow is: trigger an STK push, handle the callback, settle to your account, reconcile. This guide traces each step, including the failure modes, so you can decide whether to add MTN or Airtel to your store.
What are mobile money payments and how do they differ from mobile wallets?
Mobile money payments move money between accounts held with a mobile carrier, not a bank. You deposit cash with an agent, the carrier holds an equivalent e-money balance against your phone number, and you pay by confirming a prompt on your handset. M-Pesa, MTN MoMo, and Airtel Money all work this way. That is the rail we built Omeganodes pricing around, so you can pay for EU hosting from Nairobi without a USD card (https://omeganodes.com/pricing).
E-money vs card networks
A card wallet like Apple Pay rides Visa or Mastercard rails and needs a bank-issued card underneath. An app-based wallet like PayPal sits on top of cards or bank transfers. Mobile money needs neither: the carrier issues the account, and a merchant pulls the payment by triggering a push to your phone. Safaricom's Daraja API documentation describes this as the STK push flow, where the customer enters their PIN and the merchant receives a callback with the result.
Who regulates the float
The money sitting in carrier wallets is e-money, and the float is held separately from the carrier's operating cash. Central banks license and supervise these schemes, which is why KYC rules apply at agents and why transaction limits exist. For you as a merchant, that means settlement lands from a regulated entity, not from a card acquirer.
How does a mobile money checkout actually work step by step?
A mobile money checkout runs in seven steps: the customer confirms the order, your server calls the payment API, the customer's handset receives an STK push or USSD prompt, they enter their PIN, the gateway returns a synchronous response, your server receives an asynchronous callback confirming the funds, and you fulfil the order. The whole thing usually completes in under a minute.
The initiate-payment API call
Your backend sends the gateway the customer's phone number, the amount, a merchant order reference, and a callback URL. The reference matters: it is how you match the eventual callback to the right order, so generate it yourself and store it before the API call goes out. The gateway responds immediately with a status like "pending" or "sent to customer". That response only means the prompt was dispatched, not that money moved.
What the customer sees on the handset
The customer's phone lights up with an STK push showing the amount and your business name, and they type their mobile money PIN to approve. On networks or handsets where STK push is unavailable, the flow falls back to a USSD menu the customer dials manually. If they mistype the PIN, cancel, or the phone is off, the prompt times out and the payment fails. Build for that: show a clear retry button and let them pick a different number, because a failed prompt is routine, not an error state.
The callback your server must handle
The real confirmation arrives later, as an HTTP POST from the gateway to the callback URL you registered. It carries the transaction ID, the amount, the original merchant reference, and a result code. Treat this callback as the only source of truth: mark the order paid, store the transaction ID for reconciliation, and return a 200 quickly so the gateway does not retry. Verify the callback's authenticity (most gateways sign requests or expect an IP allowlist), because anyone who can POST to your endpoint could otherwise fake a paid order. If no callback arrives within your timeout window, poll the transaction status endpoint rather than assuming failure. This is the same push-to-deploy simplicity developers expect from a PaaS like Omeganodes: the plumbing should disappear once configured, so you can ship a checkout and move on to the side project it belongs to.
Which mobile money schemes matter for e-commerce and where?
Three schemes cover most East African checkouts, and each is strongest in its home market.
M-Pesa
Safaricom's M-Pesa dominates Kenya and is the default expectation for Kenyan buyers. If your store or SaaS targets Kenya, M-Pesa is not optional; it is the checkout.
MTN MoMo
MTN MoMo is the scheme to integrate for Uganda, Ghana, and Cameroon. Its MoMo Open API documentation covers the endpoints you need: payment initiation, callback handling for confirmation, and refunds. One API, three markets.
Airtel Money
Airtel Money is the second rail in Uganda and Tanzania and competes with M-Pesa in Kenya. Supporting it alongside the primary scheme catches customers whose wallet does not match your first choice.
| Scheme | Home markets | Role in checkout |
|---|---|---|
| M-Pesa | Kenya | Primary |
| MTN MoMo | Uganda, Ghana, Cameroon | Primary |
| Airtel Money | Uganda, Tanzania, Kenya | Secondary |
Cross-border interoperability between wallets is improving through regional initiatives, but treat each scheme as a separate integration for now. We handle this the same way at Omeganodes: pay for hosting with MTN or Airtel, and the routing is our problem, not yours. Our data processing terms at https://omeganodes.com/dpa apply to whatever payment rail you use.
How do settlement, fees, and refunds work with mobile money?
Settlement timelines
Most mobile money schemes settle T+0 or T+1. In practice, funds from a customer's payment usually land in your merchant wallet within seconds to a few minutes, with the aggregator's settlement sweep to your bank account (if you use one) running daily. If you hold the merchant wallet directly, the money is spendable almost immediately, which is why a solo developer paying for hosting with MTN Mobile Money sees their balance reflect a sale the moment the customer confirms the prompt.
Fee structure
Fees are per transaction, not monthly, and they scale with the amount rather than the count. Expect a percentage fee plus possible fixed and FX components depending on the scheme and whether the payer crosses borders. Two things matter for your margin math: check whether fees are deducted from the merchant side (they usually are), and confirm the minimum transaction floor, since small side-project prices can lose a larger share to fixed fees than a percentage alone suggests.
Refunds without chargebacks
There is no chargeback mechanism in mobile money. A refund is a manual B2C push from your merchant wallet back to the customer's number, initiated through your aggregator or scheme dashboard. That cuts fraud risk from disputed payments dramatically, but it also means refunds are your decision, not the customer's bank's. Publish your refund policy clearly, as we do on our trust page, so the manual step never becomes an argument.
What integration options exist: direct API, aggregator, or PSP?
Direct carrier APIs
Safaricom's Daraja API lets you initiate STK pushes and receive B2C payouts directly, with no middleman taking a cut per transaction. The trade-off: you maintain separate integrations per carrier, handle each carrier's callback formats, and manage your own reconciliation. Airtel Money publishes its own merchant API documentation covering collections and disbursements (Airtel Money merchant API docs), so a direct route in East Africa realistically means building against both Safaricom and Airtel separately.
Aggregators
Aggregators wrap MTN, Airtel, and sometimes cards behind one API, so you integrate once and accept across carriers. You pay a per-transaction margin for that convenience, and settlement times depend on the aggregator's payout schedule rather than the carrier's. For a solo developer shipping a side project, this is usually the fastest path from git push to a working checkout.
Full PSPs
Payment service providers add hosted checkout pages, refunds, dispute handling, and multi-country coverage on top of aggregation. Setup is the slowest and fees are the highest, but you inherit compliance and reconciliation work you would otherwise own.
If your product is a SaaS app billed monthly, weigh this against what your platform already handles: Omeganodes, for example, accepts MTN and Airtel mobile money directly for hosting, so you may not need to build payments yourself just to cover infrastructure costs. Full details are in our data processing addendum.
What are the common failure modes and how do you reduce them?
Timeouts and cancellations
The STK push expires fast, usually under a minute, and customers who switch apps to check their balance often miss it. Send the prompt at checkout, not after a form, and show a countdown with a one-tap resend. Treat a cancelled prompt as a retryable state, not a failed payment, so the customer can try again without re-entering cart details.
Missed or duplicate callbacks
Networks retry webhooks, and your server can miss one entirely during downtime. Log every callback body before processing, respond with 200 immediately, and process asynchronously. Run a reconciliation job that polls the provider's transaction status endpoint for pending payments older than a few minutes, so a missed callback never means a lost sale. Regulators require e-money issuers to maintain records and settlement timelines that make this reconciliation possible (Central Bank of Kenya, e-money issuer regulations).
Idempotency keys
Duplicate callbacks will arrive. Key each transaction on the provider's unique transaction ID and check it against a stored record before applying anything. If the ID exists, return 200 and do nothing. The same key should gate your own retries, so a webhook resend and your polling job can never double-credit a wallet or double-fulfil an order.
How do you decide if mobile money is worth adding to your checkout?
Use three filters: where your customers pay from, how big a typical order is, and how often you refund.
If most buyers are in Kenya, Uganda, or Tanzania and pay with MTN or Airtel Money, card-only checkout quietly deletes revenue. If tickets are small and frequent, per-transaction aggregator fees matter less than a failed card decline. If refunds are rare, callback and reconciliation work stays manageable for one person.
The mirror image applies to what you buy, not just what you sell. Developers without USD-billing cards face the same wall paying for hosting, which is why Omeganodes accepts mobile money for its PaaS plans (https://omeganodes.com/pricing).
If your buyers can pay you the way they already pay for airtime, add it.
FAQ
Can I accept M-Pesa payments on my website without a registered business?
Practically, no. Direct access to Safaricom's Daraja API requires a registered merchant or developer account, and aggregators that wrap M-Pesa also onboard merchants with business documentation and KYC. If you are a solo developer without a registered entity, an aggregator is your most realistic path, but expect to provide at least some formal identity and business details during onboarding.
How long does an STK push take to expire if the customer doesn't respond?
Usually under a minute. The prompt disappears quickly, and customers who switch apps to check their balance often miss it entirely. Build for this by sending the prompt at checkout rather than after a form, showing a countdown, and offering one-tap resend. Treat an expired or cancelled prompt as a retryable state, not a failed payment.
Do mobile money payments work for customers without a smartphone?
Yes. The original rail is USSD, which works on any handset that can dial a menu. STK push is the modern, smoother flow, but where it is unavailable, the checkout falls back to a USSD menu the customer dials manually before entering their PIN. Your integration does not change; the gateway handles which prompt type reaches the customer's handset.
What happens if the callback never arrives but the customer paid?
The payment is not lost, but your order will sit unpaid until you check. Run a reconciliation job that polls the provider's transaction status endpoint for pending payments older than a few minutes, and treat the polling result as confirmation the same way you would a callback. Log every callback body before processing so a delayed or retried webhook can still be matched to the order.
Can I use mobile money to pay for my hosting instead of a card?
Some providers accept it directly. Omeganodes, for example, takes MTN and Airtel mobile money for its PaaS plans, which matters if you lack a USD-billing card. Settlement is fast, with funds spendable in the merchant wallet almost immediately, so a sale or a top-up reflects on your balance the moment the prompt is confirmed. Check a provider's payment page before assuming card-only.
Deploy at the speed of Africa
World-class hosting, open to every developer, wherever you build and however you pay. Start free in a couple of minutes — no credit card, no lock-in.