A Tanzanian e-commerce checkout collects items in a cart, presents an order summary with a TZS total, asks for the customer's mobile money phone number, sends a payment request to an aggregator (or directly to Vodacom, Tigo, or Airtel), waits for the customer to confirm on their phone, receives a callback with the result, and updates the order status. The key differences from a card-based checkout: the payment is asynchronous (you wait for a callback instead of getting an instant response), you need a "waiting for confirmation" state in your UI, and you must handle timeouts and retries. Use an aggregator like Selcom or Azampay to support all three rails through one API.
If you have built a checkout with Stripe or PayPal, you are used to synchronous payments: the customer enters their card details, you send the request, and you get a success or failure response within seconds. The customer never leaves your page.
Mobile money does not work this way. The flow involves the customer's phone:
Steps 3 through 5 happen outside your application. You have no control over how long the customer takes to check their phone. They might be in the other room. They might need to find their phone. They might be in an area with poor network coverage. The typical wait is 10 to 60 seconds, but it can be longer.
Your checkout must handle this waiting period. You cannot show a blank page or a spinning wheel for 60 seconds without explanation. You need a clear "waiting for confirmation" state that tells the customer what is happening and what they need to do.
Here is the end-to-end architecture for a Tanzanian e-commerce checkout:
Get weekly developer tips
Join 25,000+ developers. Practical guides, job tips, and new content — straight to your inbox.
No spam. Unsubscribe anytime.
A mobile money e-commerce order has more states than a card-based order. Here are the states you need to handle:
Edge cases to handle:
Your checkout must work with M-Pesa, Tigo Pesa, and Airtel Money. Here is how to handle the multi-provider aspect:
If using an aggregator: The aggregator handles provider routing. You send the phone number and amount. The aggregator detects whether it is a Vodacom, Tigo, or Airtel number and routes the request accordingly. You receive a normalized callback regardless of provider. This is the simplest path.
If using direct integration: You need to detect the provider from the phone number prefix and route the request to the correct API. Maintain separate configuration (credentials, endpoints) for each provider. Normalize the callback data from all three into a common format before processing.
Phone number prefix detection for Tanzania:
Note: number portability could make prefix detection unreliable in the future. If a customer says they are on Airtel but their number prefix suggests Vodacom, trust the customer. Some checkouts add a provider selector (three buttons with provider logos) in addition to the phone number field, as a fallback.
Whichever approach you take, show the customer which provider was detected. Seeing the Vodacom, Tigo, or Airtel logo next to their phone number builds confidence that the checkout supports their wallet.
The async nature of mobile money payments creates an inventory problem that card-based checkouts rarely face: what do you do with the inventory during the 10 to 60 seconds between initiating payment and receiving confirmation?
Two approaches:
Optimistic: Reserve inventory on payment initiation. When the customer clicks "Pay," temporarily reserve the items. If payment succeeds, confirm the reservation. If it fails or times out, release the items. This prevents selling the same item to two customers simultaneously but ties up inventory during the confirmation window.
Pessimistic: Reserve inventory on payment confirmation. Do not reserve anything until the callback confirms payment. This means two customers could pay for the same last-in-stock item. The second one gets a refund and an apology. This is simpler to build but creates a worse customer experience.
For most Tanzanian e-commerce stores, the optimistic approach works better. The confirmation window is short (under 90 seconds), and the risk of two customers buying the same item in that window is low unless you sell high-demand, limited-stock products.
Either way, set a timeout on the reservation. If the payment does not confirm within 90 seconds, release the inventory and mark the order as timed out. Allow the customer to retry.
A Tanzanian e-commerce checkout combines two skill sets: full-stack web development (building the store, cart, and checkout UI) and mobile money integration (handling payments, callbacks, and transaction management).
McTaba teaches both:
The M-Pesa Integration course is the starting point if you already have full-stack skills. The Full-Stack course is the starting point if you are building those skills from scratch. Both together give you everything you need to build a production e-commerce store for the Tanzanian market.
Create a free McTaba Academy account. Access starter lessons, join the community, and explore at your own pace.
Create Free Account