Retrieve a checkout session
Read a session and its charge. A lookup, so a decline reads as 200 with a failed charge.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Response
Success.
The merchant's own business name for the pay page header, or null (neutral fallback).
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.
The caller's number this session was opened for. Consumers holding only the checkout token (which carries no payload) read it from here.
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.
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.
test, live required, optional, none 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.
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.
Named for the object it describes: the CHARGE has its own status below.
open, complete, expired 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.
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.