Session

A Session in Payments refers to an Embedded Checkout Session — a short-lived, server-created handle that authorizes a single buyer to complete a single checkout inside the Easy Labs hosted iframe. You create the session on your backend with the merchant API key, hand the client_secret to your frontend, and the iframe authenticates against that secret instead of your API key. This is what keeps the merchant key off the public web while still letting you customize the surrounding page.

Lifecycle

1. Created — client.createEmbeddedCheckoutSession({ line_items, mode, success_url, cancel_url, customer_email, payment_methods }) returns a EmbeddedCheckoutSessionData with id, client_secret, url, amount_total, currency, expires_at, and an initial status of open.
2. Open — the buyer loads your page; you mount <EmbeddedCheckout clientSecret={…} /> (React) or mountEmbeddedCheckout("#root", { clientSecret }) (vanilla browser). The iframe validates the session against /embedded-checkout/validate.
3. Confirmed — the buyer enters payment details inside the iframe; the iframe POSTs to /embedded-checkout/confirm. On success the session's status transitions to complete and payment_status to paid. The EmbeddedCheckoutProvider's onSuccess callback fires with { sessionId, status, tx_signature? }.
4. Closed — sessions also reach a terminal state of expired when the expires_at window elapses without payment. Confirmed sessions cannot be re-used; create a new session for each retry.
5. Webhook — checkout.session.completed fires server-side when the session reaches complete. For crypto payments, checkout.session.crypto_confirmed fires when the on-chain transaction is confirmed.

Relationships

A Session is associated with one Customer (created or matched via customer_email), produces one Order on success, which produces one Transfer. The line_items reference your Prices by ID, which reference Products. For crypto payments the session optionally carries a crypto_payment block that resolves to a confirmed on-chain transaction (recorded against a Wallet).

Fields that matter

• id (string) — the session ID. Use with getEmbeddedCheckoutSession for server-side polling.
• client_secret (string) — pass this to the browser; never log or persist it. Consumed by the iframe to authenticate.
• url (string) — a fully hosted checkout URL. Use this if you want to redirect instead of embedding.
• status ("open" | "complete" | "expired") — coarse session state.
• payment_status ("unpaid" | "paid" | "no_payment_required") — payment-side state on the session-status endpoint.
• amount_total (number), currency (string) — totals computed from line_items.
• expires_at (string) — ISO timestamp after which the session is no longer usable.
• payment_methods (("card" | "crypto")[]) — which methods the iframe will offer.

Related

• API reference
• Guide: Embed hosted checkout
• Guide: Build a custom checkout