Mobile Money Payments

Mobile money is the primary payment method in West and Central Africa. Ikawaari supports all major operators.

This guide uses the implemented payment_intents route family for first-payment flows.

Supported Operators

Operator	Countries	Currency	Operator Code
Orange Money	Côte d'Ivoire, Sénégal, Mali, Burkina Faso, Guinée, Cameroun	XOF, XAF, GNF	orange_ci, orange_sn, orange_ml, orange_bf, orange_gn, orange_cm
MTN MoMo	Côte d'Ivoire, Cameroun, RDC	XOF, XAF, CDF	mtn_ci, mtn_cm, mtn_cd
Wave	Côte d'Ivoire, Sénégal	XOF	wave_ci, wave_sn
Moov Money	Côte d'Ivoire, Burkina Faso	XOF	moov_ci, moov_bf
Free Money	Sénégal	XOF	free_sn

How it works

1. You create a PaymentIntent with mobile_money as the payment method type
2. The customer provides their phone number
3. Ikawaari sends a USSD push to the customer's phone
4. The customer enters their PIN to confirm
5. You receive a payment_intent.succeeded webhook

Create a mobile money payment

curl -X POST https://api.ikawaari.com/payment_intents \
  -H "Authorization: Bearer ik_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "payment_method_types": ["mobile_money"],
    "payment_method_data": {
      "type": "mobile_money",
      "mobile_money": {
        "phone": "+2250700000000",
        "operator": "orange_ci"
      }
    },
    "confirm": true
  }'

Response

{
  "id": "pi_abc123",
  "status": "processing",
  "next_action": {
    "type": "mobile_money_ussd",
    "mobile_money_ussd": {
      "message": "A USSD prompt has been sent to +225 07 00 00 00 00. Please ask the customer to confirm."
    }
  }
}

Phone number format

Always use E.164 format: +{country_code}{number}

Country	Format	Example
Côte d'Ivoire	+225XXXXXXXXXX	+2250700000000
Sénégal	+221XXXXXXXXX	+221770000000
Mali	+223XXXXXXXX	+22370000000
Cameroun	+237XXXXXXXXX	+237670000000

Timeouts

Mobile money payments have a confirmation timeout (typically 2–5 minutes). If the customer doesn't confirm in time, the payment status changes to failed with reason payment_timeout.

tip

Always display a clear message to the customer: "Please check your phone and enter your PIN to confirm the payment."

Testing

In sandbox mode, use these test phone numbers:

Phone	Behavior
+2250700000001	Payment succeeds immediately
+2250700000002	Payment fails (insufficient funds)
+2250700000003	Payment times out

See Test Mobile Money for more details.