Africa Mobile Money

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:

1. Fetch transaction report from operator API (daily)
2. Compare with your local records
3. Flag mismatches: received but not recorded, recorded but not received
4. 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BuilderCed
• Source: BuilderCed/agent-skills
• License: MIT
• Homepage: https://skills.sh/BuilderCed/agent-skills

Install and usage instructions live in the source repository linked above.