Skip to main content

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
}'
FieldRequiredNotes
amountyesWhat the customer pays. They can never change it.
accountReferenceyesYour 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.
currencynoThree-letter code. Defaults to KES.
descriptionnoShown on the page and recorded on the transaction.
externalIdnoYour own id, for reconciliation. Defaults to accountReference.
customerName, customerEmailnoShown on the page. Email is encrypted at rest.
customerPhonenoPre-fills the STK prompt. Encrypted at rest.
methodsnoAny of mpesa_stk, mpesa_manual, airtel_money, card, bank, wallet. Omit to offer every method your company has a configured gateway for.
returnUrlnoHTTPS URL the Done button goes to. Ignored when the page is embedded.
expiresInMinutesno1 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 stable

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.

Check the methods you got back

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.

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.

A browser signal is not proof of payment

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} until status is COMPLETED or FAILED.

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 public checkout endpoints are not for you

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.