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

​
How it works

  1. You create a transaction via the Simiz API with the customer’s phone number
  2. Simiz routes the request to the correct mobile money provider
  3. The customer receives a USSD/push notification on their phone
  4. The customer confirms by entering their PIN
  5. 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

ProviderCodeCountriesMin AmountMax Amount
Orange MoneyORANGE_MONEYCM, SN, CI, ML100 XAF5,000,000 XAF
MTN MoMoMTN_MOMOCM, GH, UG100 XAF5,000,000 XAF
WaveWAVESN, CI, ML, BF100 XOF5,000,000 XOF
Airtel MoneyAIRTEL_MONEYGH, UG, TZ——

​
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:
CountryFormatExample
Cameroon237XXXXXXXXX237690000001
Senegal221XXXXXXXXX221770000001
Côte d’Ivoire225XXXXXXXXX225070000001
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 CodeDescriptionAction
insufficient_balanceCustomer’s wallet balance is too lowInform customer to top up
pin_errorWrong PIN enteredCustomer should retry
provider_timeoutProvider didn’t respond in timeRetry the transaction
account_inactiveCustomer’s wallet is inactiveContact operator

​
Best practices

Network issues can cause duplicate requests. Use the Idempotency-Key header to ensure the same transaction isn’t created twice. See the Idempotency guide.
Don’t rely only on the API response. Always handle payment.succeeded, payment.failed, and payment.expired webhooks.
Validate the phone number format before calling the API. This reduces failed transactions and improves user experience.