Skip to main content
POST
Start a checkout session and get a token to collect payment

Authorizations

Authorization
string
header
required

Per-client API key (M2M). Presented as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

Required on payment writes. A replay with the same key returns the original result.

Minimum string length: 8
X-Brand-Id
string
required

The brand this request is scoped to. It is validated against your authenticated account; an unknown or unauthorized brand is rejected. The brand is never taken from the request body.

Pattern: ^brd_[A-Za-z0-9][A-Za-z0-9_-]*$
x-held-capability
string

Proof that this caller holds the enrollment named in the body: the capability issued for that enrollment when it was created (or re-issued at the identity step), sent exactly as you received it. It is checked before checkout runs. A checkout without a valid capability for the enrollment it names is refused with 404 and nothing is created. Treat it as a secret: send it only on this header, never in a URL, a body or a log.

Body

application/json

The complete input to start a checkout session. Send the offering reference, the enrollment id, an optional promo code, and — when the purchase is one that will be delivered — the opaque delivery-destination reference. Nothing else. The server determines the price, the fees, and how the charge is routed; a request that adds a price, fee, or routing field is rejected, and there is deliberately no field for a card number or security code. There is likewise deliberately no field for a name, an email address, a phone number, or a postal address: this operation takes a REFERENCE to a delivery destination, never the destination itself.

journey_id
string
required

the enrollment id this checkout belongs to

Pattern: ^jny_[A-Za-z0-9][A-Za-z0-9_-]*$
offering_ref
string
required

the offering to purchase, taken from the enrollment link. Each supply length (for example 1, 3, 6, or 12 months) is its own offering with its own reference; selecting a plan means sending a different offering reference, not a quantity or term field.

destination_ref
string

WHERE THIS ORDER IS TO BE DELIVERED, AS A REFERENCE — never as an address. The member enters their delivery details once, they are stored in the clinical vault, and the vault answers with this reference. Checkout records the reference and nothing else, so the address is readable in exactly one place and this operation carries no personal information at all. Optional: an order with no delivery leg omits it. THE REFERENCE IS OPAQUE, AND THAT IS A PROPERTY OF THE SHAPE, NOT A CONVENTION. It is exactly the reference the platform returned when the delivery details were saved: dest_ followed by a hyphenated hex UUID (8-4-4-4-12 hex digits), one fixed total length of 41 characters for every destination that has ever existed, so the reference's LENGTH tells a reader nothing, and an alphabet of 0–9, a–f and - at fixed positions only, in which the space, the comma, the #, the uppercase letter and the letters g through z that a postal address is written in cannot be spelled at all. A request that sends an address here — verbatim, encoded, or wrapped — is refused, and the refusal repeats none of what was sent. NOT the charge topology. Commerce's topology field also uses the word destination (a destination charge settles on the platform and transfers to the client's connected account, counterparty_account). That is about where MONEY goes. This is about where a PACKAGE goes. The two are unrelated and neither is derivable from the other. Recorded, not acted on: storing a destination is not shipping to it. This reference is order provenance. Fulfillment resolves the destination from the vault when it ships.

Pattern: ^dest_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
promo
string

an optional promo code. Promotions are not yet available, so sending one returns a 422 rather than quietly charging full price.

Response

the session was created; use the returned client token to collect payment

The created checkout session. Everything here is safe to show in the patient's browser. The client token is returned only once, in this response, to collect payment; it is never returned again by the status endpoint.

amount
object
required

the amount the patient will be charged, as determined by the server

client_secret
string
required

a single-use client token. The browser passes it to the payment provider's components to collect the card and complete payment; the card number never reaches Purple.

offering_ref
string
required
order_ref
string
required
Pattern: ^ord_[A-Za-z0-9][A-Za-z0-9_-]*$
payment_state
enum<string>
required

the payment state at creation; it is always awaiting payment until the patient completes it

Available options:
created,
payment_authorized,
paid,
payment_failed,
partially_refunded,
refunded,
disputed,
cancelled
destination_ref
string

the delivery-destination reference this session was created with, echoed back as RECORDED — never the value a particular retry happened to send. If a retry under the same idempotency key carries a different reference than the one originally recorded, this field still reports the ORIGINAL, so a caller can tell a kept value apart from an applied one instead of seeing an identical response either way. Absent when the order carries no delivery leg. See CommerceCheckoutSessionCreate's destination_ref for why the shape itself is opaque, and why this value is never part of the purchase identity.

Pattern: ^dest_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
stripe_account
string

the payment account this session's charge was set up on. The browser must load the payment provider's components in THIS account's context for the client token above to work. PRESENT only when the brand's charges are processed on the client's own payment account; OMITTED entirely (never null, never empty) when they are processed on the Purple platform account, because there is no separate account to point the browser at. Treat the field being absent as the signal to use the ordinary platform setup.

Pattern: ^acct_[A-Za-z0-9][A-Za-z0-9_-]*$