Skip to main content
GET
Retrieve a checkout session

Authorizations

Authorization
string
header
required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Path Parameters

checkout_id
string
required

The checkout ID returned when the session was created.

Response

Checkout session retrieved successfully.

Checkout session details returned by GET /v1/checkout-sessions/{checkout_id}.

checkout_id
string
required

Unique checkout identifier.

Example:

"chk_1M2N3o4P5q6R7s8T"

status
enum<string>
required

Current lifecycle status of the checkout session. open: awaiting customer payment, where every new session starts. completed: payment succeeded, a terminal state. expired: the session window elapsed before payment, a terminal state. cancelled: cancelled before completion, a terminal state.

Available options:
open,
completed,
expired,
cancelled
Example:

"completed"

amount
string
required

Total amount in currency.

Example:

"50.00"

currency
string
required

Base currency code.

Example:

"USD"

customer
object
required

The customer attached to the checkout.

created_at
string<date-time>
required

ISO 8601 creation timestamp.

Example:

"2026-01-24T14:30:00.000Z"

updated_at
string<date-time>
required

ISO 8601 last-updated timestamp.

Example:

"2026-01-24T14:35:00.000Z"

recurring
object | null

Present only for a subscription checkout; null for a one-time checkout.

payment_status
enum<string> | null

Payment lifecycle for the checkout. requires_payment_method, requires_confirmation, requires_action, processing, succeeded, failed, or canceled.

Available options:
requires_payment_method,
requires_confirmation,
requires_action,
processing,
succeeded,
failed,
canceled
Example:

"requires_payment_method"

source_type
string | null

What created the checkout, e.g. CHECKOUT_SESSION or API.

Example:

"CHECKOUT_SESSION"

reference
string | null

The reference you set when you created the session. null if you set none.

Example:

"order_9876"

charge
object | null

The payment created by this checkout, once payment has been attempted. null before then.

payment_method
string | null

The payment method selected for the checkout, if any. For every method except card, this is the exact corridor collected, such as NGN_BANK_TRANSFER, MOMO_GHS, or CRYPTO. Card charges report CARD rather than USD_CARD or NGN_CARD; read the currency to tell which card corridor collected it.

Example:

"NGN_BANK_TRANSFER"

customer_details
object | null

What the buyer supplied; present whenever an identity was collected, record or no record. null before then.

success_url
string<uri> | null

URL the customer is redirected to after successful payment.

Example:

"https://yourapp.com/success"

cancel_url
string<uri> | null

URL the customer is redirected to if they cancel.

Example:

"https://yourapp.com/cancel"

products
object[] | null

Resolved product line items. Populated for CART sessions; may be null for SELECTION sessions before the customer picks a product.

billing_currency
string | null

Currency the customer selected for billing.

Example:

"NGN"

platform_fee
string | null

The platform's cut of this sale, in the base currency of the sale. The key is always present; it reads null, not "0.00", on a checkout that carries no fee, and on a checkout that split the sale with transfer_data.amount instead. See Platform fees.

Example:

"20000.00"

destination_amount
string | null

The seller's contracted share of this sale, in the base currency of the sale. Null on a checkout that carries no split, and on one that split the sale with platform_fee instead.

Example:

"80000.00"

session_mode
enum<string> | null

How products are presented. CART sums a fixed set of items; SELECTION lets the customer pick one from a group.

Available options:
CART,
SELECTION
Example:

"CART"

metadata
object | null

Public metadata you attached at session creation.

Example:
expires_at
string<date-time> | null

ISO 8601 expiry timestamp.

Example:

"2026-01-24T15:30:00.000Z"

completed_at
string<date-time> | null

ISO 8601 timestamp when the session was completed.

Example:

"2026-01-24T14:35:00.000Z"