API reference

Checkout sessions

A checkout session is one payer's visit to the hosted checkout page for one order. Creating a session creates its order in the same call unless you pass an existing order. You redirect the payer to url; the page lets the payer choose Pay with Orrerie or an asset and network, shows the address and QR code, and sends the payer to success_url once the order is paid. A session is open until its order is paid or overpaid (completed) or the order expires (expired); a session whose order is underpaid stays open and shows the top-up. An order may have several sessions (a payer returns from an email).

Never fulfil from the redirect. The payer's browser reaching success_url proves nothing. Fulfil when you receive order.paid by webhook, or when GET /v1/orders/{id} returns status paid or overpaid.

The `checkout_session` object

JSON

{
  "id": "cs_z7ek5wj68fyz80j7bz1eq4e0",
  "object": "checkout_session",
  "livemode": true,
  "created": "2026-10-11T14:03:22.418Z",
  "status": "open",
  "mode": "payment",
  "order": "ord_0zymngngvf12b8b2cra7tb8e",
  "url": "https://pay.orrerie.com/c/cs_z7ek5wj68fyz80j7bz1eq4e0",
  "app_url": "https://pay.orrerie.com/o/cs_z7ek5wj68fyz80j7bz1eq4e0",
  "success_url": "https://acme.example/thanks?session={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://acme.example/cart",
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "customer_email": "jane@example.com",
  "client_reference_id": "1042",
  "collect": {
    "email": "required",
    "name": "optional",
    "shipping_address": "hidden"
  },
  "collected": {
    "email": null,
    "name": null,
    "shipping_address": null
  },
  "locale": "auto",
  "subscription": null,
  "expires_at": "2026-10-11T15:03:22.418Z",
  "completed_at": null,
  "metadata": {
    "cart_id": "c_7781"
  }
}

Table: The checkout_session object
Field	Meaning
`url`	The hosted checkout page. It carries only the session id.
`app_url`	The Pay with Orrerie link. Opens the Orrerie app when installed. `null` when app_pay_allowed is `false`.
`success_url`	Where the payer is sent after the order is paid. {CHECKOUT_SESSION_ID} and {ORDER_ID} are replaced.
`client_reference_id`	Your own reference, echoed back. Up to 200 characters.
`status`	One of `open`, `completed`, `expired`.
`mode`	One of `payment`, `subscription`.

Every field

Fields of the `checkout_session` object

Fields of the checkout_session object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`status`	string	One of `open`, `completed`, `expired`.
`mode`	string	One of `payment`, `subscription`.
`order`	object	The `ord_` id of the session's order, or the order object when expanded.
`url`	string	The hosted checkout page. It carries only the session id.
`app_url`	string or null	The Pay with Orrerie link. Opens the Orrerie app when installed. `null` when app_pay_allowed is `false`.
`success_url`	string or null	Where the payer is sent after the order is paid. {CHECKOUT_SESSION_ID} and {ORDER_ID} are replaced.
`cancel_url`	string or null	Where the page's "Back to shop" link goes; `null` for none.
`customer`	object	The `cus_` id given with the session, or the customer object when expanded; `null` for none.
`customer_email`	string or null	The email given when the session was created, kept encrypted; `null` when none was given. The checkout shows no email field in this release.
`client_reference_id`	string or null	Your own reference, echoed back. Up to 200 characters.
`collect`	object	Which details the page asks the payer for.
`collect.email`	string	`required`, `optional` or `hidden`.
`collect.name`	string	`required`, `optional` or `hidden`.
`collect.shipping_address`	string	`required`, `optional` or `hidden`.
`collected`	object	What the payer gave on the page.
`collected.email`	string or null	The email the payer gave; `null` for none.
`collected.name`	string or null	The name the payer gave; `null` for none.
`collected.shipping_address`	object or null	The shipping address the payer typed, as `{text}`; `null` for none.
`locale`	string	The page's language: `auto` or `en`.
`subscription`	string or null	The `sub_` id the session starts, for a `subscription` session; `null` otherwise.
`expires_at`	string (date-time)	When the session's order stops taking new payments.
`completed_at`	string or null	When the order was paid; `null` until then.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Endpoints

Events

Webhook events whose data.object is an object of this page.