A checkout session is a short-lived intent to collect a stablecoin payment. Create one with a single POST, then redirect the customer to the returned URL or render the embedded widget. Funds settle directly to the merchant wallet specified in the session; OpenSettle never holds them.
const checkout = await os.checkouts.create({
amount: 49.00,
currency: "USD",
settlement: {
chain: "base",
token: "USDC",
wallet: "0xA0b8…6eB48",
fallback_chains: ["arbitrum", "polygon"],
},
customer: { email: "ada@lovelace.dev" },
line_items: [
{ description: "Pro plan, April 2026", amount: 49.00 },
],
success_url: "https://yourapp.com/billing/done",
cancel_url: "https://yourapp.com/billing",
expires_in: 1800, // seconds; default 30m, max 24h
metadata: { order_id: "ord_4118" },
});
return Response.redirect(checkout.url);The URL we return resolves to https://pay.opensettle.com/c/<id>. The page detects the customer's wallet, prompts for the chain and token (constrained to what you allowed), and shows a live transaction tracker after submit. On confirmation, we redirect to success_url with the checkout id appended as ?co=ck_….
Sessions expire after expires_in seconds. Default 1,800s (30 minutes). Maximum 86,400s (24 hours). After expiration, the URL returns a friendly "session expired" page and the API rejects further submits with checkout_expired. You can also force-expire early by calling POST /v1/checkouts/:id/expire — useful if your inventory sells out.
The hosted page picks up your logo, accent color, support email, and legal links from Settings → Branding. Per-session overrides go on branding:
branding: {
accent: "#0E1330",
logo_url: "https://cdn.yourapp.com/logo-dark.svg",
show_powered_by: false, // requires Scale plan
}Pass amount for a fixed charge. For metered usage, omit amount and pass price with quantity — we compute the total at session creation and lock it. Metered checkouts are settled in one transaction; recurring metered usage belongs in a subscription, not a checkout.
checkout.created — session created.checkout.submitted — customer signed; tx is in the mempool.payment.confirmed — required confirmations reached; funds in merchant wallet.checkout.expired — TTL elapsed without a submitted tx.checkout.failed — submitted tx reverted on-chain.