Skip to main content
GET
Retrieve a checkout session

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

checkout_session_id
string
required

Response

Success.

amount_cents
number
business_name
string | null

The merchant's own business name for the pay page header, or null (neutral fallback).

caller_first_name
string | null

The caller's first name when they are a known person, so a payment line can greet them the same way the pay page does. Null for a genuinely unknown caller. Identity only: whether a card exists is a separate question answered by cards.

caller_phone
string | null

The caller's number this session was opened for. Consumers holding only the checkout token (which carries no payload) read it from here.

cards
object[]

Cards chargeable AT THIS MERCHANT, newest first, the same shape create_checkout returns. Present so a payment line holding only the checkout token can offer the saved card from this read. Empty when no payment is required or the session is already settled or expired.

charge
object | null
checkout_session_id
string
currency
string
default_card_id
string | null
environment
enum<string>

The environment this session belongs to: the mode of the checkout token used to read it (test or live). It is the single source of truth for a hosted page, which renders its config in this environment rather than re-deriving it, so business_name and tokenization below are always computed here and cannot drift to the wrong environment.

Available options:
test,
live
failure_message
string | null
merchant_id
string
metadata
object | null
order_id
string | null
payment_required
enum<string>
Available options:
required,
optional,
none
platform_call_id
string | null
processor
string | null

The merchant's processor (square, clover, …), so the pay page builds the right card source without a separate lookup. Null if the merchant is gone.

return_to
string | null
screen
object | null

What screening knows about this caller, and why.

decision is step_up only when a positive bad signal was found: the caller's number was ported or swapped within the last seven days, or the original call's carrier attestation came back C or Failed. Every such cause is listed in reasons. A missing signal is never a cause, so a lookup that errored or timed out lands in notes and leaves the decision allow: an outage upstream must not cost an honest caller their saved card.

Null until anything has resolved. Read it to understand why a caller was sent a link instead of being offered a saved card; never speak any of it to the caller.

session_status
enum<string>

Named for the object it describes: the CHARGE has its own status below.

Available options:
open,
complete,
expired
success_message
string | null
tokenization
object | null

The browser-side, PUBLISHABLE tokenization key for this merchant (Square app id + seller location, or Clover PAKMS public key), computed in environment. Null when the processor needs none or the config is incomplete. Same shape as the merchant status endpoint.

voice
string | null

The payment line reads these three from this session read, not the checkout token. voice is the merchant's matched TTS descriptor (or null for the default voice); success_message/failure_message are the developer's create_checkout closing lines, spoken by the line at charge success / decline. All null when unset.