Mobile Money

Mobile Money is the primary payment method across Africa. Simiz supports all major mobile money providers through a single, unified API.

Diagram: your API call reaches Simiz, which routes a push request through the mobile operator; the customer's phone shows a payment prompt, they enter their PIN, and a payment.completed webhook returns to your server. — Push-based flow: the customer confirms on their own phone — no card, no app, no redirect.

How it works

You create a transaction via the Simiz API with the customer’s phone number
Simiz routes the request to the correct mobile money provider
The customer receives a USSD/push notification on their phone
The customer confirms by entering their PIN
Simiz sends you a webhook with the payment result

The entire flow typically completes in 30–90 seconds. The transaction expires after 15 minutes if the customer doesn’t confirm.

Supported providers

These operator codes are technically supported by the Simiz API across the CEMAC and UEMOA zones (14 countries). Corridors are being activated (Coming soon): live coverage is at /coverage and actual availability per account is in the dashboard.

Provider	Code	Min Amount	Max Amount
Orange Money	`ORANGE_MONEY`	100 XAF	5,000,000 XAF
MTN MoMo	`MTN_MOMO`	100 XAF	5,000,000 XAF
Wave	`WAVE`	100 XOF	5,000,000 XOF
Moov Money	`MOOV_MONEY`	—	—

Create a Mobile Money payment

curl -X POST https://api.simiz.io/v1/transactions \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "payment_method": "ORANGE_MONEY",
    "payer": {
      "phone": "237690000000",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "description": "Order #12345",
    "reference": "ORDER-123",
    "metadata": {
      "order_id": "123",
      "customer_id": "cust_456"
    },
    "callback_url": "https://your-site.com/webhooks/simiz",
    "return_url": "https://your-site.com/success"
  }'

Phone number format

Phone numbers must include the country code without the + sign:

Country	Format	Example
Cameroon	`237XXXXXXXXX`	`237690000001`
Senegal	`221XXXXXXXXX`	`221770000001`
Côte d’Ivoire	`225XXXXXXXXX`	`225070000001`

Invalid phone numbers will return a 400 invalid_phone error. Always validate the format before sending.

Error handling

Common errors specific to Mobile Money:

Error Code	Description	Action
`insufficient_balance`	Customer’s wallet balance is too low	Inform customer to top up
`pin_error`	Wrong PIN entered	Customer should retry
`provider_timeout`	Provider didn’t respond in time	Retry the transaction
`account_inactive`	Customer’s wallet is inactive	Contact operator

Best practices

Always use idempotency keys

Network issues can cause duplicate requests. Use the Idempotency-Key header to ensure the same transaction isn’t created twice. See the Idempotency guide.

Handle all webhook events

Don’t rely only on the API response. Always handle transaction.completed, payment.failed, and transaction.expired webhooks.

Validate phone numbers client-side

Validate the phone number format before calling the API. This reduces failed transactions and improves user experience.

Getting Started

Core Concepts

Billing

Guides

How it works

Supported providers

Create a Mobile Money payment

Phone number format

Error handling

Best practices

​How it works

​Supported providers

​Create a Mobile Money payment

​Phone number format

​Error handling

​Best practices

How it works

Supported providers

Create a Mobile Money payment

Phone number format

Error handling

Best practices