M-PESA and Airtel Money

Use a mobile money charge when you already have the customer’s phone number. Tanda sends a payment prompt to their phone (an STK push on M-PESA); they enter their M-PESA or Airtel Money PIN to approve, and the money lands in your KES wallet.

1. Send the prompt

Call Mobile money charge.

curl -X POST https://api.tandapay.io/api/b2b/fiat/deposit/momo \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "currency": "KES",
    "phoneNumber": "254712345678",
    "externalReference": "order_10045"
  }'

const charge = await fetch("https://api.tandapay.io/api/b2b/fiat/deposit/momo", {
  method: "POST",
  headers: { Authorization: `Bearer ${await getToken()}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    amount: 1500,
    currency: "KES",
    phoneNumber: "254712345678",
    externalReference: "order_10045",
  }),
}).then((r) => r.json());

charge = requests.post(
    "https://api.tandapay.io/api/b2b/fiat/deposit/momo",
    headers={"Authorization": f"Bearer {get_token()}"},
    json={
        "amount": 1500,
        "currency": "KES",
        "phoneNumber": "254712345678",
        "externalReference": "order_10045",
    },
).json()

Response

{
  "success": true,
  "message": "Initiated request.",
  "transactionId": "aB3dE5fG7hJ9kL1mN2pQ"
}

Field	Required	Notes
`amount`	Yes	Whole shillings, e.g. `1500`.
`currency`	Yes	`KES`.
`phoneNumber`	Yes	`2547XXXXXXXX` or `2541XXXXXXXX`, no `+`.
`externalReference`	Yes	Your unique ID for this attempt.
`momoOperatorId`	No	`mpesa` or `airtel`. If omitted, Tanda detects the network from the number.

Tell the customer to check their phone as soon as you get the response. Prompts time out after a short while; if the customer misses it, start a new charge with a new externalReference.

2. Wait for the outcome

The customer approves (or ignores) the prompt on their phone, so the result arrives asynchronously as a transaction_updated webhook.

Successful

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "successful",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo",
    "thirdPartyReference": "TJS4K2LM9P"
  },
  "timestamp": "2026-10-28T09:14:22.100Z"
}

Failed

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "failed",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo",
    "note": "The user cancelled the request."
  },
  "timestamp": "2026-10-28T09:14:22.100Z"
}

thirdPartyReference is the M-PESA or Airtel receipt number. Store it: customers quote it when they contact you. If you haven’t received a webhook, check with Get transaction using the transactionId or your externalReference. Fulfil only when chargeStatus is successful.

3. Handle an OTP step

Occasionally a charge needs a one-time code. The webhook arrives with status: "pending" and stepRequired: "otp":

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "pending",
    "type": "deposit",
    "externalReference": "order_10045",
    "stepRequired": "otp",
    "method": "momo"
  },
  "timestamp": "2026-10-28T09:14:05.000Z"
}

Ask the customer for the code and submit it with Validate OTP:

curl -X POST https://api.tandapay.io/api/b2b/fiat/deposit/aB3dE5fG7hJ9kL1mN2pQ/validate-otp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "111111" }'

A final successful or failed webhook follows.

Why prompts fail

The note field explains a failure. The common ones:

What happened	What to do
Customer cancelled or didn’t enter their PIN in time	Offer to try again with a new charge.
Phone off or out of coverage	Ask the customer to check their phone, then retry.
Insufficient balance	Ask the customer to top up, or offer another method.
Number not registered for M-PESA or Airtel Money	Check the number or offer another method.
Network busy	Retry after a short delay. Check Service status before retrying many at once.

The full list is in Transaction errors. Don’t branch your code on the wording of note; use status.

Refunds

You can refund a successful mobile money payment back to the customer’s wallet. See Refunds.

Get started

Accept payments

Send payouts

Webhooks

Go live

M-PESA and Airtel Money

1. Send the prompt

2. Wait for the outcome

3. Handle an OTP step

Why prompts fail

Refunds

​1. Send the prompt

​2. Wait for the outcome

​3. Handle an OTP step

​Why prompts fail

​Refunds

1. Send the prompt

2. Wait for the outcome

3. Handle an OTP step

Why prompts fail

Refunds