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 or our SDK, 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, configured in the CrissCross dashboard. See Webhooks.
• 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 five endpoints. Steps 2 and 5 are optional but recommended:

1. POST /v1/checkout/session — Create a session for the payment. → returns sessionId.
2. (Optional) GET /v1/payment/available-methods?sessionId=... — Check which operators are available for this payer. Useful for rendering the operator selector.
3. POST /v1/payment — Initiate the transaction. → returns transactionId, transaction enters pending.
4. 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.
5. (Optional) POST /v1/payment/refunds — Refund the payment later. See Refunds.

POST /v1/payment/authorize is not part of the mobile money flow. It exists for card 3-D Secure challenges and similar redirect-based flows. Don’t call it for mobile money.

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

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

Keep the sessionId. You’ll use it for the next two calls. 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.

Step 2 — (Optional) Get available payment methods

If you want to render an operator picker driven by what’s actually configured for the payer’s country, ask the API:

$
curl -G 'https://api.crisscross.money/v1/payment/available-methods' \
>
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
>
  --data-urlencode 'sessionId=0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a'

Response

1
{
2
  "success": true,
3
  "availableMethods": [
4
    {
5
      "type": "mobilemoney",
6
      "name": "Mobile Money",
7
      "requiredInput": [
8
        {
9
          "name": "provider",
10
          "type": "select",
11
          "label": "Provider",
12
          "options": [
13
            { "value": "mpesa", "label": "M-Pesa" }
14
          ]
15
        },
16
        { "name": "payerFullName", "type": "text", "label": "Payer Full Name" },
17
        { "name": "payerMobileNumber", "type": "text", "label": "Payer Mobile Number" }
18
      ]
19
    }
20
  ]
21
}

A few things to note:

• The type field is always "mobilemoney" — there is no "mtn-momo" or "mobile-money" variant. Operator selection happens inside paymentDetails.provider on the payment request.
• The options list under provider is country-filtered based on payerDetails.location from the session. For Kenya you’ll only see M-Pesa; for Côte d’Ivoire you’ll see MTN, Orange, Moov, and Wave.
• The full list of operator slugs and per-country availability is on the Mobile Money page.

You can skip this call entirely if you already know which operator the customer is using.

Step 3 — 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

1
{
2
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
3
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
4
  "merchantReference": "ORDER-2026-0142",
5
  "paymentMethodId": "mobilemoney",
6
  "status": "pending",
7
  "message": "Transaction pending",
8
  "authState": {
9
    "type": "pending_approval"
10
  }
11
}

At this point CrissCross has sent the request to the operator, which has dispatched the push / USSD prompt to the customer’s handset. 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 4 — 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 payload:

1
{
2
  "eventType": "transaction.completed",
3
  "eventId": "evt_01HX5GMR3K8YBQ5VCRD7P3F9Z2",
4
  "timestamp": "2026-06-02T10:30:14Z",
5
  "payload": {
6
    "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
7
    "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
8
    "merchantReference": "ORDER-2026-0142",
9
    "paymentMethodId": "mobilemoney",
10
    "status": "COMPLETED",
11
    "message": "Transaction completed",
12
    "processorName": "safaricom-daraja",
13
    "processorReference": "PROC-9f3e4b2c",
14
    "authState": {
15
      "state": "authorized",
16
      "transitionedAt": "2026-06-02T10:30:14Z"
17
    }
18
  }
19
}

Match incoming events to the transaction using payload.transactionId (preferred) or payload.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:

1
{
2
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
3
  "status": "pending",
4
  "message": "Transaction pending",
5
  "authState": { "type": "pending_approval" }
6
}

Response after the customer approves:

1
{
2
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
3
  "status": "COMPLETED",
4
  "message": "Transaction successful",
5
  "processorReference": "PROC-9f3e4b2c",
6
  "authState": {
7
    "type": "authorized",
8
    "processorTransactionId": "PROC-9f3e4b2c",
9
    "financialTransactionId": "FIN-9f3e4b2c"
10
  }
11
}

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 after ~3 minutes total — at that point trust the webhook. Customers usually approve within 10 – 30 seconds.

Handling failures

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

1
{
2
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
3
  "status": "FAILED",
4
  "message": "Insufficient funds",
5
  "authState": {
6
    "type": "auth_failure",
7
    "code": "PAYIN_INSUFFICIENT_FUNDS",
8
    "message": "The payer's mobile money account has insufficient funds."
9
  }
10
}

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.type: "error" is distinct from auth_failure — it means CrissCross or the operator hit a system error, not that the payment was declined. The response carries hints about how to recover:

1
{
2
  "authState": {
3
    "type": "error",
4
    "code": "DOWNSTREAM_ERROR",
5
    "message": "Provider returned a transient error",
6
    "canRetry": true
7
  }
8
}

• 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 eventId 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 – 0970000010, 0970000014 → specific auth failure codes.
• 0970000012, 0970000013 → system errors.
• 0970000015 – 0970000017 → transient errors for exercising retry logic.

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.