> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Money

> Accept Mobile Money payments from Orange Money, MTN MoMo, Wave, and Moov Money.

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

<Frame caption="Push-based flow: the customer confirms on their own phone — no card, no app, no redirect.">
  <img src="/images/mobile-money-push.svg" alt="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." />
</Frame>

## 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

<Note>
  The entire flow typically completes in **30–90 seconds**. The transaction expires after **15 minutes** if the customer doesn't confirm.
</Note>

## 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](https://simiz.io/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

```bash
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` |

<Warning>
  Invalid phone numbers will return a `400 invalid_phone` error. Always validate the format before sending.
</Warning>

## 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

<Accordion title="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](/en/core-concepts/security/idempotency).
</Accordion>

<Accordion title="Handle all webhook events">
  Don't rely only on the API response. Always handle `transaction.completed`, `payment.failed`, and `transaction.expired` webhooks.
</Accordion>

<Accordion title="Validate phone numbers client-side">
  Validate the phone number format before calling the API. This reduces failed transactions and improves user experience.
</Accordion>