Orange Money, MyZaka, and smega APIs are open — but the documentation is scattered and gotchas are real. This guide consolidates what we have learned building payment integrations across Botswana.
Mobile money is the de facto payment rail for retail transactions in Botswana. With over 2 million registered mobile wallets across Orange Money, MyZaka (Mascom), and smega (BTC), any business-facing application that does not integrate payments is leaving revenue on the table.
Understanding the payment landscape
All three major mobile money providers in Botswana offer merchant APIs based on a similar pattern: initiate payment request → customer approves on their phone → receive callback with success/failure status. The difference lies in the authentication model, sandbox availability, and callback reliability.
Common integration patterns
- Push payment (C2B): you send a payment request to the customer's phone number. Best for checkout flows.
- Pull payment (B2C): you push money to a customer or supplier wallet. Used for disbursements, cashback, and loyalty rewards.
- QR code payment: customer scans a static or dynamic QR code. Best for in-store or low-connectivity environments.
- USSD payment menu: customer dials a shortcode and confirms payment. Works on any phone, including feature phones.
Technical gotchas we have hit in production
- Callback timeouts: always implement idempotent payment status polling in addition to callbacks. Callbacks fail silently in ~3 % of transactions.
- Phone number normalisation: +267 71 234 567, 71234567, and 00267712345567 are all valid inputs from users. Normalise to E.164 before sending to the API.
- Sandbox vs production: sandbox systems occasionally approve amounts the production system rejects. Always test edge cases on production with small amounts.
- Rate limits: most APIs limit to 10 requests/second. Implement a queue for batch disbursements.
Security checklist
- Store API keys in environment variables — never in code or version control.
- Validate callback signatures using the provider's HMAC key.
- Implement double-spend protection with idempotency keys.
- Log every transaction attempt, callback, and reconciliation event.
"Payment code is the one place where optimistic error handling is unacceptable. Verify everything twice."
