name: africa-mobile-money description: Integrate M-Pesa, Orange Money, Wave, and MTN MoMo payment APIs with proper error handling, reconciliation, and multi-operator patterns. version: "1.0.0" last-updated: "2026-04-17" model_tested: "claude-sonnet-4-6" category: africa platforms: [claude-code, codex, gemini-cli, cursor, copilot, windsurf, cline] language: en geo_relevance: [africa] priority: medium dependencies: mcp: [] skills: [] apis: [mpesa-daraja, orange-money, wave, mtn-momo] data: [] update_sources:
- url: "https://developer.safaricom.co.ke" check_frequency: "quarterly" last_checked: "2026-04-17" license: MIT
Africa Mobile Money Integration
DISCLAIMER: This skill provides integration patterns only. It does not constitute financial advice. Payment processing is regulated — verify compliance with local financial authorities in each market.
When to Use
- Accepting payments from African mobile money users
- Building multi-operator payment flows
- Implementing reconciliation for mobile money transactions
- Designing payment UX for feature phones (USSD) and smartphones
Supported Operators
| Operator | Markets | API | Auth |
|---|---|---|---|
| M-Pesa (Safaricom) | Kenya, Tanzania, DRC, Mozambique | Daraja 2.0 | OAuth2 |
| Orange Money | Senegal, Mali, Cote d'Ivoire, Cameroon, 10+ | OMAPI | API Key |
| Wave | Senegal, Cote d'Ivoire, Mali, Uganda | REST | API Key |
| MTN MoMo | Ghana, Uganda, Rwanda, Cameroon, 10+ | Open API | OAuth2 + Subscription Key |
Common Payment Flow
1. Customer initiates payment (app, USSD, or web)
2. Your server calls operator API (STK Push / Payment Request)
3. Customer receives prompt on phone → enters PIN
4. Operator processes → sends callback to your server
5. Your server verifies callback signature
6. Update order status + send confirmation
Key Patterns
Multi-Operator Detection
Detect operator from phone number prefix:
Kenya:
07XX, 01XX → Safaricom (M-Pesa)
0720-0729 → Safaricom
0733-0739 → Safaricom
Senegal:
77X → Orange Money
78X → Wave
76X → Free Money
Idempotency
Mobile money callbacks can arrive multiple times. Always:
- Use a unique transaction ID per request
- Check if transaction already processed before updating state
- Store callback raw payload for reconciliation
Timeout Handling
Mobile money transactions have long confirmation times:
- M-Pesa STK Push: up to 60s for customer PIN entry
- Orange Money: up to 120s
- Design for: pending → success/failed/expired states
- Never assume failure on timeout — always check status API
Reconciliation
Daily reconciliation is critical:
- Fetch transaction report from operator API (daily)
- Compare with your local records
- Flag mismatches: received but not recorded, recorded but not received
- Investigate and resolve within 24h
Error Handling
| Error | Cause | Action |
|---|---|---|
| Insufficient balance | Customer lacks funds | Show clear message, suggest lower amount |
| Wrong PIN | Customer entered wrong PIN | Allow retry (max 3) |
| Timeout | Customer didn't respond | Check status API, don't retry automatically |
| Duplicate | Same transaction sent twice | Return existing result (idempotent) |
| System unavailable | Operator maintenance | Queue and retry with exponential backoff |
Security
- Never log full phone numbers (PII) — mask middle digits
- Verify callback source — check IP whitelist or signature
- Use HTTPS for all API calls
- Store API keys in environment variables, never in code
- Amount validation — server-side, never trust client
What This Skill Does NOT Do
- Does not handle operator onboarding/KYC (business process)
- Does not manage currency conversion (use forex APIs)
- Does not implement USSD menus (see
africa-ussd-development) - Does not handle regulatory compliance per country (varies widely)