> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout sessions

> A checkout session is the purchase intent every Yuno payment sits inside. Amount, currency, country, and merchant order reference are committed here before any payment is created.

## What a checkout session is

A checkout session represents a single purchase intent. It commits the amount, currency, country, and your merchant order reference before any payment is created. Every Yuno payment runs inside one checkout session.

Think of it as a container: the session defines **what** is being purchased, the [payment](/core-concepts/payments) defines **how** the customer pays for it.

## Session lifecycle

1. **Your server** creates a checkout session through the API.
2. **Your client** uses the returned `checkout_session` to initialize the SDK or render the payment options.
3. **Your server** creates a payment that references the session.
4. **Yuno** marks the session as completed once the payment reaches a terminal status.

## Create a checkout session

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl --request POST \
  --url https://api-sandbox.y.uno/v1/checkout/sessions \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": {
      "currency": "USD",
      "value": 250.00
    },
    "country": "US",
    "merchant_order_id": "order-9876",
    "account_id": "your-account-id",
    "payment_description": "Annual subscription",
    "callback_url": "https://yoursite.com/payment/callback"
  }'
```

See [Create checkout session](/api-reference/checkout-sessions/create) for every accepted field and response shape.

### Required fields

| Field                 | Type   | Description                                               |
| --------------------- | ------ | --------------------------------------------------------- |
| `amount.currency`     | string | ISO 4217 currency code (for example `USD`, `BRL`, `MXN`)  |
| `amount.value`        | number | Payment amount as a decimal                               |
| `country`             | string | ISO 3166-1 alpha-2 country code                           |
| `merchant_order_id`   | string | Your internal order reference                             |
| `account_id`          | string | Your `account_id` from the Dashboard's Developers section |
| `payment_description` | string | Human readable description shown to the customer          |

### Optional fields

| Field          | Type   | Description                                                                            |
| -------------- | ------ | -------------------------------------------------------------------------------------- |
| `customer_id`  | string | Yuno `customer_id` for one click flows, see [customers](/core-concepts/customers)      |
| `workflow`     | string | Integration mode: `SDK_CHECKOUT`, `SDK_LITE`, `SDK_SEAMLESS`, `SDK_HEADLESS`, `DIRECT` |
| `callback_url` | string | Server notification URL for webhooks                                                   |
| `return_url`   | string | Customer redirect URL after payment. Required for 3DS, Pix, and redirect methods       |
| `metadata`     | object | Key value pairs for your own tracking                                                  |

<Note>
  `POST /v1/checkout/sessions` returns HTTP **200**, not 201. The session is not a REST resource in the traditional sense, it is an initialized flow.
</Note>

## Discover available methods

Once a session exists, ask Yuno which methods are available for this combination of country, currency, and your configured providers.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl --request GET \
  --url https://api-sandbox.y.uno/v1/checkout/sessions/{checkout_session_id}/payment-methods \
  --header 'public-api-key: your-public-api-key' \
  --header 'private-secret-key: your-private-secret-key' \
```

See [Get payment methods](/api-reference/checkout-sessions/get-payment-methods).

## Session tokens

The create response includes a `checkout_session` token that you use to:

* Initialize the [Yuno SDK](/guides/sdk/overview) on the client.
* Reference the purchase intent when creating the payment server side.
* Determine available methods based on country, currency, and your provider configuration.

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "checkout_session": "cs_abc123def456",
  "amount": { "currency": "USD", "value": 250.00 },
  "country": "US",
  "available_payment_methods": ["CARD", "APPLE_PAY", "GOOGLE_PAY"]
}
```

## Relationship to payments

| Aspect          | Checkout session                    | Payment                                         |
| --------------- | ----------------------------------- | ----------------------------------------------- |
| **Purpose**     | Defines what is being purchased     | Defines how the purchase is paid                |
| **Created by**  | Your server                         | Your server                                     |
| **Cardinality** | One per purchase attempt            | One per checkout session                        |
| **Contains**    | Amount, currency, country, customer | Method, token, customer detail, provider result |

<Warning>
  A checkout session can only back one payment. If a payment fails and the customer retries, create a new checkout session for the retry attempt.
</Warning>

## What next

<div className="mdx-card-tiles">
  <CardGroup cols={2}>
    <Card title="Payments" icon="credit-card" href="/core-concepts/payments">
      Create, capture, refund, and cancel with code.
    </Card>

    <Card title="Payment flow" icon="arrows-spin" href="/core-concepts/payment-flow">
      The conceptual lifecycle and status state machine.
    </Card>

    <Card title="Customers" icon="user" href="/core-concepts/customers">
      Attach a customer for one click and saved methods.
    </Card>

    <Card title="Checkout session object" icon="book" href="/api-reference/checkout-sessions/object">
      The full object schema in the API reference.
    </Card>
  </CardGroup>
</div>