Skip to main content

​
Overview

Use this endpoint to create a hosted checkout session for your customer. Kiotapay returns a checkout URL that you can redirect the customer to, open in a browser, or present as a pay button link inside your app. This is useful when you want Kiotapay to handle the payment collection flow for methods such as:
  • CARD
  • MPESA_STK
Once the session is created, your system receives a response containing:
  • a public checkout session ID
  • a unique checkout reference
  • the hosted checkout URL
  • the current status of the session

​
Endpoint

POST https://api.kiotapay.co/api/sandbox/v1/checkout-sessions
Use the sandbox base URL for testing. Switch to your production base URL when you go live.

​
Authentication

Send your bearer token in the Authorization header. 
Authorization: Bearer <your_access_token>

​
Headers

​
Authorization
string
required
Bearer token used to authenticate your API request.
​
Content-Type
string
required
Must be application/json.

​
Request body

​
amount
number
required
Amount to be charged. Provide the full monetary amount in the currency specified.
​
currency
string
required
Three-letter currency code. Example: KES.
​
description
string
required
Human-readable description of the payment. Example: Payment for order #12345.
​
successUrl
string
required
URL where the customer should be redirected after a successful payment.
​
cancelUrl
string
required
URL where the customer should be redirected if they cancel the payment flow.
​
paymentMethods
array[string]
required
List of allowed payment methods for this checkout session. Example: ["CARD", "MPESA_STK"].
​
externalReference
string
Your own external reference for reconciliation, such as an order ID.
​
customerEmail
string
Customer email address.
​
customerPhone
string
Customer phone number in international format. Example: +237612345678.
​
paymentReference
string
Reference shown or associated with the payment. Often this matches your order or invoice reference.
​
callbackUrl
string
Webhook URL that Kiotapay can notify with payment updates for this checkout session.

​
Example request

curl --location 'https://api.kiotapay.co/api/sandbox/v1/checkout-sessions' \
--header 'Device-Id: example-my-device-id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data-raw '{
  "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": "+237612345678",
  "paymentReference": "ORDER-12345-EXT",
  "callbackUrl": "https://webhook.site/dd1b4efd-a1a7-4aac-9b23-0dc13dec525f"
}'

​
Example response

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

​
Response fields

​
id
uuid
Public checkout session ID.
​
checkoutUrl
string
Hosted Kiotapay checkout URL. Redirect your customer to this link to complete payment.
​
checkoutRef
string
Unique Kiotapay checkout reference for support, reconciliation, and tracking.
​
status
enum
Current status of the checkout session.

​
Checkout session statuses

​
PENDING
string
The checkout session has been created and is waiting for the customer to start or complete payment.
​
REQUIRES_CUSTOMER_ACTION
string
The payment needs an additional step from the customer, such as completing card authentication or approving an STK prompt.
​
PROCESSING
string
The payment is being processed.
​
SUCCEEDED
string
The payment completed successfully.
​
FAILED
string
The payment failed.
​
EXPIRED
string
The checkout session expired before payment was completed.

​
How it works

1

Create a checkout session

Call the endpoint with the payment details, redirect URLs, customer details, and allowed payment methods.
2

Receive the checkout URL

Kiotapay returns a checkoutUrl in the response.
3

Redirect or open the page

Send the customer to the hosted checkout page using the returned URL.
4

Track payment result

Use your successUrl, cancelUrl, and optional callbackUrl to track the final outcome.

​
Redirect example

After creating the checkout session on your backend, send the returned checkoutUrl to your frontend and redirect the user. 
window.location.href = checkoutUrl;

​
Best practices

  • Always generate a unique externalReference for each order or invoice.
  • Store the returned id and checkoutRef in your database for reconciliation.
  • Prefer using a callbackUrl so your backend can receive asynchronous payment updates.
  • Do not rely only on frontend redirects for final payment confirmation.
  • Validate that the final payment status is SUCCEEDED before fulfilling an order.

​
Notes

  • checkoutUrl is the main link your customer should open to complete payment.
  • successUrl and cancelUrl are customer-facing redirect URLs.
  • callbackUrl is intended for server-to-server notifications.
  • The initial returned status may be PENDING, even though the payment later moves to another state.

​
Sample integration flow

​
Error handling

Your integration should be prepared to handle standard API errors such as:
  • invalid authentication token
  • missing required headers
  • invalid payload fields
  • unsupported payment methods
  • invalid callback or redirect URLs
A typical error response may look like: 
{
  "message": "Invalid request payload",
  "errors": {
    "amount": ["amount must be greater than 0"],
    "currency": ["currency is required"]
  }
}

​
Full request schema

{
  "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": "+237612345678",
  "paymentReference": "ORDER-12345-EXT",
  "callbackUrl": "https://merchant.example.com/api/webhooks/kiotapay"
}

​
Full response schema

{
  "id": "uuid",
  "checkoutUrl": "string",
  "checkoutRef": "string",
  "status": "PENDING | REQUIRES_CUSTOMER_ACTION | PROCESSING | SUCCEEDED | FAILED | EXPIRED"
}