Create a checkout session

Server URLloading...

POST

/api/sandbox/v1/checkout-sessions

Send

Authorization

Body

Create a hosted checkout session and get back a URL to send your customer to. Kiotapay renders the payment page, collects the money by card or M-Pesa STK, and reports the result back to you.

Use this when you would rather not build a payment flow yourself.

How it works

1. Call this endpoint with the amount, redirect URLs and allowed payment methods.
2. Kiotapay returns a checkoutUrl.
3. Redirect the customer there — window.location.href = checkoutUrl.
4. The customer pays and is returned to your successUrl or cancelUrl.
5. Kiotapay POSTs the final result to your callbackUrl.

Getting this right

• Generate a unique externalReference per order or invoice.
• Store the returned id and checkoutRef for reconciliation.
• Confirm payment from the callback, not the browser redirect. A customer can close the tab before being redirected, and a redirect can be forged.
• Only fulfil an order once the status is SUCCEEDED.

Response Body

curl -X POST "https://example.com/api/sandbox/v1/checkout-sessions" \  -H "Content-Type: application/json" \  -d '{    "amount": 1500,    "currency": "KES",    "description": "Payment for order #12345",    "successUrl": "https://portal.example.com/checkout/success",    "cancelUrl": "https://portal.example.com/checkout/cancel",    "paymentMethods": [      "CARD",      "MPESA_STK"    ],    "externalReference": "ORDER-12345-EXT",    "customerEmail": "customer@example.com",    "customerPhone": "+254712345678",    "paymentReference": "ORDER-12345-EXT",    "callbackUrl": "https://merchant.example.com/api/webhooks/kiotapay"  }'

{  "id": "1f1f7d84-5a65-4f76-98bc-c7c50dbe1234",  "checkoutUrl": "https://checkout.kiotapay.co/session/chk_01JXYZABCDEFG123456",  "checkoutRef": "CHK-20260316-000123",  "status": "PENDING"}