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

# Checkout Sessions

> Create and track individual payment 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](#session-status) 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](/api/reference/quotes) 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.

```json theme={null}
{ "quoteId": "b3f1…", "metadata": { "orderId": "123" } }
```

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

```json theme={null}
{ "linkId": "pl_...", "metadata": { "orderId": "123" } }
```

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

```json theme={null}
{ "linkId": "pl_...", "chainId": 8453, "asset": "USDC" }
```

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

```json theme={null}
{ "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-reference openapi="GET /checkout_sessions" />

<api-reference openapi="POST /checkout_sessions" />

<api-reference openapi="GET /checkout_sessions/{id}" />