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

mandatory for payments (api-style-guide) — replays return 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_-]*$

Body

application/json

The complete input to start a checkout session. Send the offering reference, the enrollment id, and an optional promo code — 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.

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.

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
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_-]*$