Skip to main content

​
Get Checkout Session

Retrieve the details of an existing checkout session. This endpoint is typically used by frontend applications to load the checkout page data using the session ID.

​
Endpoint

GET https://api.kiotapay.co/api/sandbox/v1/checkout-sessions/{checkoutSessionId} Example: GET https://api.kiotapay.co/api/sandbox/v1/checkout-sessions/cf488410-37d5-4dba-9b27-8d74f3ad8ae4

​
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.

​
Path parameters

​
checkoutSessionId
uuid
required
The public checkout session ID returned when creating the checkout session.

​
Example request

curl --location 'https://api.kiotapay.co/api/sandbox/v1/checkout-sessions/cf488410-37d5-4dba-9b27-8d74f3ad8ae4' \
--header 'Device-Id: example-my-device-id' \
--header 'Authorization: Bearer <your_access_token>'

​
Example response

{
  "id": "cf488410-37d5-4dba-9b27-8d74f3ad8ae4",
  "amount": 1500,
  "currency": "KES",
  "description": "Payment for order #12345",
  "customerEmail": "customer@example.com",
  "customerMsisdn": "+237612345678",
  "externalRef": "ORDER-12345-EXT",
  "paymentMethods": ["CARD", "MPESA_STK"],
  "merchantDisplayName": "Example Store",
  "merchantLogoUrl": "https://cdn.example.com/logo.png",
  "status": "PENDING"
}

​
Response fields

​
id
uuid
Public checkout session identifier.
​
amount
number
Amount to be paid in the specified currency.
​
currency
string
Three-letter currency code (ISO format). Example: KES.
​
description
string
Description of the payment or order.
​
customerEmail
string
Customer email associated with the checkout session.
​
customerMsisdn
string
Customer phone number in international format.
​
externalRef
string
Merchant-provided reference such as an order ID.
​
paymentMethods
array[string]
List of allowed payment methods for this checkout session.
​
merchantDisplayName
string
Display name of the merchant shown on the hosted checkout page.
​
merchantLogoUrl
string
Logo URL displayed on the checkout page.
​
status
enum
Current checkout session status.

​
Typical usage

This endpoint is usually called by the hosted checkout frontend to load session information such as:
  • amount
  • merchant branding
  • supported payment methods
  • checkout status
This ensures the payment page displays accurate transaction details to the customer.

​
Example integration flow