Checkout

Waftpay Checkout is a hosted payment page. You create a checkout session from your server, send your customer to the page we host, and we handle the payment experience — mobile money (M-PESA STK & paybill), bank/PesaLink, partial payments, retries, and session expiry. Card and payment details never touch your site. There are two ways to bring the customer to it:

Redirect (this guide)

Send the browser to the checkout_url we return. Simplest to ship. The customer pays on checkout.waftpay.io and is redirected back to you.

Embedded overlay

Keep the customer on your page. Our loader script opens the checkout in an overlay and gives you JavaScript callbacks (onSuccess, onFailure, …).

Either way, you never build the payment UI. You only (1) create the session server-side and (2) place the customer in front of our page.See it working end to end in the WaftStore demo → — a sample store that creates a session and hands off to this checkout page.

How it works

Authenticate (server-side)

Get a product-scoped Bearer token from Get Authentication Token. Cache it and refresh only on expiry. Your consumer_key/consumer_secret stay on your server — never in the browser.

Create a checkout request (server-side)

Call Create Checkout Request with the customer, amount, and your redirect + callback URLs. You get back a checkout_url and expires_at.

Send the customer to the page

Redirect the browser to checkout_url (or use the embedded overlay).

Receive the callback (source of truth)

Waftpay POSTs the final result to your callback_url. Use this — not the browser redirect — to fulfil the order.

Handle the return redirect

We send the customer back to your success_redirect_url or fail_redirect_url for the on-screen outcome.

Prerequisites

Collections service enabled on your account.
A product-scoped Bearer token from Get Authentication Token.
A publicly reachable callback_url to receive the final result. See Webhooks overview.

1. Create the checkout request

Do this on your server — it uses your secret Bearer token.

POST https://api.waftpay.io/checkout/v1/request

POST https://dev.waftpay.io/checkout/v1/request

Required headers

Authorization: Bearer <token>
Content-Type: application/json

Request body (example)

{
  "customer": {
    "first_name": "Amina",
    "other_names": "Kariuki",
    "email": "amina.kariuki@example.com",
    "phone_number": "254733112244"
  },
  "timestamp": "2025-11-18T09:45:30.540Z",
  "checkout_reference": "CHK623581942",
  "payment_reference": "INV20478519",
  "msisdn": "254711223344",
  "country": "KEN",
  "currency": "KES",
  "amount": 1750,
  "mode": "redirect",
  "callback_url": "https://store.example.com/waftpay/callback",
  "success_redirect_url": "https://store.example.com/order/complete",
  "fail_redirect_url": "https://store.example.com/order/failed",
  "meta_data": {
    "order_id": "ORDER-39182"
  },
  "extra_params": {
    "language": "en",
    "expiry": "2026-02-14 18:30:00",
    "strict_amount": true
  }
}

See the full field reference. The fields that most affect behaviour:

checkout_reference — must be unique per request.
extra_params.expiry — optional; a default is applied if omitted.
extra_params.strict_amount — true requires full payment; false lets the customer pay in parts.

Response (accepted)

{
  "code": "200",
  "status": "SUCCESS",
  "description": "Request accepted",
  "data": {
    "checkout_url": "https://checkout.waftpay.io/checkout/OTRkN2I2YTQtZTliZi00MDI0LTk2N2ItZGI1MTQ0NmU2NzY2",
    "expires_at": "2026-03-02T14:08:41.921Z"
  }
}

The last path segment of checkout_url is the request token for this session. You pass the whole checkout_url to redirect, or just the token to the embedded overlay. Generate it on your server — never in the browser.

On your server (example)

This is the merchant’s entire integration — the same on your server whether you then redirect or embed. Re-price the cart from your own catalogue (never trust client totals), cache the Bearer token, create the request, and return the checkout_url and token to the browser. This mirrors the WaftStore demo’s POST /api/checkout route.

// POST /api/checkout  (server-side only — secrets never reach the browser)
export async function POST(request: Request) {
  const { customer, items } = await request.json();

  // 1. Re-price the cart from YOUR canonical product list.
  const amount = priceCart(items); // throws on invalid items

  // 2. Unique references for this checkout.
  const ts = Date.now();
  const checkoutReference = `CHK-${ts}`;

  // 3. Bearer token (cached in memory, refreshed only on expiry).
  const token = await getWaftpayToken();

  // 4. Create the checkout request.
  const res = await fetch("https://api.waftpay.io/checkout/v1/request", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer,
      timestamp: new Date(ts).toISOString(),
      checkout_reference: checkoutReference,
      payment_reference: `ORD-${ts}`,
      msisdn: customer.phone_number,
      country: "KEN",
      currency: "KES",
      amount,
      mode: "redirect",
      callback_url: process.env.CHECKOUT_CALLBACK_URL,
      success_redirect_url: `${appUrl}/checkout/success?ref=${checkoutReference}`,
      fail_redirect_url: `${appUrl}/checkout/failed?ref=${checkoutReference}`,
      meta_data: { order_id: `ORDER-${ts}` },
      extra_params: { language: "en", strict_amount: false },
    }),
  });

  const { data } = await res.json();
  // The token is the last path segment of checkout_url — hand it to the
  // browser for redirect (checkout_url) or Waftpay.mount({ token }).
  const token_ = new URL(data.checkout_url).pathname.split("/").pop();
  return Response.json({ checkout_url: data.checkout_url, token: token_ });
}

getWaftpayToken() exchanges consumer_key + consumer_secret at Get Authentication Token for a short-lived Bearer token, caches it in memory, and refreshes ~60s before expiry (retrying once if a cached token is rejected).

2. Send the customer to the page

Redirect the browser to the checkout_url:

// after your server returns the checkout_url
window.location.href = checkoutUrl;

That’s it — Waftpay renders the page, shows your business name and the amount, lists the payment methods enabled for your account, runs a countdown against the session expiry, and (when strict_amount is false) lets the customer settle the balance in parts. Prefer to keep the customer on your own page? Use the embedded overlay instead of redirecting.

3. Receive the callback (source of truth)

When the payment resolves, Waftpay POSTs the final result to your callback_url. Fulfil the order from this callback, not from the browser redirect (a customer can close the tab before returning).

{
  "status": "SUCCESS",
  "code": "102",
  "description": "Transaction successfully processed",
  "results": {
    "transaction_reference": "CHK1769954123895429017",
    "checkout_status": "FULLY_PAID",
    "amount": 1750,
    "payments": [
      {
        "status": "SUCCESS",
        "result_code": "0",
        "result_description": "The service request is processed successfully.",
        "amount": 1750,
        "account": "254733112244",
        "total_charges": 140,
        "total_amount": 1750,
        "service_code": "SAF_COL_KE",
        "external_reference": "Q8MN7RX4J2",
        "payment_uuid": "197563911284320774",
        "time_processed": 1769954132.447
      }
    ],
    "metadata": "{\"order_id\":\"ORDER-39182\"}"
  }
}

results.checkout_status — FULLY_PAID, PARTIALLY_PAID, or FAILED.
results.payments[] — one entry per payment (more than one if the customer paid in parts).
results.metadata — your meta_data, echoed back as a JSON string.

Verify the signature and respond 200 quickly. See Verify signature and Retries & idempotency.

4. Handle the return redirect

After paying, the customer lands on your success_redirect_url or fail_redirect_url. Use these pages for the on-screen message only; confirm fulfilment from the callback. If you need to double-check a specific order, use status checks.

Testing

Use the sandbox base URL https://dev.waftpay.io and a tool like webhook.site for your callback_url while developing. See Environments.

WaftStore demo — a working merchant integration
Create Checkout Request API
Embedded checkout
Get Authentication Token
Webhooks overview
Errors

Introduction

Getting started

Guides

Webhooks

Redirect (this guide)

Embedded overlay

How it works

Prerequisites

1. Create the checkout request

On your server (example)

2. Send the customer to the page

3. Receive the callback (source of truth)

4. Handle the return redirect

Testing

Redirect (this guide)

Embedded overlay

​How it works

​Prerequisites

​1. Create the checkout request

​On your server (example)

​2. Send the customer to the page

​3. Receive the callback (source of truth)

​4. Handle the return redirect

​Testing

​Related links

How it works

Prerequisites

1. Create the checkout request

On your server (example)

2. Send the customer to the page

3. Receive the callback (source of truth)

4. Handle the return redirect

Testing

Related links