Create Checkout Session

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: [phone].

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": "[e-mail]",
  "customerPhone": "[phone]",
  "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": "[e-mail]",
  "customerPhone": "[phone]",
  "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"
}