Checkout Sessions

A checkout session represents one payment attempt. Each session has a unique deposit address the customer sends funds to. Sessions expire if no payment is detected within the configured TTL (default 5 minutes).

The checkout session object

Field	Type	Description
`id`	uuid	Unique identifier
`object`	string	Always `"checkout_session"`
`linkId`	uuid \| null	The payment link this session was created from, if any
`status`	string	See status values below
`address`	string	Unique deposit address the customer should send funds to
`amount.wei`	string	Required amount in wei
`amount.eth`	string	Required amount in ETH
`fiat.amount`	string	Fiat amount, e.g. `"100.00"`
`fiat.currency`	string	e.g. `"USD"`
`ethPriceUsd`	string	ETH/USD rate locked at session creation
`expiresAt`	datetime	When the session expires if unpaid
`paidAt`	datetime \| null	When payment was confirmed
`txHash`	string \| null	On-chain transaction hash
`chainId`	integer	EVM chain ID
`asset`	string	Asset symbol, e.g. `"ETH"`, `"USDC"`
`assetSelected`	boolean	`true` when the coin is already decided (from a quote or an explicit `chainId`/`asset`), so the hosted checkout skips the network/coin picker and lands on the pay step
`metadata`	object \| null	Your custom key/value data. Also receives any billing details (`name`, `phone`, `country`, `region`, `postcode`, `notes`) the customer enters on the hosted checkout
`checkoutUrl`	string	URL to send the customer to
`livemode`	boolean
`createdAt`	datetime
`updatedAt`	datetime

Session status

Status	Meaning
`pending`	Awaiting payment
`detected`	Transfer detected, waiting for confirmations
`paid`	Payment confirmed
`paid_late`	Payment confirmed after expiry (within grace window)
`underpaid`	Transfer detected but amount is less than required
`overpaid`	Transfer detected but amount exceeds required
`expired`	Session timed out with no payment
`failed`	An unrecoverable error occurred

Three modes

Quote mode — create a session from a quote you issued earlier. The chain, asset and locked price all come from the quote, so the customer pays exactly what was quoted and lands straight on the pay step. A quote can only back one session.

{ "quoteId": "b3f1…", "metadata": { "orderId": "123" } }

Link mode — create a session from an existing payment link. The price and currency come from the link.

{ "linkId": "pl_...", "metadata": { "orderId": "123" } }

Pass chainId and asset to pin the coin up front — the hosted checkout then skips the network/coin picker:

{ "linkId": "pl_...", "chainId": 8453, "asset": "USDC" }

Ad-hoc mode — create a session with a custom amount. Useful for dynamic pricing. Also accepts chainId / asset.

{ "amount": { "value": "73.42", "currency": "USD" } }

Pre-selecting the coin & a one-step checkout

A session where the coin is already decided — created from a quote, or with an explicit chainId + asset — has assetSelected: true. On the hosted checkout the customer skips the network and coin steps entirely. Combine that with a known customerEmail (passed on create, or captured on a prior visit) and the checkout collapses to a single Pay step.

Billing details captured at checkout

When a customer fills in their details on the hosted checkout (email is required; name, phone, country, region, postcode and order notes are optional), the optional fields are merged into the session metadata — alongside any metadata you set at creation — so they arrive on the session.* webhooks and when you read the session back.

API

API Reference

The checkout session object

Session status

Three modes

Pre-selecting the coin & a one-step checkout

Billing details captured at checkout

​The checkout session object

​Session status

​Three modes

​Pre-selecting the coin & a one-step checkout

​Billing details captured at checkout

The checkout session object

Session status

Three modes

Pre-selecting the coin & a one-step checkout

Billing details captured at checkout