Skip to content
cartonium docs

Hosted cartonium checkout

cartonium checkout is a tenant-branded service hosted by cartonium: checkout and payment, order status, and the signed-in account center (profile, addresses, order history, returns, and saved payment methods). Hosted checkout and customer accounts are shipped capabilities. They are optional: use the hosted UI, build a BYO checkout and account UI, or adopt the hosted surfaces you need. Your storefront still creates checkout sessions and chooses safe handoff and return destinations.

Under the hood it drives the exact same public APIs a BYO storefront would: the checkout-session contract for payment and the customer-account API for the account center. The difference is who renders the UI — cartonium, instead of you.

Origins

Default hosted origins distinguish the platform deployment and commerce mode:

Platform deploymentOrdinary commerceSandbox commerce (current staging contract)
Production{tenant}.litecheckout.io{tenant}.sandbox.litecheckout.io
Preview / staging{tenant}.preview.litecheckout.io{tenant}.sandbox.preview.litecheckout.io

The tenant slug is the leftmost label, so acme.litecheckout.io serves the acme tenant. Every page resolves its tenant per-request from the host — there is no per-tenant deploy. A Preview deployment alone does not select Sandbox commerce. Use the resolved connection details for the intended environment; do not derive a customer destination from a raw deployment hostname. The staging Sandbox contract is not a claim of Production activation.

What it serves

Core hosted routes:

  • Checkout — /session/<token>: the tenant-branded payment surface over a checkout session.
  • Order status — /order/<token>/status: read-only post-purchase status (the o-token page).
  • Account — /account: signed-in home for profile, addresses, orders, and returns. The exact-order destination is /account/orders/by-reference/{orderReference} — address it with the stable public orderReference (or1_…) from API order responses; it is null only on legacy orders that predate the reference backfill, which keep the compatibility route. /account/orders/{orderNumber} remains a supported compatibility route; the display order number is a label, not a routing identity, so don't resolve a reference into a number before handing off. An unauthenticated visit continues through hosted sign-in with no customer email in any URL: entering the emailed code on the sign-in page returns to that exact order, and recovery links mint the exact destination directly, while an ordinary emailed sign-in link currently lands on hosted order history (where each order links onward by reference). Returns are started from a signed-in order (see Customer accounts); /account/returns is not a standalone returns page and routes to hosted order history.
  • Account sections — /account/profile, /account/addresses, /account/orders, and /account/payment-methods use a customer session. Saving a card is account management, not payment of a checkout; see Saved payment methods.

Booking pages and customer booking actions are implemented in the current staging contract, including /account/bookings. Bookings remain in active development, not launch-complete. The shipped hosted checkout/account capability does not establish availability of every booking or later checkout extension. Follow the feature-status matrix and each guide's activation boundary.

Reserved seams (the route exists but renders a placeholder until its API contract lands — they do not work yet):

  • Payment retry — /payment/<token>: a tokenized re-pay surface, waiting on the payment-recovery token family. Today, payment happens on the /session/<token> checkout link.
  • Tokenized return — /order/<token>/return: a from-email return entry, waiting on the order-token return contract. Today, returns go through the signed-in account.

Checkout and account both require what their underlying APIs require — a checkout session token for the payment flow, a customer session for the account pages — and the token-addressed pages (/order/..., /payment/...) are reached from emailed links carrying opaque, hash-at-rest tokens.

Adopting it from a storefront

A storefront doesn't have to choose all-or-nothing. Each customer surface — checkout, order status, order history, returns, account, saved payment methods — can be rendered by your frontend or handed to the appropriate hosted route. There is no universal storefront environment flag that implements this integration for every framework. Flags in a reference storefront control that implementation only.

  1. Resolve the destination. Obtain the tenant and environment's connection details. In the current staging contract, GET /merchant/settings/connection-details returns hostedCheckoutUrl (the hosted base origin, not a session URL) and hostedAccountUrl (its /account entry), together with environment and commerceEnvironment. Use those resolved hosted destinations when choosing hosted UI. A null destination gives no handoff target, and a returned URL does not prove reachability. Separately, checkout summaries' accountUrl and accountSignInUrl reflect the effective customer-action origin, which can be a trusted BYO origin; do not infer a hosted checkout origin from them or from a deployment URL.
  2. Hand off the right credential. Create a checkout session through the published contract and navigate to /session/{token} on that confirmed hosted origin. Pass the exact checkout token unchanged. An order-status link instead needs its separately issued o token; an orderReference, display order number, or checkout token is not a substitute.
  3. Let the hosted origin establish its customer session. Signed-in account, order-history, and saved-payment pages require hosted sign-in; purpose-bound action links keep their separate token credential. A BYO session cookie is not shared across origins. Never put a customer session bearer, merchant JWT, API key, or customer email into a handoff URL.
  4. Preserve the order address and return path. Exact-order handoffs use /account/orders/by-reference/{orderReference}. Pass the public reference through as-is; do not resolve it into a display number. Returns begin on that owned order, while /account/returns continues to order history. Use the API's resolved return/action URLs below and omit a link when its value is null.

Hosted UI does not grant access by navigation alone. Checkout tokens, customer sessions, and purpose-bound action tokens retain their own authority and expiry whichever frontend renders the experience.

Return and action destinations

Hosted cartonium checkout receives its customer-facing URLs from the API checkout summary. The API resolves explicit checkout settings first, then safe defaults, so storefronts do not have to infer destinations from deployment hosts or organization profile fields.

SurfaceSettingDefault when blank
Back to store / order status returnreturnToStoreUrlThe tenant storefront origin, then a neutral cartonium page when configured, then null
Completed checkout redirectpostCheckoutRedirectUrlreturnToStoreUrl, then the tenant storefront origin, then a neutral cartonium page when configured, then null
Expired checkout retrycheckoutRetryUrlreturnToStoreUrl, then the tenant storefront origin, then a neutral cartonium page when configured, then null
Canceled checkoutcheckoutCancelUrlcheckoutRetryUrl, then returnToStoreUrl, then the tenant storefront origin, then a neutral cartonium page when configured, then null
Account and sign-in linkscustomerActionBaseUrlThe tenant's hosted cartonium checkout account origin

Explicit redirect destinations are only used when they point at a trusted origin: the tenant's verified custom domain for the current environment, the tenant's own hosted cartonium checkout origin, or an operator-approved shared origin. Untrusted or invalid values are ignored rather than sent to shoppers.

Content-Security-Policy and violation reports

Every hosted page enforces a nonce-based Content-Security-Policy. A browser's violation report includes the page address with its query string and the address of the page the shopper came from, so violations are reported only from fixed, token-free addresses such as /cookies, /account, /account/orders and /account/sign-in, and only when the page has no query string and was not opened from a token page. Every other page enforces the same policy but sends no report: the tokenized links (/session/..., /order/..., /payment/...), addresses that name an order or document, any address with a query string, and pages opened from a token page. A report that is sent goes to cartonium's own collector, which records the violated directive with the page and blocked addresses reduced to their origin and first path segment.

Hosted vs BYO — when to use which

  • Hosted cartonium checkout — fastest path to a working, tenant-branded checkout and account experience; cartonium owns the UI, upgrades, and security posture (httpOnly session cookies, same-origin guards, tokenized links).
  • BYO — full control of the customer UI, at the cost of building and maintaining it against the checkout-session and customer-account APIs.

Both run on the same server-authoritative commerce core: cartonium computes totals, owns Stripe objects, and confirms orders from the webhook regardless of which surface rendered the page.

Related