Checkout

Checkout, the unified payment SDK, is the quickest way to accept payments. Your server creates a session, you redirect the customer to the link Tanda returns, and the customer pays by M-PESA, Airtel Money or bank transfer on a Tanda-hosted page. Tanda handles the phone prompt and bank details for you.

1. Create a session

Call Create checkout session from your server.

curl -X POST https://api.tandapay.io/api/b2b/fiat/payment-sdk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "chargeCurrency": "KES",
    "walletCurrency": "KES",
    "externalReference": "order_10045",
    "customerId": "customer_123",
    "prefillData": {
      "firstName": "Brian",
      "lastName": "Otieno",
      "email": "brian@example.com",
      "phoneNumber": "+254712345678"
    },
    "successRedirectUrl": "https://merchant.co.ke/checkout/success",
    "failureRedirectUrl": "https://merchant.co.ke/checkout/failed",
    "cancelRedirectUrl": "https://merchant.co.ke/checkout/cancelled"
  }'

app.post("/checkout", async (req, res) => {
  const order = await createOrder(req.body); // your own order record

  const session = await fetch("https://api.tandapay.io/api/b2b/fiat/payment-sdk", {
    method: "POST",
    headers: { Authorization: `Bearer ${await getToken()}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      amount: order.total,
      chargeCurrency: "KES",
      walletCurrency: "KES",
      externalReference: order.id,
      customerId: order.customerId,
      prefillData: { firstName: order.firstName, lastName: order.lastName, email: order.email },
      successRedirectUrl: `https://merchant.co.ke/orders/${order.id}/success`,
      failureRedirectUrl: `https://merchant.co.ke/orders/${order.id}/failed`,
      cancelRedirectUrl: `https://merchant.co.ke/orders/${order.id}`,
    }),
  }).then((r) => r.json());

  await saveTransactionId(order.id, session.data.transactionId);
  res.redirect(303, session.data.paymentSdkLink);
});

session = requests.post(
    "https://api.tandapay.io/api/b2b/fiat/payment-sdk",
    headers={"Authorization": f"Bearer {get_token()}"},
    json={
        "amount": order.total,
        "chargeCurrency": "KES",
        "walletCurrency": "KES",
        "externalReference": order.id,
        "successRedirectUrl": f"https://merchant.co.ke/orders/{order.id}/success",
        "failureRedirectUrl": f"https://merchant.co.ke/orders/{order.id}/failed",
        "cancelRedirectUrl": f"https://merchant.co.ke/orders/{order.id}",
    },
).json()

save_transaction_id(order.id, session["data"]["transactionId"])
return redirect(session["data"]["paymentSdkLink"])

Response

{
  "success": true,
  "message": "Transaction created successfully",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "paymentSdkLink": "https://gateway.tandapay.io/sdk/transaction/aB3dE5fG7hJ9kL1mN2pQ"
  }
}

Options

string

Show only one method: momo (M-PESA and Airtel Money) or bank. Leave it out to let the customer choose from everything enabled on your account.

string

Your own ID for the customer. It comes back on the transaction, so you can match payments to customers.

object

firstName, lastName, email, accountName and phoneNumber (E.164, e.g. +254712345678) to fill in for the customer. Prefilled values can’t be edited on the payment page, so only send details you’re sure of.

string

Where Tanda sends the customer after a successful payment.

string

Where Tanda sends the customer after a failed payment.

string

Where Tanda sends the customer if they cancel. All three redirect URLs are optional but recommended.

Add your own reference to the redirect URLs, for example https://merchant.co.ke/checkout/success?ref=order_10045, so the page knows which order to look up.

2. Redirect the customer

Send the customer to paymentSdkLink exactly as returned. Don’t build or modify the URL yourself. On the page they pick M-PESA, Airtel Money or bank transfer and complete the payment.

3. Handle the return

When the customer finishes, Tanda redirects them to the matching URL. Use this page to show a message such as “We’re confirming your payment”.

A redirect to your success URL is not proof of payment. Customers can open that URL directly. Always confirm the status from your server before fulfilling.

4. Confirm and fulfil

You’ll receive transaction_updated webhooks as the payment progresses. Before you fulfil, confirm the outcome from your server with Get transaction, using the transactionId or your externalReference.

curl https://api.tandapay.io/api/b2b/transactions/aB3dE5fG7hJ9kL1mN2pQ \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "success": true,
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "externalReference": "order_10045",
    "customerId": "customer_123",
    "type": "deposit",
    "method": "momo",
    "amount": 1500,
    "chargeCurrency": "KES",
    "walletCurrency": "KES",
    "chargeStatus": "successful",
    "status": "SUCCESSFUL",
    "fullTimestamp": "2026-10-28T09:14:22.000Z"
  }
}

`chargeStatus`	Meaning	What to do
`pending`	The customer hasn’t finished, or a step (phone prompt, bank transfer) is outstanding.	Wait. Show “confirming your payment”.
`successful`	Money received.	Fulfil the order.
`failed`	The payment didn’t go through.	Let the customer try again with a new session and a new `externalReference`.

Good practice

Create a new session, with a new externalReference, for every attempt.
Store transactionId against your order as soon as the session is created, so webhooks can find the order.
Make your fulfilment idempotent: the same webhook can arrive more than once.
Use Get checkout methods if you want to show method logos before the customer leaves your site.

Test it

In sandbox, the value the customer enters on the hosted page decides the outcome. See Testing.

Get started

Accept payments

Send payouts

Webhooks

Go live

1. Create a session

Options

2. Redirect the customer

3. Handle the return

4. Confirm and fulfil

Good practice

Test it

​1. Create a session

​Options

​2. Redirect the customer

​3. Handle the return

​4. Confirm and fulfil

​Good practice

​Test it

1. Create a session

Options

2. Redirect the customer

3. Handle the return

4. Confirm and fulfil

Good practice

Test it