Checkout Sessions API
API reference for creating and retrieving hosted Checkout Sessions.
Checkout Sessions API
Create a Checkout Session
POST /api/checkout-sessions
Authentication: Authorization: Bearer <organization API key>
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
| Field | Type | Required | Description |
|---|---|---|---|
amount | decimal string | yes | Final order total, greater than zero |
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 | 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.
Paylink-backed request
You may instead send paylinkId to create a unique attempt around an existing fixed-price Paylink:
{
"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.
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
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.
curl https://app.yolfi.com/api/checkout-sessions/ycs_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer $YOLFI_API_KEY"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.
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.