tf-checkout-react 2.0.0-beta.24 → 2.0.0-beta.26

package/README.md

@@ -7,25 +7,40 @@ components, plus the shared API and React Query hooks. Which paths a buyer can
 actually use depend on the event, the deployed API, the buyer's session and the
 payment provider.
 
-This reference describes **2.0.0-beta.24**. It is a prerelease with a different
+This reference describes **2.0.0-beta.26**. It is a prerelease with a different
 API from 1.x. Pin the version while evaluating it. npm's `latest` and `beta`
 tags can move independently and an unqualified install may select 1.x:
 
 ```bash
 npm view tf-checkout-react dist-tags
-npm install tf-checkout-react@2.0.0-beta.24 @tanstack/react-query react react-dom
+npm install tf-checkout-react@2.0.0-beta.26 @tanstack/react-query react react-dom
 ```
 
-The [API reference](https://unpkg.com/tf-checkout-react@2.0.0-beta.24/docs/API.md)
+The [API reference](https://unpkg.com/tf-checkout-react@2.0.0-beta.26/docs/API.md)
 is included as `docs/API.md` in this package.
 
-Contents: [Requirements](#requirements) · [Quick start](#quick-start) ·
-[Configuration](#configuration-and-sessions) · [Embedded checkout](#embeddedcheckout)
-· [Composition](#compose-sections) · [Checkout lifecycle](#checkout-lifecycle)
-· [Payments](#payments) · [Authentication](#authentication) ·
-[Reference](#component-reference) · [Headless APIs](#headless-apis) ·
+## Choose a checkout layout
+
+| Your goal | Start here | What the SDK renders |
+| --- | --- | --- |
+| Add a complete checkout to an event page | [`EmbeddedCheckout`](#embeddedcheckout) | A ready-made ticket or seat selection view followed by add-ons, buyer details, waiver and payment when applicable. |
+| Continue a cart created by an earlier flow | [`ResumedCheckout`](#resume-a-server-cart) | Ready-made buyer details, waiver and payment for the current session's existing cart. |
+| Keep the checkout on one page and arrange the sections yourself | [Single-page composition](#single-page-checkout) | Ticket selection, seats, add-ons, billing and payment sections in the host's layout. |
+| Show progressive steps or connect routes | [Step-by-step composition](#step-by-step-checkout) | The same sections; your application controls what is visible and how the buyer moves between steps. |
+| Organize the form as an accordion | [Accordion composition](#accordion-checkout) | Native HTML disclosure sections around the SDK's checkout components. |
+| Build your own checkout UI | [Headless APIs](#headless-apis) | The shared engine, hooks and API; your application owns the UI and navigation. |
+
+`EmbeddedCheckout` and `ResumedCheckout` are the ready-made flows in this
+version. The 1.x `*Container` components and named single-page/accordion
+examples are not drop-in 2.x exports. The [migration guide](#migrating-from-1x)
+shows how to reproduce those layouts with the current components.
+
+[Requirements](#requirements) · [Quick start](#quick-start) ·
+[Configure sessions](#configuration-and-sessions) · [Ready-made checkout](#embeddedcheckout) ·
+[Custom layouts](#compose-sections) · [Payments](#payments) ·
+[Authentication](#authentication) · [Component reference](#component-reference) ·
 [Styling](#styling-and-localization) · [Migration](#migrating-from-1x) ·
-[Testing and troubleshooting](#testing-and-troubleshooting)
+[Troubleshooting](#testing-and-troubleshooting)
 
 ## Requirements
 
@@ -50,17 +65,25 @@ Its `dist/styles` files and referenced assets are part of the npm package.
 
 ## Quick start
 
-Configure once before mounting the SDK. Create the query client once rather
-than on every render. Replace the placeholders with an event and a registered
-public client ID in the environment you are using.
+This example puts the ready-made checkout on one event page. You need a test
+event ID and the matching **public** SDK client ID. Ask your Ticket Fairy
+integration contact for these values and the appropriate environment.
+
+1. Install the package and its peers using the command above.
+2. Replace `EVENT_ID` and `PUBLIC_SDK_CLIENT_ID` below. Configure the SDK once
+   in your browser entry, before rendering the checkout.
+3. Mount `App` in your React application. The package entry imports its CSS;
+   the bundler must process CSS imports and their assets.
 
 ```tsx
 import { useState } from 'react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { configureCheckout, EmbeddedCheckout } from 'tf-checkout-react'
+import {
+  configureCheckout, EmbeddedCheckout, type PlaceOrderResult,
+} from 'tf-checkout-react'
 
 configureCheckout({
-  env: 'PROD',
+  env: 'STAG',
   clientId: 'PUBLIC_SDK_CLIENT_ID',
   clientSecret: '',
   cookieAuth: true,
@@ -69,30 +92,41 @@ configureCheckout({
 const queryClient = new QueryClient()
 
 export function App() {
-  const [notice, setNotice] = useState('')
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+
   return (
     <QueryClientProvider client={queryClient}>
-      <EmbeddedCheckout
-        eventId="EVENT_ID"
-        onComplete={(order) => {
-          setNotice(order.pending ? 'Payment pending' : 'Order submitted')
-        }}
-      />
-      <p role="status">{notice}</p>
+      {order ? (
+        <section role="status">
+          <h1>Checking your order</h1>
+          <p>Check your order status before making another purchase.</p>
+          {order.pending && <p>Your payment is pending.</p>}
+          {order.needIdVerification && <p>Identity verification may be required.</p>}
+        </section>
+      ) : (
+        <EmbeddedCheckout
+          eventId="EVENT_ID"
+          confirmationMode="redirect"
+          onComplete={setOrder}
+        />
+      )}
     </QueryClientProvider>
   )
 }
 ```
 
-Use a test event and the corresponding test client ID with `env: 'STAG'` for
-integration testing. `onComplete` receives a result that may be pending; do not
-fulfil an order merely because this callback fired. See
-[Payments](#payments) for reconciliation and retry guidance.
+The buyer first chooses tickets or seats. After reservation, the checkout shows
+applicable add-ons, buyer details, waiver and payment. `onComplete` hands the
+result to the host; the example displays a neutral status instead of claiming
+that tickets are ready. Connect that screen to **your backend's authoritative
+order status** using `order.orderHash`, handle any required ID verification and
+pending voucher, and provide support if the status cannot be established. The
+callback alone is not proof of settlement or ticket issuance.
 
-The inline confirmation also offers a generic share link using the current
-page URL without checking referral eligibility. That URL can contain query
-parameters or lack the buyer's referral. Review the
-[confirmation limitations](#checkout-sections) before using the default flow.
+Use `env: 'PROD'` with the matching production public client ID when your
+integration is ready. This beta's stock payment UI can ask a buyer to retry an
+unconfirmed payment; that wording does not establish that retrying is safe. See
+[Payments](#payments) before using the stock flow in production.
 
 ## Configuration and sessions
 
@@ -147,7 +181,31 @@ third-party dependencies should be tested in that framework.
 seat selection, add-ons, billing, waivers, payment and inline completion as the
 flow requires. It must be under `QueryClientProvider`.
 
-Only `eventId` is required. Callbacks and options are optional.
+Only `eventId` is required. Callbacks and options are optional. The component
+owns its checkout provider; do not wrap it in another `CheckoutProvider` to
+control its internal steps. The host still supplies `QueryClientProvider`.
+
+### What the buyer sees
+
+1. **Tickets:** the event's catalog, quantities, applicable codes and any
+   organizer-configured waiting list. Seated events can open a seat map.
+2. **Checkout:** a selection summary and the applicable add-ons, buyer/holder
+   details, waiver and payment. The reservation timer is displayed when available.
+3. **Completion:** `inline` shows the SDK's confirmation view; `redirect` calls
+   `onComplete` and leaves the host to show the next screen. The quick start uses
+   `redirect` so the host can check order status before presenting a receipt.
+
+`initialView="seats"` opens the seat-selection view first for an applicable
+seated event. `onViewChange` reports `tickets`, `seats` or `checkout`; it does
+not turn the component into a controlled router. For custom paths or step
+arrangements, use [section composition](#compose-sections).
+
+When choosing `confirmationMode="redirect"`, provide `onComplete` to receive
+the result and navigate to your status page. Although the prop is optional in
+the type, without that handoff the checkout remains mounted and no host status
+page is reached.
+
+### Options and callbacks
 
 | Prop | Type / default | Description |
 | --- | --- | --- |
@@ -179,98 +237,408 @@ session authorities; use the one appropriate to your configured journey.
 for the public checkout registration or account-completion journey; those
 paths force it on in this version.
 
+### Example: brand the ready-made checkout
+
+Use the same `QueryClientProvider` and one-time configuration as the quick
+start. Here `onViewChange` can update surrounding page content; `onComplete`
+passes the order result to the host's status screen.
+
+```tsx
+import { useState } from 'react'
+import { EmbeddedCheckout, type PlaceOrderResult } from 'tf-checkout-react'
+
+export function BrandedCheckout() {
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+  const [view, setView] = useState('tickets')
+
+  if (order) return <p role="status">Checking your order status…</p>
+
+  return (
+    <main>
+      <p>Checkout step: {view}</p>
+      <EmbeddedCheckout
+        eventId="EVENT_ID"
+        confirmationMode="redirect"
+        onComplete={setOrder}
+        onViewChange={setView}
+        initialPromoCode="WELCOME"
+        referrer="REFERRER_ID"
+        readAttributionFromUrl={false}
+        locale="en-US"
+        messages={{ 'tickets.getTickets': 'Continue to checkout' }}
+        theme={{ colorScheme: 'light', accent: '#6b2bd9', radiusCard: '16px' }}
+        className="festival-checkout"
+      />
+    </main>
+  )
+}
+```
+
+Use a promo or referral only when it belongs to this visit. Remove those props
+when they do not apply. By default the component also reads `promo` /
+`promo_code` and `ttf_r` / `referrer_id` from the URL. The example disables
+that behavior so the host controls attribution. `initialPromoCode` is applied
+once when the catalog mounts. It is not a guarantee that a code is valid.
+`theme` changes SDK design tokens, `className` lets your stylesheet target this
+instance, and `messages` overrides individual SDK copy keys. `locale` and
+`messages` do not automatically translate the event's own content or an
+external payment-provider page. See [Styling and localization](#styling-and-localization)
+for the available theme tokens and locales.
+
+### Example: connect host navigation and sign-in
+
+Pass callbacks when the surrounding application owns these actions. For
+example, `openSignIn` can open your sign-in UI, and `onOrder` can hand the
+result to your order-status screen. `onViewChange` is a notification, not a
+way to force the checkout to a particular step.
+
+```tsx
+import { EmbeddedCheckout, type PlaceOrderResult } from 'tf-checkout-react'
+
+type View = 'tickets' | 'seats' | 'checkout'
+
+export function HostCheckout(props: {
+  eventId: string
+  openSignIn: (email?: string) => void
+  showOrderStatus: (order: PlaceOrderResult) => void
+  reportView: (view: View) => void
+}) {
+  return (
+    <EmbeddedCheckout
+      eventId={props.eventId}
+      onLogin={props.openSignIn}
+      onViewChange={props.reportView}
+      confirmationMode="redirect"
+      onComplete={props.showOrderStatus}
+    />
+  )
+}
+```
+
+The email passed to `openSignIn` can be absent. Supplying `onLogin` replaces
+the built-in login modal; your host must complete the appropriate sign-in
+journey. An event-scoped checkout identity is not automatically a full
+account session. `showOrderStatus` must check the order and provider rather
+than treating the callback as a paid receipt.
+
 ### Resume a server cart
 
-`ResumedCheckout` calls `resumeCart` for an existing cart in the current
-session. It does not create that cart or accept a cart ID as a prop. A resale
-acceptance flow, for example, must create the cart first. The component shows
-billing, waivers and payment and requires the same query provider and
-configuration as the embedded flow.
+`ResumedCheckout` is a ready-made layout for a cart that **already exists in
+the current session**, such as one created by a preceding resale flow. It
+starts with buyer details and payment; it does not show ticket selection, create
+the cart, or accept a cart ID. Its `confirmationMode` defaults to `redirect`.
+Provide `onComplete` for the redirect/status handoff: without it the successful
+flow remains on its loading transition. Alternatively select `inline` and
+account for the confirmation and verification-copy limitations below.
 
 ```tsx
 import { useState } from 'react'
-import { ResumedCheckout } from 'tf-checkout-react'
+import { ResumedCheckout, type PlaceOrderResult } from 'tf-checkout-react'
 
+// Mount only after your preceding flow created a cart in this session.
 export function ResumePage() {
-  const [notice, setNotice] = useState('')
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+  if (order) return <p role="status">Checking your order status…</p>
+
   return (
-    <>
     <ResumedCheckout
       eventId="EVENT_ID"
       isFromResale
-      confirmationMode="inline"
-      onComplete={(order) => setNotice(order.pending ? 'Payment pending' : 'Order submitted')}
+      confirmationMode="redirect"
+      onComplete={setOrder}
     />
-    <p role="status">{notice}</p>
-    </>
   )
 }
 ```
 
+Wrap this page in the same `QueryClientProvider` as the quick start. Set
+`isFromResale` only for the resale path. Check the result with your backend,
+including any verification or pending-payment requirements. If the preceding
+flow did not create a cart, or the session changed, return the buyer to that
+flow instead of assuming a cart can be resumed.
+
 Props are `eventId` (required), `isFromResale` (default `false`),
-`onComplete`, `confirmationMode` (default **`redirect`**),
-`requireEmailConfirmation`, `collectTicketHolders`, `collectHolderContact`
-(each default `true`), `privacyPolicy`, `brandOptInLabel`,
-`additionalConditions`, `theme` and `className`. With the default redirect
-mode, route in `onComplete`; otherwise a transition remains visible. Unlike
-`EmbeddedCheckout`, this component does not accept `locale`, `messages`,
-`auth` or `onLogin` props in this version.
+`onComplete`, `confirmationMode`, `requireEmailConfirmation`,
+`collectTicketHolders`, `collectHolderContact` (each default `true`),
+`privacyPolicy`, `brandOptInLabel`, `additionalConditions`, `theme` and
+`className`. Unlike `EmbeddedCheckout`, this component does not accept
+`locale`, `messages`, `auth` or `onLogin` props in this version.
 
 ## Compose sections
 
-For a different layout, render sections beneath `CheckoutProvider` and the
-host's `QueryClientProvider`. The provider creates a web-wired `useCheckout`
-instance unless `value` is supplied. Sections share its context. The app-wide
-checkout store is shared by default, so separate `useCheckout()` calls are not
-independent carts. Avoid mounting competing checkout flows for different events
-at once; coordinate completion/reset and session transitions in the host.
+Use sections when the ready-made flow does not fit your page. Put all sections
+for one checkout inside a single `CheckoutProvider`, under the host's
+`QueryClientProvider`. The provider shares one checkout instance with its
+children. The default store is app-wide: mounting two flows does not create two
+independent carts. Configure the SDK once, before mounting the provider.
+
+The examples below assume the quick start's `configureCheckout` and
+`QueryClientProvider` setup. They demonstrate page layout and section wiring;
+your host still needs to implement order-status reconciliation, expiry and
+recovery for its event and enabled payment methods.
+
+These are wiring recipes, not complete buyer navigation. Each includes a return
+from the seat view and keeps `Tickets` mounted while switching views. The host
+still needs to implement Edit and Back from checkout (including payment to
+billing), preserve entered details, handle seat holds and cart expiry, and
+guard event/session changes and in-flight or retained payments. Use
+`EmbeddedCheckout` for its built-in Back and guarded Edit behavior.
+The seat-view Back button only changes views: it does not itself release reserved
+seats or cancel an already-started reservation or cart priming. Coordinate any
+in-flight work and the hold's expiry or release under your deployed backend
+contract before permitting a conflicting selection.
+
+### Single-page checkout
+
+This layout keeps the buyer on one browser page. Selecting tickets or seats
+reveals a single combined form with add-ons, buyer details, waiver and payment.
+The host supplies the status view after `onComplete`.
 
 ```tsx
 import { useState } from 'react'
 import {
-  AddOns, BillingInfo, CheckoutProvider, OrderSummary, Payment,
-  Tickets, WaiverSigning,
+  AddOns, BillingInfo, CheckoutProvider, Payment, SeatMap,
+  Tickets, TimerBanner, WaiverSigning, useCheckoutContext, type PlaceOrderResult,
 } from 'tf-checkout-react'
 
-export function ComposedCheckout() {
-  const eventId = 'EVENT_ID'
-  const [notice, setNotice] = useState('')
+function SinglePageContents({ eventId }: { eventId: string }) {
+  const checkout = useCheckoutContext()
+  const [view, setView] = useState<'tickets' | 'seats' | 'checkout'>('tickets')
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+
+  if (order) return <p role="status">Checking your order status…</p>
+
+  return (
+    <main>
+      <div hidden={view !== 'tickets'}>
+        <Tickets
+          eventId={eventId}
+          onContinue={() => setView('checkout')}
+          onSelectSeats={() => setView('seats')}
+        />
+      </div>
+      {view === 'seats' && (
+        <>
+          <button type="button" onClick={() => setView('tickets')}>Back to tickets</button>
+          <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+        </>
+      )}
+      {view === 'checkout' && (
+        <>
+          <TimerBanner seconds={checkout.secondsLeft} />
+          <AddOns eventId={eventId} />
+          <BillingInfo
+            eventId={eventId}
+            requireEmailConfirmation
+            collectTicketHolders
+            collectHolderContact
+          />
+          <WaiverSigning eventId={eventId} />
+          <Payment
+            eventId={eventId}
+            requireEmailConfirmation
+            collectTicketHolders
+            requireHolderContact
+            onComplete={setOrder}
+          />
+        </>
+      )}
+    </main>
+  )
+}
+
+export function SinglePageCheckout({ eventId }: { eventId: string }) {
   return (
     <CheckoutProvider theme={{ colorScheme: 'light', accent: '#2458d3' }}>
-      <Tickets eventId={eventId} />
-      <AddOns eventId={eventId} />
-      <BillingInfo eventId={eventId} requireEmailConfirmation />
-      <WaiverSigning eventId={eventId} />
-      <OrderSummary eventId={eventId} />
-      <Payment
-        eventId={eventId}
-        requireEmailConfirmation
-        onComplete={(order) => setNotice(order.pending ? 'Payment pending' : 'Order submitted')}
-      />
-      <p role="status">{notice}</p>
+      <SinglePageContents eventId={eventId} />
     </CheckoutProvider>
   )
 }
 ```
 
-This is a basic general-admission layout. Use section callbacks to reveal and
-navigate between steps as needed. For seated events wire `Tickets.onSelectSeats`
-to a `SeatMap` view; without the callback its seat-selection CTA is hidden.
-Keep `BillingInfo`'s email/holder rules aligned with `Payment`'s corresponding
-rules. If using a host privacy policy, pass the policy to `BillingInfo`, pass
-`requirePrivacyPolicy` to `Payment`, and use `onPrivacyRequired` to reveal the
-billing error. Render the event's required conditions and waiver, not just a
-card input. Read the consent limitations below before using `privacyPolicy` or
-the billing-skip option. Do not skip add-ons when one is required.
-
-`CheckoutProvider` props: `children` (required), `value?: UseCheckout`,
+`Tickets.onContinue` fires after the cart is primed. `onSelectSeats` opens the
+seat view; without it the seat-selection button is hidden in a composed
+`Tickets` section. `SeatMap.onContinue` runs after seats are added and priced.
+Without an `onContinue` prop, `BillingInfo` and `AddOns` use their combined-form
+behavior instead of showing a separate Continue button. Match the billing and
+payment email/holder settings, as shown. `AddOns` renders nothing when the
+event has no applicable add-ons; do not skip a required one.
+
+### Step-by-step checkout
+
+To make billing and payment separate steps, give `BillingInfo` an `onContinue`
+callback. It then validates and saves the buyer details before moving on. This
+example keeps the checkout provider mounted for the whole flow; it does not
+change URLs or assume a browser refresh can resume the in-memory layout.
+
+```tsx
+import { useState } from 'react'
+import {
+  AddOns, BillingInfo, CheckoutProvider, Payment, SeatMap,
+  Tickets, TimerBanner, WaiverSigning, useCheckoutContext, type PlaceOrderResult,
+} from 'tf-checkout-react'
+
+type Step = 'tickets' | 'seats' | 'details' | 'payment'
+
+function StepContents({ eventId }: { eventId: string }) {
+  const checkout = useCheckoutContext()
+  const [step, setStep] = useState<Step>('tickets')
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+
+  if (order) return <p role="status">Checking your order status…</p>
+
+  return (
+    <main>
+      {(step === 'details' || step === 'payment') && (
+        <TimerBanner seconds={checkout.secondsLeft} />
+      )}
+      <div hidden={step !== 'tickets'}>
+        <Tickets
+          eventId={eventId}
+          onContinue={() => setStep('details')}
+          onSelectSeats={() => setStep('seats')}
+        />
+      </div>
+      {step === 'seats' && (
+        <>
+          <button type="button" onClick={() => setStep('tickets')}>Back to tickets</button>
+          <SeatMap eventId={eventId} onContinue={() => setStep('details')} />
+        </>
+      )}
+      {step === 'details' && (
+        <BillingInfo
+          eventId={eventId}
+          requireEmailConfirmation
+          collectTicketHolders
+          collectHolderContact
+          onContinue={() => setStep('payment')}
+        />
+      )}
+      {step === 'payment' && (
+        <>
+          <AddOns eventId={eventId} />
+          <WaiverSigning eventId={eventId} />
+          <Payment
+            eventId={eventId}
+            requireEmailConfirmation
+            collectTicketHolders
+            requireHolderContact
+            onComplete={setOrder}
+          />
+        </>
+      )}
+    </main>
+  )
+}
+
+export function StepCheckout({ eventId }: { eventId: string }) {
+  return <CheckoutProvider><StepContents eventId={eventId} /></CheckoutProvider>
+}
+```
+
+For separate routes, keep the provider above the routed pages and connect the
+callbacks to your router. A full page reload is a different session/navigation
+problem: `ResumedCheckout` can attach only to an existing cart in the current
+session, and the old 1.x localStorage state is not a migration format. Handle
+expired reservations, browser Back, buyer changes and unconfirmed payments
+before enabling navigation or a new purchase. Do not unmount or reset an
+in-flight payment merely to move between steps.
+
+The step example is a progressive layout: the next step appears after a
+successful callback. A router can replace `setStep`, but the SDK does not
+supply a route-based checkout or implement your browser Back handling. Do not
+assume that a successful TypeScript build verifies route, refresh or payment
+behavior; test those flows with your own backend and providers.
+
+### Accordion checkout
+
+The SDK does not export a named accordion component. This host-built layout
+uses native HTML disclosures to group the same SDK sections. The payment field
+stays outside the disclosures so it remains visible while the buyer pays.
+It uses the configuration and `QueryClientProvider` from the quick start.
+
+```tsx
+import { useState } from 'react'
+import {
+  AddOns, BillingInfo, CheckoutProvider, Payment, SeatMap,
+  Tickets, TimerBanner, WaiverSigning, useCheckoutContext, type PlaceOrderResult,
+} from 'tf-checkout-react'
+
+function AccordionContents({ eventId }: { eventId: string }) {
+  const checkout = useCheckoutContext()
+  const [view, setView] = useState<'tickets' | 'seats' | 'checkout'>('tickets')
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+
+  if (order) return <p role="status">Checking your order status…</p>
+
+  return (
+    <main>
+      <div hidden={view !== 'tickets'}>
+        <Tickets
+          eventId={eventId}
+          onContinue={() => setView('checkout')}
+          onSelectSeats={() => setView('seats')}
+        />
+      </div>
+      {view === 'seats' && (
+        <>
+          <button type="button" onClick={() => setView('tickets')}>Back to tickets</button>
+          <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+        </>
+      )}
+      {view === 'checkout' && (
+        <>
+          <TimerBanner seconds={checkout.secondsLeft} />
+          <details open>
+            <summary>Add-ons</summary>
+            <AddOns eventId={eventId} />
+          </details>
+          <details open>
+            <summary>Buyer and ticket holders</summary>
+            <BillingInfo
+              eventId={eventId}
+              requireEmailConfirmation
+              collectTicketHolders
+              collectHolderContact
+            />
+          </details>
+          <details open>
+            <summary>Waiver</summary>
+            <WaiverSigning eventId={eventId} />
+          </details>
+          <Payment
+            eventId={eventId}
+            requireEmailConfirmation
+            collectTicketHolders
+            requireHolderContact
+            onComplete={setOrder}
+          />
+        </>
+      )}
+    </main>
+  )
+}
+
+export function AccordionCheckout({ eventId }: { eventId: string }) {
+  return <CheckoutProvider><AccordionContents eventId={eventId} /></CheckoutProvider>
+}
+```
+
+The buyer reserves tickets or seats, then can open or close the form groups.
+Closing a `<details>` element hides its contents without unmounting them. In a
+production accordion, open the relevant group when validation needs the buyer's
+attention, and make sure required add-ons, fields and waivers cannot be missed.
+Do not hide or replace the active payment field during a payment attempt.
+As with the other examples, replace the status placeholder with your own
+verified order-status and support flow.
+
+`CheckoutProvider` props are `children` (required), `value?: UseCheckout`,
 `theme?: CheckoutTheme`, `locale?: LocaleCode`,
 `messages?: Partial<Messages>`, and `className?: string`. Use
-`useCheckoutContext()` inside the provider. `useCheckoutValidation()` exposes
-`{ attempt, requestValidation }` for coordinating validation between sections;
-both context hooks require a provider. The provider's default checkout includes
-the installment picker. If supplying your own `value`, wire any custom payment
-ports you need when creating that checkout.
+`useCheckoutContext()` inside the provider to read the current checkout and
+`useCheckoutValidation()` to coordinate validation between sections. The
+provider's default checkout includes the installment picker. If supplying your
+own `value`, wire any custom payment ports you need when creating that checkout.
 
 ## Checkout lifecycle
 
@@ -309,6 +677,18 @@ error or closed provider page means the charge failed. A custom provider page mu
 settle with `{ event: 'dismiss' }` on close/unmount, and other custom payment
 ports must settle, or a waiting reset cannot finish.
 
+The beta.26 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
+say pressing Pay again finishes an unconfirmed order; the `resetWhenSettled`
+comment also omits retired checkouts as a reason for `false`. Those comments do
+not establish that a retry is safe. Use the session and reconciliation guidance
+above.
+
+Stock `Payment` can display an engine message telling the buyer to press Pay
+again when payment is unconfirmed. That wording does not establish that a retry
+is safe. If neutral buyer guidance is required for uncertain outcomes, use a
+custom payment flow with host-controlled error UI, retain the order and reconcile
+the current session and authoritative order/provider status before recovery.
+
 ### Tickets, codes, seats and waiting lists
 
 `Tickets` reads the catalog, presents the event's promo/access-code controls and
@@ -354,7 +734,7 @@ holder's answers in `ticketDataCapture`, and add-on answers via
 the opaque catalog ID. Use backend country/state IDs for `countryId` and
 `stateId`; `countryCode` / `stateCode` are payment billing codes.
 
-In beta.24 conditional custom-field requiredness is left to the backend and
+In beta.26 conditional custom-field requiredness is left to the backend and
 not all hosted-checkout conditional visibility is reproduced. Verify the
 actual event against the deployed checkout, including blanks, images, holder
 scoping and validation errors; do not claim parity from the presence of a
@@ -362,11 +742,20 @@ field alone. Terms and `additionalConditions` are client-side acceptance gates;
 respect the server's own requirements. `Payment` renders condition `content`,
 or `name` as a fallback, as HTML. Only supply trusted or appropriately sanitized
 content, and verify the source and handling of server-provided conditions too.
-Failed waiver reads other than a 404 remain unknown and block placement; use
-`reloadCheckoutDetails()` to retry rather than silently skipping it.
+
+During cart priming, failed custom-field, checkout-config, add-on or event
+condition reads fall back to empty/default data. The stock UI cannot show or
+gate requirements it did not load. Do not treat an empty list as proof that no
+requirement exists; verify deployment/failure behavior and add tested host
+safeguards for mandatory fields and acknowledgments. Server validation of
+required answers is not proof that a condition was acknowledged. Only failed
+waiver reads other than a 404 are recorded in `unavailableDetails`. Before money
+may have moved, placement retries an unavailable waiver and blocks if it remains
+unknown; `reloadCheckoutDetails()` can also retry the waiver read. A retained
+order with a possible payment follows separate recovery and needs reconciliation.
 `WaiverSigning` handles the SDK's signing flow.
 
-**Consent limitation in beta.24:** when `privacyPolicy` is supplied, the
+**Consent limitation in beta.26:** when `privacyPolicy` is supplied, the
 stock `BillingInfo` replaces the Ticket Fairy marketing checkbox with the
 required privacy checkbox, but both use `consent.ttfOptIn`; the order sends
 that value as `ttf_opt_in`. The privacy acknowledgement and Ticket Fairy
@@ -406,6 +795,19 @@ for authoritative confirmation before showing a paid receipt or fulfilling.
 ID verification may still be required after payment. An ID-verification failure
 is not a reason to repeat the charge.
 
+The stock in-flow `Confirmation` displays confirmed/ticket-available copy when
+`pending` is absent or false; it does not independently verify final settlement.
+For both paid and free orders, use `confirmationMode="redirect"` with a
+host-owned status page, or a custom composed confirmation gated on authoritative
+order and provider status. Arrange ID verification on the host route when
+`needIdVerification` is true; redirect does not render the inline verification.
+The stock `IDVerification` and routed `OrderIDVerification` verified messages
+say tickets are on their way; they do not check final settlement or issuance.
+Use host-owned neutral verification and status UI when that copy is premature.
+If `onComplete` navigates away or unmounts the checkout, its inline verification
+cannot appear: keep the provider mounted or handle verification at the destination.
+For a custom flow, see [host-owned ID verification](#host-owned-id-verification).
+
 **Zero-total orders:** this SDK ignores the free-registration response body and
 reports `needIdVerification: false`. Verification or approval may still be
 required, and `free: true` is not proof tickets were issued. The default inline
@@ -421,7 +823,8 @@ order's payment status before showing its default confirmed/ticket-availability
 copy. Gate it on an authoritative status appropriate for that page. When
 `onComplete` reports `pending`, show a pending page (and any voucher) instead;
 do not route directly to `OrderConfirmation` as a paid receipt. The in-flow
-`Confirmation` component reads the current result and has a pending state.
+`Confirmation` component reads the current result and has a pending state, but
+the absence of `pending` is not proof of settlement.
 
 `CardInput` renders Stripe Elements and uses the checkout's default card owner;
 `StripePaymentElement` is the deferred Elements option when its server config
@@ -452,6 +855,24 @@ three only when the provider confirms nothing was charged. An unclassified
 error is treated as unknown. Avoid automatic blind retries and never promise
 exactly-once charging across your app, backend and provider.
 
+### Host-owned ID verification
+
+`runIdVerification(orderHash, options)` does not open the provider on its own.
+Supply `openUrl` to validate the URL against your provider and scheme policy
+and open it in the browser; handle a missing URL or blocked/failed opening in
+your UI. The engine swallows asynchronous `openUrl` rejections, so catch and
+record opening failures inside the callback: polling can otherwise continue
+without a handoff. Use `onPhase` for polling state and handle browser returns;
+`registerForegroundListener` can trigger a recheck on return and must return an
+unsubscribe function.
+
+Alternatively, `onRequired` receives the order hash and possibly null URL; if
+it returns `true`, the engine resolves `undefined` without opening or polling,
+and your host owns both steps. A timeout or poll error rejects with a message
+promising that payment is safe and tickets will be emailed. Replace that text
+with neutral status and reconcile authoritative payment, verification and
+issuance. Verification alone does not prove settlement or issuance.
+
 ## Authentication
 
 The embedded checkout supplies the event to its built-in `AuthModal`. A
@@ -520,7 +941,7 @@ package are the authoritative detail for callback payloads and DTOs.
 | `BillingInfo` | `eventId?`, `onContinue?`, `heading?`, `buttonLabel?`, `onLogin?`, `skipWhenProfileComplete?`, `requireEmailConfirmation?`, `collectTicketHolders?`, `collectHolderContact?`, `ttfOptInLabel?`, `brandOptInLabel?`, `privacyPolicy?`, `showPrivacyError?`, `step?`, `className?`. Standalone holder collection follows backend gates unless explicitly enabled. |
 | `WaiverSigning` | `eventId`, `className?`. Render before payment for an event requiring a waiver. |
 | `Payment` | `onComplete?`, `eventId?`, `requireEmailConfirmation?`, `collectTicketHolders?`, `requireHolderContact?`, `additionalConditions?`, `requirePrivacyPolicy?`, `onPrivacyRequired?`, `showTestCardHint?`, `className?`. Match the paired billing policies. |
-| `OrderSummary` | `eventId?`, `className?`. Uses the current checkout's pricing. |
+| `OrderSummary` | `eventId?`, `className?`. Uses the current checkout's pricing. `Payment` already renders it; use it separately when you need a summary elsewhere. |
 | `IDVerification` | `className?`. Uses the current checkout/order. |
 | `Confirmation` | `shareUrl?`, `shareMessage?`, `viewOrderUrl?`, `children?`, `className?`. Uses the current checkout result and handles pending presentation. The default share URL and eligibility have the limitations below. |
 | `OrderConfirmation` | `orderHash`, `title?`, `message?`, `helper?`, `eventTitle?`, `eventDate?`, `eventLocation?`, `viewOrderUrl?` (string or function), `showReferral?`, `showShareButtons?`, `showRewards?`, `snapchat?`, `onLoaded?`, `onError?`, `className?`. Reloads confirmation by hash; the host must gate it on appropriate payment status. The three `show*` options default to true; Snapchat defaults to false. |
@@ -688,7 +1109,7 @@ as the final order amount.
 | `setAcceptedConditions(map)`, `acceptCondition(id, accepted)`, `setAddonDataCapture(map)` | Record condition acceptance and add-on answers. |
 | `setWaiverSignature(index, signature, hold?)`, `holdWaiverSigning(index)` | Coordinate a signature save with the cart/holder it belongs to; release a hold when finished. Prefer `WaiverSigning` for standard UI. |
 | `reloadCheckoutDetails()`, `syncCurrency(eventId, code?, options?)` | Retry unavailable details or switch/seed event currency. Refresh selection and prices after changing currency. |
-| `placeOrder(method?, options?)`, `runIdVerification(orderHash, options?)` | Place/pay; optionally run verification separately. `placeOrder` accepts `autoRunIdVerification`, `idVerification` and `claimCard` options. |
+| `placeOrder(method?, options?)`, `runIdVerification(orderHash, options?)` | Place/pay; optionally run verification separately with a host URL opener or takeover. See [host-owned ID verification](#host-owned-id-verification). `placeOrder` accepts `autoRunIdVerification`, `idVerification` and `claimCard` options. |
 | `applyPromoCode(eventId, code)`, `attributeReferrer(eventId, referrer)`, `joinWaitingList(eventId, entry)` | Helpers return promises. Refetch catalog after a code changes availability. |
 | `reset()`, `resetWhenSettled()` | Restart subject to payment-settlement protection; see [lifecycle](#checkout-lifecycle). |
 | `snapshot`, `store`, `isLoggedIn` | Entire state, shared store, and whether the hook sees an authenticated or checkout buyer session. The latter does not imply private-account authority. |
@@ -721,11 +1142,13 @@ for a different gateway.
 
 The package re-exports the shared core: `ttf` is a configured domain facade,
 `api` contains raw calls, `hooks` contains React bindings, and DTOs, logic,
-`createEngine` and `createCheckoutStore` are named exports. `ttf` calls return
-promises; they do not render UI or replace the engine's sequencing, payment
-ownership and preflight. Use them directly only when your application owns the
-corresponding workflow. The installed `dist/index.d.ts` includes the complete
-exported signatures. Avoid importing a private shared-core package.
+`createEngine` and `createCheckoutStore` are named exports. Network calls usually
+return promises; `ttf.events.filterAddonsForTickets` and
+`ttf.order.mapProfileToBilling` are synchronous helpers. They do not render UI
+or replace the engine's sequencing, payment ownership and preflight. Use them
+directly only when your application owns the corresponding workflow. The
+installed `dist/index.d.ts` includes the complete exported signatures. Avoid
+importing a private shared-core package.
 
 ```tsx
 import { hooks } from 'tf-checkout-react'
@@ -819,7 +1242,7 @@ existing 1.x integration pinned until the new flow and backend are verified.
 There is no automatic translation of old URLs, component props, account
 sessions or persisted 1.x state.
 
-| 1.x integration | 2.0.0-beta.24 approach |
+| 1.x integration | 2.0.0-beta.26 approach |
 | --- | --- |
 | `setConfigs({ BASE_URL, ... })` | `configureCheckout({ env` or `baseUrl`, `clientId`, `clientSecret: ''`, ... `})`; public client registration and session setup are required. |
 | `TicketsContainer`, `SeatMapContainer`, `AddOnsContainer` | `EmbeddedCheckout` or `Tickets`, `SeatMap`, `AddOns` under `CheckoutProvider`. Adapt callbacks and navigation. |
@@ -832,6 +1255,25 @@ sessions or persisted 1.x state.
 | Promo/access, waiting list, pixel and referral behavior | Re-check catalog metadata, code/attribution precedence, waiting-list contract and explicit tracking. Do not infer numeric `?r=`. |
 | Legacy single-page state in localStorage | Use the 2.x checkout store/engine and server cart; do not copy sensitive state or assume 1.x persisted state can be resumed. |
 
+### Migrating layout callbacks
+
+A callback name change can also change what the host receives. In particular,
+`onContinue` does not pass the old callback's response payload:
+
+| 1.x usage | 2.x replacement |
+| --- | --- |
+| `TicketsContainer`'s `getTicketsLabel` | `Tickets`'s `buttonLabel`. |
+| `TicketsContainer`'s `onAddToCartSuccess(data)` | `Tickets.onContinue()` after reservation; read the current cart through `useCheckoutContext()` under the provider. |
+| `BillingInfoContainer`'s `handleSubmit(values, helpers, eventId, response)` | `BillingInfo.onContinue()` after validation and save; read the current billing and holders from the checkout context. Omit the callback for combined-form behavior. |
+| `AddOnsContainer` timer | Render `TimerBanner` with `useCheckoutContext().secondsLeft` in the host layout. |
+| Separate 1.x page URLs and localStorage state | Keep the 2.x provider mounted across host steps; implement route/refresh handling and verify any existing server cart in the current session. |
+
+These are migration starting points, not prop-compatible aliases. In 2.x
+`eventId` is a string; convert a numeric ID before passing it. Old Material UI
+theme options, callback payloads and optional page behavior need explicit host
+work. For the two complete flows see [Choose a checkout layout](#choose-a-checkout-layout);
+for single-page and stepped alternatives see [Compose sections](#compose-sections).
+
 Compare the exact event's ticket types, dated pricing, seats, add-ons, holder
 questions, conditional fields, consent, waivers, fees, currencies, payment
 methods, account and post-purchase behavior before switching. Backend rollout

package/docs/API.md

@@ -1,12 +1,16 @@
 # React checkout API reference
 
 This reference describes the public surface of `tf-checkout-react` version
-`2.0.0-beta.24`. It supplements the package's npm README with examples and an
+`2.0.0-beta.26`. It supplements the package's npm README with examples and an
 inventory of the shared facade and hooks. The package's installed
 `dist/index.d.ts` is the exact versioned source for complete signatures and
 DTO fields. A named export or a typed payment method does not establish that
 the matching backend feature, account permission or payment provider is enabled.
 
+For installation, a complete quick start, and examples of the ready-made,
+single-page and step-by-step layouts, start with the [checkout guide](https://unpkg.com/tf-checkout-react@2.0.0-beta.26/README.md#choose-a-checkout-layout).
+This file is the detailed component, engine and API reference.
+
 All examples assume `configureCheckout` has run, and React Query examples are
 under a host `QueryClientProvider`. Use a registered public SDK client ID and
 an empty `clientSecret` in a browser. Never ship a confidential client secret.
@@ -61,8 +65,11 @@ appropriate authorized logout flow where a backend session must also end.
 
 `Tickets` and `SeatMap` report when a cart is ready; the host owns navigation
 when composing individual sections. This skeleton connects seated selection to
-its view. It is not a standalone app: configure and mount it under
-`QueryClientProvider`.
+its view. This wiring recipe is not a standalone app: configure and mount it
+under `QueryClientProvider`. Its seat Back changes views only; it does not itself
+release held seats or cancel an in-flight reservation or cart priming. Before
+allowing a conflicting selection, coordinate that work and hold expiry or
+release under your deployed backend contract.
 
 ```tsx
 import { useState } from 'react'
@@ -75,15 +82,18 @@ export function CheckoutLayout({ eventId }: { eventId: string }) {
   const [notice, setNotice] = useState('')
   return (
     <CheckoutProvider>
-      {view === 'tickets' && (
+      <div hidden={view !== 'tickets'}>
         <Tickets
           eventId={eventId}
           onSelectSeats={() => setView('seats')}
           onContinue={() => setView('checkout')}
         />
-      )}
+      </div>
       {view === 'seats' && (
-        <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+        <>
+          <button type="button" onClick={() => setView('tickets')}>Back to tickets</button>
+          <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+        </>
       )}
       {view === 'checkout' && (
         <>
@@ -101,10 +111,11 @@ export function CheckoutLayout({ eventId }: { eventId: string }) {
 }
 ```
 
-Real navigation must also handle expiry, payment in flight, retained orders and
-buyer/session changes. Do not unconditionally discard or replace a cart on
-Back during a payment. Use the embedded flow when its navigation fits; when
-building your own, preserve validation and server reservation behavior. The
+Real navigation must also implement checkout Edit/Back, preserve entered
+details, and handle expiry, payment in flight, retained orders and buyer/session
+changes. Do not unconditionally discard or replace a cart on Back during a
+payment. Use `EmbeddedCheckout` for its built-in Back and guarded Edit behavior;
+when building your own, preserve validation and server reservation behavior. The
 host can use `useCheckoutContext()` inside the provider to read the shared
 checkout and `useCheckoutValidation()` to coordinate section validation.
 
@@ -231,8 +242,18 @@ validate on the deployed server too. In this beta the backend owns conditional
 requiredness and hosted-checkout conditional visibility is not fully reproduced.
 Test the actual event's branches before release.
 
+During priming, failed custom-field, checkout-config, add-on or event-condition
+reads fall back to empty/default data and are not recorded in `unavailableDetails`.
+The engine and stock UI cannot gate requirements they did not load. Do not treat
+an empty list as proof that no requirement exists; verify failure behavior and
+implement tested host safeguards for mandatory fields and acknowledgments. Server
+answer validation is not proof that a condition was acknowledged.
+
 If `unavailableDetails` includes `'waiver'`, the read failed without establishing
-whether a waiver exists. `reloadCheckoutDetails()` retries it. For a custom
+whether a waiver exists. Before money may have moved, placement retries that
+read and blocks if it remains unknown; `reloadCheckoutDetails()` also retries it.
+A retained order with a possible payment follows separate recovery and needs
+reconciliation. For a custom
 waiver UI, `holdWaiverSigning(index)` returns a hold or `null`; complete or
 cancel the upload, attach via `setWaiverSignature(index, signature, hold)` only
 while the binding remains current, and release the hold. The standard
@@ -258,7 +279,34 @@ If status is unavailable, contact support. Do not retry payment for a free order
 `OrderConfirmation` does not check payment status before rendering its default
 confirmed/ticket-availability copy. Gate it on authoritative appropriate status;
 when the result is pending, show pending UI and any voucher instead. The
-in-flow `Confirmation` component reads the current result's pending state.
+in-flow `Confirmation` component reads the current result's pending state but
+shows confirmed copy when `pending` is absent or false, even for paid orders
+whose final settlement has not been independently verified. Use a host-owned
+status route with `confirmationMode="redirect"` or a custom composed
+confirmation gated on authoritative order and provider status. Redirect omits
+inline ID verification; arrange it when `needIdVerification` is true.
+For `EmbeddedCheckout` in redirect mode, provide `onComplete` to route the
+result. `ResumedCheckout` defaults to redirect and likewise needs that callback;
+otherwise its successful flow remains in the loading transition. Inline mode
+has the confirmation and verification-copy limitations described here.
+The stock `IDVerification` and routed `OrderIDVerification` verified messages
+say tickets are on their way but do not verify settlement or issuance. Use a
+host-owned neutral verification and status UI when appropriate. If `onComplete`
+navigates away or unmounts the checkout, inline verification will not appear;
+keep the provider mounted or handle verification at the destination.
+
+For custom verification, `runIdVerification(orderHash, options)` does not
+open a URL by itself. Supply `openUrl`, validate the provider URL and open it
+in the browser; handle a missing URL or blocked/failed opening. The engine
+swallows asynchronous `openUrl` rejections, so catch and record failures in
+that callback while showing neutral status. Handle `onPhase` and browser
+returns; `registerForegroundListener` can recheck on return and returns an
+unsubscribe function. Alternatively, return `true` from `onRequired` to take
+over: the engine resolves `undefined` and neither opens nor polls. A timeout or
+poll error rejects with copy promising payment is safe and tickets will be
+emailed; replace it with neutral status and reconcile authoritative payment,
+verification and issuance. Verification alone proves neither settlement nor
+issuance.
 
 For a custom Stripe card step, the following demonstrates the boundary between
 host-collected data and SDK placement. Render it only after reserving a cart and
@@ -350,6 +398,15 @@ no-charge outcomes as `declined`, `cancelled` or `notStarted`, with `unknown`
 for uncertainty. `UNSUPPORTED_GATEWAY` indicates the necessary platform
 capability is not available, not that every provider failure is safe to retry.
 
+The beta.26 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
+say pressing Pay again finishes an unconfirmed order; the `resetWhenSettled`
+comment omits retired checkouts as a reason for `false`. Those comments do not
+establish that a retry is safe; check the current session and reconcile first.
+Stock `Payment` can also display an engine message telling the buyer to press
+Pay again when payment is unconfirmed. That wording does not prove a retry is
+safe. If neutral guidance is required, use a custom payment flow with
+host-controlled error UI, retain the order and reconcile before recovery.
+
 ## Auth component contracts
 
 `AuthModal` owns a complete modal flow. Supply `open`, `onClose` and, for
@@ -464,6 +521,10 @@ preflight, state and payment coordination. Raw functions are also exported in
 the `api` namespace. Calling a low-level endpoint directly does not grant a
 buyer permission or guarantee a safe payment retry.
 
+`ttf.events.requiredCustomFieldLabels(eventId)` returns `[]` if its lookup
+fails as well as when no matching required order/ticket labels exist. An empty
+result is not proof that the event has no required custom fields.
+
 | Namespace | Methods |
 | --- | --- |
 | `ttf.events` | `featured`, `details`, `tickets`, `ticketsWithMeta`, `bundles`, `startBundlePurchase`, `info`, `conditions`, `timeSlotTickets`, `customFields`, `requiredCustomFieldLabels`, `addons`, `filterAddonsForTickets`, `submitPromoCode`, `setCurrency`, `authenticate`, `track`, `updateOrderDataCapture`, `updateTicketDataCapture`. |

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0-beta.24",
+  "version": "2.0.0-beta.26",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",