The Checkout Session object

Checkout sessions represent an individual purchase attempt. They are created server-side (typically from a payment link) and consumed by the hosted checkout page. Sessions track PENDING → PAID / EXPIRED / CANCELLED / FAILED and, when paid, produce the on-chain payment receipt.

Session object

{
  "id": "cs_abc123",
  "status": "PENDING",
  "purpose": "ADDON",
  "amount": "15.00",
  "currency": "USDC",
  "acceptedToken": "0x833...",
  "chainId": 8453,
  "customerWallet": "0xabc...",
  "recipientWallet": "0xdef...",
  "paymentLinkId": "pl_123",
  "companyId": "cm_abc123",
  "expiresAt": "2026-09-17T13:00:00.000Z"
}

Field	Type	Description
`id`	string	Checkout session ID (`cs_…`)
`status`	string	`PENDING`, `PAID`, `EXPIRED`, `CANCELLED`, or `FAILED`
`purpose`	string	`ADDON`, `INVOICE`, or `CUSTOM`
`amount`	string	Order amount (decimal)
`currency`	string	Display currency (typically `USDC`)
`acceptedToken`	string	Token contract the customer pays with
`chainId`	number	Settlement chain
`customerWallet`	string \| null	Payer wallet
`recipientWallet`	string	Recipient (merchant) wallet
`paymentLinkId`	string \| null	Source payment link, if any

Create a checkout session

POST /api/v1/checkout-sessions creates a session. Provide either an existing paymentLinkId (the session inherits amount, token, chain, and recipients from the link) or a raw session definition. Auth: legacy api_… key or dashboard session.

Auth matrix note

Credential	Status
Legacy `api_…`	✅
Dashboard session	✅
`sk_…` / `rk_…` / `pk_…`	⚠️ ❌ (not yet accepted)

With a payment link

string

required

The payment link to create a session for.

string

Company to associate with the purchase.

string

Customer email (receipts).

string

Customer wallet address.

string

Customer name/identifier.

string

Redirect URL after successful payment.

string

Redirect URL after cancelled payment.

string (ISO 8601)

Session expiry.

curl -X POST https://api.arcenpay.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer api_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "paymentLinkId": "pl_abc123", "customerEmail": "[email protected]" }'

As a raw session (no payment link)

purpose, amount, acceptedToken, and recipientWallet are all required.

{
  "purpose": "CUSTOM",
  "amount": 49,
  "acceptedToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "recipientWallet": "0xMerchantAddress...",
  "companyId": "cm_abc123",
  "customerEmail": "[email protected]"
}

Response

201 with { "checkoutSession": { ...session } }.

Get a checkout session

GET /api/v1/checkout-sessions/:id returns one session scoped to your team. Auth: legacy api_… key or dashboard session.

GET https://api.arcenpay.com/api/v1/checkout-sessions/cs_abc123

List checkout sessions

GET /api/v1/checkout-sessions returns the most recent 100 sessions for your team, ordered newest first, including related payment link, company, add-on, invoice, and payment info. Auth: legacy api_… key or dashboard session.

GET https://api.arcenpay.com/api/v1/checkout-sessions

Hosted checkout & public confirm

The hosted /pay/:slug page and the public confirmation endpoints are unauthenticated by design — the customer (or agent) opens them with the session attached.

Endpoint	Purpose
`GET /api/v1/public/checkout/:sessionId`	Fetch a session for the hosted page
`PATCH /api/v1/public/checkout/:sessionId`	Update customer info on a session
`POST /api/v1/public/checkout/:sessionId/confirm`	Confirm an on-chain payment against the session
`POST /api/v1/public/payment-links/:slug/session`	Open a session from a payment-link slug
`POST /api/v1/public/payment-links/:slug/confirm`	Confirm payment for a slug-based session

See Payment Links & Spec API for the public confirm contract and receipt shape.

Checkout session webhooks

Event	When it fires
`checkout.session.created`	Customer opened a hosted checkout and a session was created
`checkout.session.paid`	Session paid and verified on-chain

Payment Links & Spec API — public session and confirm endpoints
Checkout concept — the four payment paths
Checkout session methods — createCheckoutSession, createHostedCheckout, chargeCustomer

Last modified on September 19, 2026

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

The Checkout Session object

Session object

Create a checkout session

Auth matrix note

With a payment link

As a raw session (no payment link)

Response

Get a checkout session

List checkout sessions

Hosted checkout & public confirm

Checkout session webhooks

​Session object

​Create a checkout session

​Auth matrix note

​With a payment link

​As a raw session (no payment link)

​Response

​Get a checkout session

​List checkout sessions

​Hosted checkout & public confirm

​Checkout session webhooks

​Related

Session object

Create a checkout session

Auth matrix note

With a payment link

As a raw session (no payment link)

Response

Get a checkout session

List checkout sessions

Hosted checkout & public confirm

Checkout session webhooks

Related