Checkout sessions create Flint-hosted payment pages for a single buyer. Each session is backed by an order: pass order_id to collect payment for an order you already created, quick_pay_item to have Flint create a simple one-time order for you, or subscription_plan_id to run hosted subscription signup from a subscription plan. The create response returns a tokenized buyer-facing url you redirect or link the buyer to.
Sessions are single-use. Generic sessions are short-lived (24 hours by default); invoice-owned sessions last for the life of the invoice's payment link. A session is open until the buyer completes payment, a mixed terminal attempt settles only part of the balance, you close it, it expires, or its source invalidates it. Terminal statuses are paid, partially_paid, closed, expired, and invalidated; terminal_reason explains the exact transition, including payment_succeeded and payment_partially_succeeded. Flint allows only one active session per order at a time. Creating another session for the same order returns CHECKOUT_SESSION_ALREADY_EXISTS unless you explicitly compare and replace the current session with replace_checkout_session_id. A hosted session pays the order with one payment method, so creating one for an order with more than one unpaid payment leg returns CHECKOUT_SPLIT_PAYMENT_UNSUPPORTED. Configuration (theme, tipping, customer collection requirements, redirects, legal links, expiration, and for an embedded session its page_origin) is fixed at creation on POST /v1/checkout-sessions. The invoice and return launch routes can replace page_origin on a reused embedded session, and a new embedded session they create inherits it from the earlier session when you omit it; see Collect an invoice or a return balance. page_origin is the origin of the page that renders an embedded checkout, such as https://shop.example.com. It is the only origin that can show the session's gift card challenge, and it grants no API access. While a session is open, a read of that one session returns gift_card_challenge.url, where the buyer completes the challenge; see Apply gift cards. Afterward, your API key can update metadata and external_reference_id. While the session is open, the session's checkout credential can save the buyer's email and phone as buyer_contact and the buyer's time zone as timezone, and on a subscription plan session either credential can send the buyer's interval and quantity as subscription_terms. A read with the checkout credential also returns save_payment_method_offered, which says whether checkout offers the buyer the option to save the card they type, save_payment_method_requires_verification, which says whether the buyer must first confirm their email with a code, and, once the checkout acts for a customer, customer_prefill; see Saved payment details. It also returns merchant_support, the support email, phone, and help page the merchant set; see Show how to reach the merchant. The checkout credential requests and confirms that code with the customer verification routes, and confirming returns the only credential that acts for the customer; see Confirm the buyer's email.
Start with the Checkout sessions guide. Not sure whether you need a checkout session, a payment link, or an invoice? See Payment links vs checkout sessions vs invoices.
For a gift card purchase without a customer identity, request an emailed code with purpose: "gift_card_purchase" through the session's customer verification route. This purpose is available on an open, unfunded order with gift card purchase lines and does not require saving a payment method. Confirm the code and use the returned checkout credential before payment. The purchaser and gift card recipient can have different email addresses.