# Checkout Sessions API (/en/checkout/api-reference)



Checkout Sessions API [#checkout-sessions-api]

Create a Checkout Session [#create-a-checkout-session]

`POST /api/checkout-sessions`

Authentication: `Authorization: Bearer <organization API key>` or a dedicated agent credential. Host MCP OAuth tokens cannot authenticate direct HTTP requests; see [authentication](/en/api#authentication).

For standalone API Checkout, `Idempotency-Key` is required and must contain 16–200 characters. It
is scoped to the current organization. Repeating the same key and request returns the original
session; reusing the key with different request data returns `409 Conflict`.

Standalone request fields [#standalone-request-fields]

| Field               | Type           | Required | Description                                                        |
| :------------------ | :------------- | :------- | :----------------------------------------------------------------- |
| `amount`            | decimal string | yes      | Final order total, at least `0.01` in the pricing currency         |
| `currency`          | enum           | yes      | `USD`, `EUR`, or another supported Yolfi pricing currency          |
| `merchantOrderId`   | string         | no       | Your order identifier, up to 255 characters                        |
| `description`       | string         | no       | Text shown in hosted checkout, up to 1,000 characters              |
| `customerEmail`     | email          | no       | Trusted prefilled buyer email                                      |
| `customerName`      | string         | no       | Trusted prefilled buyer name                                       |
| `clientReferenceId` | string         | no       | Your customer reference                                            |
| `metadata`          | object         | no       | Primitive values within platform metadata limits                   |
| `successUrl`        | URL            | no       | Redirect after confirmed payment; supports `{CHECKOUT_SESSION_ID}` |
| `cancelUrl`         | URL            | no       | Return destination when checkout is cancelled                      |
| `expiresInMinutes`  | integer        | no       | 5–1,440; defaults to 60                                            |

Yolfi intentionally does not accept product line items. Keep the cart, quantities, discounts, tax,
and fulfillment data in your system; send only the final server-calculated `amount`.

The backend rejects totals below `0.01` in the pricing currency when creating a Checkout Session.
Exactly `0.01` passes this [price validation](/en/paylinks/api-reference#minimum-payment-amounts).
The merchant's enabled payment networks and their payment and settlement requirements are unchanged.

Paylink-backed request [#paylink-backed-request]

You may instead send `paylinkId` to create a unique attempt around an existing fixed-price Paylink:

```json
{
  "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
  "customerEmail": "buyer@example.com",
  "successUrl": "https://merchant.example/thanks?session_id={CHECKOUT_SESSION_ID}"
}
```

In this mode the amount and currency are copied from the enabled Paylink. Do not send `amount` or
`currency`; Paylink-backed sessions cannot override the saved product price.

The optional `subscriptionId` UUID identifies an existing recurring subscription and is supported only with `paylinkId`. The remaining customer, metadata, redirect, and expiration fields apply to both modes. Use an idempotency key for retries in either mode, even though standalone sessions require it.

Response fields [#response-fields]

| Field               | Type           | Description                                     |
| :------------------ | :------------- | :---------------------------------------------- |
| `id`                | string         | Public Checkout Session ID with `ycs_` prefix   |
| `object`            | string         | Always `checkout_session`                       |
| `status`            | string         | `OPEN`, `PROCESSING`, `COMPLETED`, or `EXPIRED` |
| `paylinkId`         | string or null | Present only for a Paylink-backed session       |
| `amount`            | decimal string | Immutable pricing snapshot                      |
| `currency`          | string         | Pricing currency snapshot                       |
| `merchantOrderId`   | string or null | Your order identifier                           |
| `description`       | string or null | Checkout description snapshot                   |
| `clientReferenceId` | string or null | Your customer reference                         |
| `successUrl`        | URL or null    | Successful-payment return URL                   |
| `cancelUrl`         | URL or null    | Checkout cancellation URL                       |
| `expiresAt`         | ISO 8601       | Session expiration time                         |
| `createdAt`         | ISO 8601       | Session creation time                           |
| `url`               | URL            | Hosted checkout destination                     |

Standalone sessions use the same root URL space as Paylinks. Yolfi distinguishes the resource by
its identifier: Checkout Sessions use the reserved `ycs_` prefix, while Paylinks use UUIDs.

Retrieve a Checkout Session [#retrieve-a-checkout-session]

`GET /api/checkout-sessions/{id}`

This authenticated endpoint is organization-scoped. It returns the session snapshot plus
customer fields, metadata, and a `payment` summary once an Invoice exists.

```bash
curl https://app.yolfi.com/api/checkout-sessions/ycs_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $YOLFI_API_KEY"
```

<Callout type="warning">
  `Checkout Session.status = COMPLETED` means the buyer has created an Invoice. It does not mean
  the blockchain payment is confirmed. Use the Invoice status or the signed `payment.confirmed`
  webhook for fulfillment.
</Callout>

Public hosted-checkout endpoint [#public-hosted-checkout-endpoint]

`GET /api/public/checkout-sessions/{id}` is used by Yolfi's hosted checkout. It does not require
authentication and intentionally exposes only the data needed to render that particular session.
Merchant integrations should create and retrieve sessions through the authenticated endpoints.