Mobile Money

Overview

Mobile money is the dominant consumer payment method across most of Africa. Customers hold a wallet balance with a mobile network operator (MTN, M-Pesa, Airtel, Orange, and others) and authorise payments from their handset using a PIN. CrissCross gives you a single integration that covers every supported operator in every supported country.

This page is the umbrella reference for the payment method. For operator-specific copy (logos, marketing notes, and operator-only quirks) see the per-operator pages linked below; for the end-to-end Direct API request/response sequence see the Direct API: Mobile Money guide.

How a mobile money payment works

Unlike a card payment, a mobile money payment is asynchronous: the customer approves the debit on their handset, not in your checkout. The lifecycle looks like this:

1. The merchant initiates a payment with the customer’s provider and phone number.
2. The operator sends a push or USSD prompt to the customer’s handset.
3. The customer enters their PIN to approve (or rejects, or lets it time out).
4. The operator confirms the outcome back to CrissCross, which notifies you via webhook and exposes the final state on the transaction.

While the customer is approving, the transaction sits in a pending state with authState.type: "pending_approval". There is no POST /payment/authorize step for mobile money — approval happens entirely on the handset, and you either poll or wait for the webhook.

Typical approval takes 10 – 30 seconds. The provider will eventually time the prompt out (usually around 60 – 120 seconds) if the customer takes no action.

Supported countries and operators

The set of available operators is determined by the payerDetails.location you submit when creating a checkout session. The exhaustive list returned for a given country is also available from GET /v1/payment/available-methods once a session exists — that endpoint is the source of truth at runtime and will reflect any operator that has been disabled for your account.

Operator slugs (the value you pass in paymentDetails.provider):

airtel, airteltigo, celtiis, free, halotel, moov, mpesa, mtn, orange, tigo, vodacom, wave, zamtel.

For operator-specific marketing copy and supported workflow notes, see:

• MTN MoMo
• M-Pesa
• Airtel Money
• Tanzania mobile money (Tembo)

What you collect from the customer

For any mobile money payment, you need three things:

The country code itself comes from payerDetails.location on the session — an ISO 3166 alpha-3 code like KEN, NGA, ZAF. You don’t pass the country code on the payment request again.

Integration options

You can accept mobile money through any of the standard CrissCross integration paths:

• Hosted Checkout — CrissCross renders the operator selector, mobile number field, and pending-approval screen. Lowest engineering cost.
• CrissCross SDK — drop-in components that handle the input fields and approval polling for you.
• Direct API: Mobile Money — full control. You collect the inputs, call POST /v1/payment, and either poll or rely on webhooks for completion.

The Direct API guide is the most concrete reference for what fields are sent and what responses look like.

Sandbox testing

Sandbox is on by default for every test merchant. Hit https://api.crisscross.money with sandbox credentials and any mobile money request will be routed to the sandbox connector — no real handset, no real operator, no money moves.

The sandbox decides the outcome based on the last digits of the mobile number you submit. The match is on the normalised E.164 form, so the country code doesn’t matter: 0970000005, +27970000005, and +254970000005 all trigger the same scenario when sent with a payerDetails.location of ZAF, KEN, etc. Any number not listed below succeeds normally.

Authorisation failures

These numbers cause the transaction to move from pending to a final failed state and emit a transaction.failed webhook. The authState.code lets you distinguish reasons.

System errors

These return an error authState rather than auth_failure. Retry semantics differ — see the Direct API guide for which can be retried.

Transient errors (test your retry logic)

These numbers misbehave for the first ~2 seconds after the transaction is created, then succeed. They’re useful for verifying that your polling and retry code is resilient.

Successful payment

Any number not listed above completes the happy path: the response on POST /v1/payment is pending with authState.type: "pending_approval", and a subsequent GET /v1/payment/{transactionId} returns authorized with a processorReference like PROC-<transactionId>.

Failure and error reference

The full set of authState.code values you can see on a mobile money transaction:

Auth failures are terminal for the transaction — the customer would need to retry with a fresh payment. Errors marked as retryable in the response (authState.canRetry) can be re-executed against the same checkout session.

Next steps

• Walk through the end-to-end API sequence in Direct API: Mobile Money.
• Configure your webhook subscription to receive transaction.completed, transaction.failed, transaction.errored, transaction.cancelled, and transaction.expired — see Webhooks.
• Review operator-specific notes on MTN MoMo, M-Pesa, Airtel, or Tanzania mobile money.