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

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

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.

Discover available methods

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

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.

Session tokens

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

• Initialize the Yuno SDK on the client.
• Reference the purchase intent when creating the payment server side.
• Determine available methods based on country, currency, and your provider configuration.

{
  "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

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.

What next

Payments

Create, capture, refund, and cancel with code.

Payment flow

The conceptual lifecycle and status state machine.

Customers

Attach a customer for one click and saved methods.

Checkout session object

The full object schema in the API reference.