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: how a payment works, what you collect, sandbox testing, and the error reference. The available operators differ by country — see the per-country pages for the operator list and any country-specific notes. 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 outside your checkout. Most operators use a handset prompt flow:

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 AUTH_REQUIRED (not PENDING), and authState.authMethodType tells you what is happening:

• pendingApproval — the prompt has been pushed to the customer’s handset. Show a “check your phone” screen; there is no POST /v1/payment/authorize step — approval happens entirely on the handset, and you either poll or wait for the webhook.
• ussd — the customer must dial themselves: render authState.ussd.instruction verbatim in your checkout.
• fields — the rail asks for a one-time PIN inside your checkout: the authState lists a single otp field, submitted via POST /v1/payment/authorize.
• redirect — the customer authenticates on the operator’s own page: send them to authState.redirect.url.

The fields and redirect rails are covered below and can be exercised in sandbox.

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.

Redirect-based operators (Wave)

Some operators approve through a redirect rather than a handset prompt — the customer is sent to the operator’s page (a QR code on desktop, an app deep link on mobile), approves there, and is redirected back. Wave (Francophone West Africa) works this way; see Wave for the full flow. Country pages note which of their operators use the redirect flow.

Supported countries

The available operators are determined by the payerDetails.location (ISO 3166 alpha-3) you set when creating a checkout session, filtered by what is enabled for your account — operators are configured during onboarding. On Hosted Checkout the customer sees the right operators automatically.

Pick your country for its operators and any country-specific notes:

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 either of the standard CrissCross integration paths:

• Hosted Checkout — CrissCross renders the operator selector, mobile number field, and pending-approval screen. Lowest engineering cost.
• 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 end in a final FAILED status and emit a transaction.failed webhook. The authState.code lets you distinguish reasons.

System errors

These return an authState with state: "error" rather than state: "failed". 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.

Delayed confirmations

These numbers stay unconfirmed for a fixed window before completing, simulating a customer who is slow to approve on their handset. Combined with a session expiry shorter than the window, they exercise the late-debit path — the confirmation arrives after the session has expired, triggering the automatic-refund flow. The refund pays out to the same number, and some numbers double as payout-failure triggers, so they differ in what happens to that refund:

OTP authentication

Some rails ask the customer to confirm the payment with a one-time PIN inside your checkout rather than on their handset. Use this number to exercise that flow end to end:

The transaction returns an authState of authMethodType: "fields" asking for a single otp field, exactly as production OTP rails do. Submit the code via POST /v1/payment/authorize (Hosted Checkout renders the input automatically):

• 123456 — the payment is confirmed and completes shortly after.
• Any other code — the payment fails with invalidPin, mirroring production wrong-OTP behaviour (there is no re-prompt).
• Submit nothing — the transaction expires when the session does, exercising the OTP-timeout path.

Redirect authentication

Some wallets authenticate the customer on the operator’s own page or app instead of an in-session OTP (see Redirect-based operators). These numbers return an authState of authMethodType: "redirect":

There are two kinds of redirect test number — interactive ones that send the customer to a sandbox provider simulation page with Approve and Decline buttons (standing in for the wallet’s real authorisation page), and timed ones where the provider page is never seen and the outcome resolves automatically:

On the interactive numbers the customer’s choice is the sole resolver, whichever integration type you use — there is no timer to race. After deciding, a Hosted Checkout customer is returned to the checkout, and a Direct API customer is sent to your session’s redirectUrl with a status query parameter appended (complete or failed) — provide one on session creation so the round-trip has somewhere to land.

The timed numbers exist for automated suites: no browser is required, and the outcome is delivered asynchronously through polling or the transaction.completed / transaction.failed webhook — the same way production wallet redirects resolve.

Successful payment

Any number not listed above completes the happy path: POST /v1/payment returns PENDING, the transaction moves to AUTH_REQUIRED with authState.authMethodType: "pendingApproval", and the next GET /v1/payment/{transactionId} returns COMPLETED 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

• Find your country in the supported countries table for its operators and notes.
• 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.