Direct API: Mobile Money

Overview

This guide walks through a complete mobile money payment using CrissCross’s Direct API. It assumes you’ve decided not to use Hosted Checkout, and want to drive the flow yourself.

For the conceptual overview, supported operators, and sandbox test numbers, see Mobile Money. This page is the request/response reference.

Prerequisites

• CrissCross account with a merchantId and API credentials. See Authentication for how to obtain a bearer token.
• A webhook endpoint reachable over HTTPS, subscribed to transaction events. See Webhooks for how subscriptions are managed.
• Sandbox credentials for testing. The same endpoints serve both sandbox and live — your bearer token routes the request to the right environment.

All requests in this guide go to https://api.crisscross.money/v1.

The flow at a glance

A mobile money payment touches four endpoints. Step 4 is optional:

1. POST /v1/checkout/session — Create a session for the payment. → returns sessionId.
2. POST /v1/payment — Initiate the transaction. → returns transactionId, transaction enters PENDING.
3. Webhook + GET /v1/payment/{transactionId} — Wait for the customer to approve on their handset. The terminal state arrives by webhook; poll if you need an interactive UI.
4. (Optional) POST /v1/payment/refunds — Refund the payment later. See Refunds.

The operators you can offer are configured on your account during onboarding. The full list of operator slugs and per-country availability is on the Mobile Money page.

For most operators POST /v1/payment/authorize is not part of the flow — approval happens on the customer’s handset. The exceptions are OTP rails (the transaction asks for a one-time PIN collected in your checkout and submitted via POST /v1/payment/authorize) and redirect rails (the customer authenticates on the operator’s page). Both are covered in OTP and redirect rails below.

Step 1 — Create a checkout session

curl -X POST 'https://api.crisscross.money/v1/checkout/session' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "merchantId": "1b2a3d4c-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "merchantReference": "ORDER-2026-0142",
    "amount": 250000,
    "currency": "KES",
    "integrationType": "direct",
    "payerDetails": {
      "emailAddress": "[email protected]",
      "fullName": "Frank Mwangi",
      "location": "KEN",
      "phoneNumber": "+254701234567"
    }
  }'

Response

{
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
  "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f"
}

Keep the sessionId. You’ll use it to initiate the payment. A session can only have one active transaction at a time — POST /v1/payment will return 409 Conflict if you try to initiate a second one against the same session.

The response also returns a payerId — a persistent identifier for this customer. Store it against your customer record and pass it back in payerDetails.payerId on future sessions to recognise a returning payer. See Payer ID.

Step 2 — Initiate the payment

curl -X POST 'https://api.crisscross.money/v1/payment' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
    "paymentMethodId": "mobilemoney",
    "paymentDetails": {
      "type": "mobilemoney",
      "provider": "mpesa",
      "payerMobileNumber": "0701234567",
      "payerFullName": "Frank Mwangi"
    }
  }'

Response

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
  "merchantReference": "ORDER-2026-0142",
  "paymentMethodId": "mobilemoney",
  "status": "PENDING",
  "message": "Transaction pending"
}

The response carries the transaction’s current status — usually PENDING, but a fast routing failure can come back as FAILED or ERRORED synchronously, so handle any status. Once CrissCross has sent the request to the operator and the push / USSD prompt is on the customer’s handset, the transaction moves to AUTH_REQUIRED with authState.authMethodType: "pendingApproval". The customer now has to approve.

Tell your customer what’s happening. A mobile money pending screen should say something like “Check your phone — we’ve sent an MTN prompt to +254 ••• •••• 567. Enter your MoMo PIN to approve.” If you skip this, customers often think the page is broken and abandon.

Step 3 — Wait for the terminal state

You have two options, and most integrations use both. Webhooks are the source of truth; polling is for keeping your customer-facing UI responsive while you wait.

Webhooks

Subscribe to these event types on your webhook endpoint:

Example completed body, exactly as delivered — the payload is the whole body, with no envelope around it:

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
  "merchantReference": "ORDER-2026-0142",
  "paymentMethodId": "mobilemoney",
  "status": "COMPLETED",
  "message": "Transaction completed",
  "identifiers": {
    "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f",
    "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a"
  },
  "paymentAttributes": { "merchant_type": "real" },
  "processorName": "safaricom-daraja",
  "processorReference": "PROC-9f3e4b2c",
  "financialTransactionReference": null,
  "authState": {
    "state": "completed",
    "transitionedAt": "2026-06-02T10:30:14Z",
    "message": "Transaction completed"
  }
}

Because the body carries no event type, subscribe this endpoint to transaction.* only and route on status. Match incoming events to the transaction using transactionId (preferred) or merchantReference. Verify the webhook signature on every delivery — see Webhooks → Securing webhooks.

Polling

If you need to update the customer-facing screen as soon as approval happens (rather than waiting for the webhook to land on your server and round-trip back), poll:

curl -G 'https://api.crisscross.money/v1/payment/9f3e4b2c-1a6d-4e88-9d3a-ff1234567890' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response while the customer is approving:

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "status": "AUTH_REQUIRED",
  "message": "Transaction pending",
  "authState": { "authMethodType": "pendingApproval" }
}

Response after the customer approves:

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "status": "COMPLETED",
  "message": "Transaction completed",
  "processorReference": "PROC-9f3e4b2c",
  "authState": {
    "state": "completed",
    "transitionedAt": "2026-06-02T10:30:44Z",
    "message": "Transaction completed"
  }
}

Recommended polling cadence: every 2 seconds for the first 30 seconds, then back off to every 5 – 10 seconds. Stop polling once status is no longer PENDING or AUTH_REQUIRED — unless the response carries authState.canPoll: true, which means the error was a polling hiccup and the transaction may still complete, so keep going. Stop after ~3 minutes total either way and trust the webhook. Customers usually approve within 10 – 30 seconds.

OTP and redirect rails

Some rails don’t use the handset prompt. Instead of authMethodType: "pendingApproval", the transaction’s AUTH_REQUIRED state carries an authState describing what the customer must do next. Detect these on the poll response and handle them before falling back to the normal wait loop.

OTP — authState.authMethodType: "fields" with a single otp field (and an optional buyer-facing instruction to render above the input). Collect the code from the customer and submit it:

curl -X POST 'https://api.crisscross.money/v1/payment/authorize' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "transactionId": "0197a3f1-2b4c-7d5e-8f90-1a2b3c4d5e6f",
    "authDataFields": [
      { "name": "otp", "type": "string", "value": "123456" }
    ]
  }'

A correct code moves the payment to confirmation (poll or wait for the webhook as usual); a wrong code fails the transaction with authState.code: "invalidPin" — there is no re-prompt, the customer must start a fresh payment. If the customer never submits, the transaction expires with the session.

Redirect — authState.authMethodType: "redirect" with a url to send the customer to (and requiresTopLevel: true when the URL deep-links to a wallet app and must not be iframed). Provide a redirectUrl on the session so the customer can be sent back to you afterwards — after authorising on the operator’s page (in sandbox, the interactive test numbers serve a provider simulation page with Approve/Decline buttons; the timed numbers skip it) the customer is redirected there with a status query parameter appended. The outcome arrives asynchronously through the poll/webhook channel once the customer completes (or abandons) the operator’s page — there is nothing to submit yourself.

In sandbox, 0970000021 exercises the OTP rail and 0970000022 – 0970000025 the redirect rail — see Testing below.

Handling failures

If the customer rejects, times out, or has insufficient funds, the transaction ends in status: FAILED with authState.state: "failed" and a specific code:

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "status": "FAILED",
  "message": "Insufficient funds",
  "authState": {
    "state": "failed",
    "code": "payinInsufficientFunds",
    "message": "The payer's mobile money account has insufficient funds."
  }
}

Common codes you’ll see for mobile money:

An auth failure is terminal for the transaction. To retry, create a new transaction on the same sessionId (or a fresh session if it has expired).

Handling errors

authState.state: "error" is distinct from failed — it means CrissCross or the operator hit a system error, not that the payment was declined. The response carries hints about how to recover:

{
  "authState": {
    "state": "error",
    "code": "downstreamError",
    "message": "Provider returned a transient error",
    "canRetry": true
  }
}

• canRetry: true — Re-initiate the transaction. If your account has a fallback processor configured for the same operator, CrissCross will route the retry there.
• canPoll: true — The error came from a polling attempt; keep polling, the transaction may still complete.
• Neither flag set — Treat as terminal and surface a generic “Something went wrong” to the customer.

Idempotency and duplicate prevention

• A sessionId can only have one active transaction at a time. Repeated POST /v1/payment calls with the same sessionId return 409 Conflict while the first transaction is still live, which is the intended way to prevent duplicate charges if your client retries.
• For the same logical order, reuse the same merchantReference on the session — this gives you a stable identifier for reconciliation via GET /v1/payment/search?merchantReference=....
• Webhooks may be delivered more than once. Deduplicate on the svix-id header in your handler. See Webhooks → Best practices.

Testing

Sandbox responses are driven by the last digits of payerMobileNumber. The full table of test numbers is on the Mobile Money page — short version:

• Any number not in the table → success.
• 0970000005 – 0970000011, 0970000014 → specific auth failure codes.
• 0970000012, 0970000013 → system errors.
• 0970000015 – 0970000017 → transient errors for exercising retry logic.
• 0970000018 – 0970000020, 0970000026 → delayed confirmations (5 min / 30 s / 1 min / 1 min) — pair a delay longer than the session expiry to exercise the late-debit path. Use 0970000026 to see the automatic refund succeed; the refunds for 0970000018 and 0970000020 fail, because those numbers double as payout-failure triggers.
• 0970000021 → OTP rail: submit 123456 via POST /v1/payment/authorize to complete, any other code to fail with invalidPin.
• 0970000022, 0970000024 → timed redirect rail: the redirect url is your returnUrl (no provider page) and the payment auto-completes / auto-fails ~10 s after initiation. Use these for headless suites.
• 0970000023, 0970000025 → interactive redirect rail: the redirect url is a sandbox provider simulation page with Approve/Decline buttons (0970000023 with requiresTopLevel: true); the customer’s decision is the sole resolver — never auto-resolves — and sends them back to your session’s redirectUrl with a status param.

Use a real payerDetails.location for the country code you’re testing — the number is normalised against it, so 0970000005 with "location": "KEN" and 0970000005 with "location": "NGA" produce the same failure but on different normalised numbers.

Endpoint reference

For the full schemas of every request and response, see the Payments API reference.