Hosted checkout & payment links
The hosted checkout gives your customer a ready-made payment page. You create an invoice, send the customer the returned checkoutUrl, and the page handles M-Pesa STK push, manual M-Pesa (paybill), Airtel Money, card, bank transfer and wallet. It is the fastest way to collect a payment without building any payment UI.
1. Create an invoice
POST /v1/checkout/invoices, with your company Bearer token. Do this on your server: the amount is fixed here, so it can never be set by a browser.
curl -X POST https://sandbox.merchants.taifapay.africa/v1/checkout/invoices \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 1500,
"currency": "KES",
"accountReference": "INV-1001",
"description": "Order #1001 - 2x widget",
"customerName": "Jane Doe",
"customerEmail": "jane@example.com",
"customerPhone": "254712345678",
"methods": ["mpesa_stk", "card"],
"returnUrl": "https://merchant.example.com/thanks",
"expiresInMinutes": 30
}'
| Field | Required | Notes |
|---|---|---|
amount | yes | What the customer pays. They can never change it. |
accountReference | yes | Your unique reference. Joined to your company's identifier letters it forms the public invoice number (ABC + INV-1001 → ABCINV-1001), so it must be unique within your company and cannot be reused, even after expiry. Letters, numbers, ., _ and - only. |
currency | no | Three-letter code. Defaults to KES. |
description | no | Shown on the page and recorded on the transaction. |
externalId | no | Your own id, for reconciliation. Defaults to accountReference. |
customerName, customerEmail | no | Shown on the page. Email is encrypted at rest. |
customerPhone | no | Pre-fills the STK prompt. Encrypted at rest. |
methods | no | Any of mpesa_stk, mpesa_manual, airtel_money, card, bank, wallet. Omit to offer every method your company has a configured gateway for. |
returnUrl | no | HTTPS URL the Done button goes to. Ignored when the page is embedded. |
expiresInMinutes | no | 1 to 10080 (seven days). Default 30. |
{
"message": "Invoice created",
"invoice": {
"transactionId": "a3f1c2d4-5e6b-7a8c-9d0e-1f2a3b4c5d6e",
"checkoutUrl": "https://pay.taifapay.africa/pay/ABCINV-1001",
"invoiceNo": "ABCINV-1001",
"amount": 1500,
"currency": "KES",
"status": "open",
"methods": ["mpesa_stk", "card"],
"expiresAt": "2026-07-17T12:30:00.000Z"
}
}
The transactionId is created with the invoice and settles whichever method the customer eventually picks. Store it. It is the one id you track regardless of payment method.
An invoice only offers methods whose gateway is configured and active for your company. If you ask for a method you do not have, the invoice is still created without it. Read the methods array on the response instead of assuming.
You can also create invoices from the portal under Payment links, which is useful for one-off links you send by message.
2. Send the customer to pay
Pick one. Both use the same page.
- Option A: Redirect or share the link
- Option B: Embed in your page
The simplest option, with no extra dependency. Send the customer the checkoutUrl by SMS, email or WhatsApp, or redirect to it from your site:
res.redirect(invoice.checkoutUrl);
The page is public and needs no authentication. The customer picks a method and pays, and the page keeps itself updated, showing the STK prompt status and then the receipt. Its Done button goes to your returnUrl. See Inside the checkout page for every screen.
Keep the customer on your own page by rendering checkout in an iframe with @taifapay/payments-js. Pass the public invoiceNo, never your secret and never the full URL.
npm install @taifapay/payments-js
import { mountCheckout } from "@taifapay/payments-js";
const handle = mountCheckout("#pay", {
invoiceNo: invoice.invoiceNo, // from your server, e.g. "ABCINV-1001"
host: "https://sandbox-pay.taifapay.africa", // sandbox; omit for production
onSuccess: ({ receiptNumber }) => showThanks(receiptNumber),
onFailure: ({ message }) => showError(message),
onExpired: () => showExpired(),
});
// later, e.g. on unmount or route change:
handle.unmount();
With no bundler:
<script src="https://unpkg.com/@taifapay/payments-js"></script>
<div id="pay"></div>
<script>
TaifaPay.mountCheckout("#pay", { invoiceNo: "ABCINV-1001", onSuccess: console.log });
</script>
Card data, personal data and your credentials never touch your page, because everything is collected on the Taifa origin inside the iframe.
Before this works in production: your site's origin must be allow-listed for framing, and host must match the environment that created the invoice.
| Callback | Fires when |
|---|---|
onReady | The page has loaded. |
onSuccess({ method, receiptNumber }) | The payment was approved. A UX signal only. |
onFailure({ message }) | An attempt failed, such as a declined card. The invoice usually stays payable. |
onExpired | The link can no longer be paid. |
When embedded, the page's Done button does nothing and returnUrl is not used. Navigate or update your UI from onSuccess.
onSuccess and returnUrl only tell you the customer's browser saw an approval. Always confirm with a webhook or a poll before releasing goods.
3. Know when it is paid
Use either or both.
- Webhooks (recommended). You receive a signed event when the transaction resolves. See Webhooks and Webhook events.
- Polling.
GET /v1/transactions/{transactionId}untilstatusisCOMPLETEDorFAILED.
For cards, the sequence has an extra step because the money reaches you after the acquirer settles. See Card payments.
You can also fetch the invoice itself:
curl https://sandbox.merchants.taifapay.africa/v1/checkout/invoices/ABCINV-1001 \
-H "Authorization: Bearer $ACCESS_TOKEN"
It returns the session status (open, processing, complete, failed, expired or cancelled), the selected method and timestamps. Invoices are scoped to your company, so you can never read another merchant's.
The checkout/public/... endpoints that power the hosted page sit behind CSRF and rate-limit guards tied to a live session, and are not meant for server-to-server calls. Integrate with invoice creation plus webhook or poll, as shown above.
Expiry
An invoice past its expiresAt can no longer be paid, and its transaction is marked FAILED shortly after. If the customer still wants to pay, create a new invoice with a new accountReference.
Related
- Inside the checkout page: every screen the customer can land on
- Card payments and Card-only invoices
- Webhooks