# Checkout Sessions

> Learn how checkout sessions create payment requests.

Canonical: https://stafiel.org/documentation/accept-payments/checkout-sessions
Version: v1.0.0

A checkout session is the payment request for one merchant order, invoice, or
internal reference. It defines the amount, token, network, checkout display, and
return path for that payment. Each checkout session maps to one payment request
in the merchant system.

![Checkout session concept](/documentation/checkout-sessions-light.png)

## Before Creating A Checkout Session

Before creating a checkout session, set the payment details for the request:

Information
Requirement
What it means

Payment amount
Required
The USDT or USDC amount shown to the customer.

Token and network
Required
A supported USDT or USDC option from [Supported Assets and Networks](/documentation/start/supported-assets-and-networks).

Metadata
Recommended
Product name, description, quantity, order ID, invoice ID, booking ID, or customer reference.

Return URL
Recommended
A metadata value that sends the customer back after completing or leaving checkout.

Payment window
Optional
How long the checkout remains usable. If omitted, the default payment window applies.

Only supported token and network combinations enabled for the merchant account
should be offered to customers.

Merchant order or invoice references help match payment status, settlement,
invoice, receipt, refund, and support records later.

## Fixed After Creation

After checkout session creation, its payment terms are fixed for that order.
Later merchant setting changes apply only to future checkout sessions.

## Checkout Surfaces

After creating a checkout session, choose how customers open it.

![Checkout surface modes](/documentation/checkout-surfaces-light.png)

### Hosted Checkout (Redirect)

Hosted checkout opens a Stafiel-hosted payment page as a separate browser page or
tab. It is best for a complete payment page without building the payment screen
inside the merchant site.

Customers see the session amount, token, network, payment status, QR code,
payment address, payment window, and checkout metadata such as product title,
description, and quantity.

- Redirect: opens the hosted checkout page in a separate browser page or tab.

### Widget (Modal/Inline/Lite/Micro)

Widget places Stafiel checkout inside the merchant site. It is best when
customers should open checkout from the merchant page or keep checkout embedded
inside that page. Widget modes use the same session amount, token, network, and
payment window.

Widget has four customer-facing modes:

- Modal: opens checkout in an overlay above the page.

- Inline: shows checkout in a larger embedded area inside the page layout.

- Lite: shows checkout in a compact embedded area.

- Micro: shows checkout in the smallest embedded area.

Use either Checkout Snippet or Embedded Widget with any of these four modes. For
checkout snippet and widget implementation details, see
[Widget Integration](/documentation/developer-integration/widget-integration).

## How To Choose A Surface

Choose based on where checkout should appear and how much control is needed:

Need
Recommended surface
Why

Separate browser page or tab
Hosted checkout
Use a complete Stafiel-hosted payment page.

Fast setup inside the merchant site
Checkout snippet
Attach checkout to a button, link, or simple page element with fewer setup choices.

More control inside the merchant site
Embedded widget
Use more layout and behavior options for inline areas, compact blocks, or custom storefront layouts.

Checkout snippet and Embedded widget are two ways to add Widget checkout to a
merchant site. Both can use Modal, Inline, Lite, or Micro mode with a similar
checkout appearance and the same core checkout information; the difference is
setup simplicity and page control, while the mode should fit the available page
space and checkout flow.

## Next Steps

For how customers complete a payment, see
[Payment Flow](/documentation/accept-payments/payment-flow). To create sessions
from the backend, see
[Checkout Sessions API](/documentation/developer-integration/checkout-api).