> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcenpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Checkout Session object

> Data model and reference for hosted checkout sessions, purchase flows, and payment settlement across EVM and Stellar.

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

```json theme={null}
{
  "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

<ParamField body="paymentLinkId" type="string" required>
  The payment link to create a session for.
</ParamField>

<ParamField body="companyId" type="string">
  Company to associate with the purchase.
</ParamField>

<ParamField body="customerEmail" type="string">
  Customer email (receipts).
</ParamField>

<ParamField body="customerWallet" type="string">
  Customer wallet address.
</ParamField>

<ParamField body="customerName" type="string">
  Customer name/identifier.
</ParamField>

<ParamField body="successUrl" type="string">
  Redirect URL after successful payment.
</ParamField>

<ParamField body="cancelUrl" type="string">
  Redirect URL after cancelled payment.
</ParamField>

<ParamField body="expiresAt" type="string (ISO 8601)">
  Session expiry.
</ParamField>

```bash theme={null}
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": "billing@acme.com" }'
```

### As a raw session (no payment link)

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

```json theme={null}
{
  "purpose": "CUSTOM",
  "amount": 49,
  "acceptedToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "recipientWallet": "0xMerchantAddress...",
  "companyId": "cm_abc123",
  "customerEmail": "billing@acme.com"
}
```

### 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.

```bash theme={null}
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.

```bash theme={null}
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](/api/payment-links) 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                          |

## Related

* [Payment Links & Spec API](/api/payment-links) — public session and confirm endpoints
* [Checkout concept](/concepts/checkout) — the four payment paths
* [Checkout session methods](/sdk/node/client) — `createCheckoutSession`, `createHostedCheckout`, `chargeCustomer`