Get Checkout Session

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