tf-checkout-react-native 2.0.0-beta.22 → 2.0.0-beta.24

package/README.md

@@ -1,384 +1,995 @@
-# tf-checkout-react-native
-
-The TicketFairy checkout for React Native. Drop in one component and you have
-ticket selection, add-ons, buyer details, payment, ID verification, and the
-receipt — or compose the sections yourself.
-
-Same API as [`tf-checkout-react`](https://github.com/theticketfairy/tf-shared-libraries/blob/main/packages/tf-checkout-react/README.md); the flow,
-validation, and gating rules are literally the same code.
-
-The 2.x source is maintained in [`tf-shared-libraries/packages/tf-checkout-react-native`](https://github.com/theticketfairy/tf-shared-libraries/tree/main/packages/tf-checkout-react-native).
-The core is private and bundled into both platform packages. Use React 18+ and
-React Query 5 on web; the native requirements below reflect its supported build.
-Never put a confidential OAuth client secret in browser or mobile code. Public
-checkout integrations use registered SDK client IDs and owned buyer sessions.
-
-## Prepared native storage change — beta.22
-
-The prepared paired beta.22 prerelease requires an explicit synchronous credential-storage
-adapter. Native `configureCheckout` and its root `configure` alias no longer create
-an unencrypted MMKV store. The MMKV factory/default exports and peer dependency
-are removed. This is a native beta breaking change; web defaults are unchanged.
-See [beta.22 release preparation](../../docs/releases/2.0.0-beta.22.md) and
-[secure native setup and migration](../../docs/integration/native-session-storage.md).
-
-The replacement release is not published yet. The beta.21 receipt below remains
-the last verified registry checkpoint; its published artifact still has the older
-MMKV dependency. The following setup examples describe current source, not an
-in-place change to an already published version.
-
-## Install
-
-### Last verified paired prerelease 2.0.0-beta.21
-
-Both SDKs are registry-verified as `2.0.0-beta.21` from exact tagged shared source
-`d7de6a71058cc293e6d521d52b42d9911768d1c2`, through protected paired pipeline15.
-The [canonical receipt](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/releases/2.0.0-beta.21.registry.json)
-records exact archive/member/SHA/SRI proof. Both stable `latest` tags are unchanged.
-Pin the exact version below; `@beta` follows the most recent prerelease. Publication
-does not establish API rollout, app delivery or device/provider acceptance.
-
-This version preserves quantities across rotating encrypted ticket IDs using
-the API's optional canonical `selectionKey`, while quantity/change APIs and cart
-requests retain the latest encrypted IDs. Deploy and verify the canonical
-base/dated key and dated numeric context before relying on that behavior:
-`display_price`, `price_with_fees`, `fee_included`, `price_currency` and
-`price_symbol`. No localized price parsing or base-price/cap substitution is
-used. Missing optional keys retain opaque-ID compatibility, without a
-rotation-retention claim. The [beta.21 notes](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/releases/2.0.0-beta.21.md)
-and [app integration contract](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/integration/app-sdk.md)
-record API rollout requirements and separate deployment/provider/device gates.
-
-Post-purchase upgrade waiting is a separate server-owned contract. Only valid
-change-options targets can expose Join or Leave; malformed target IDs, labels
-or existing entries are ignored. A sold-out row does not enable it. The backend
-must explicitly offer that organizer-configured flow; local receiver validation
-does not prove its deployed availability or a completed join.
-
-After the replacement paired prerelease is published:
-
-```bash
-npx expo install tf-checkout-react-native@2.0.0-beta.22 \
-  @tanstack/react-query \
-  @stripe/stripe-react-native \
-  @react-native-clipboard/clipboard \
-  react-native-webview \
-  react-native-render-html@6.3.4
+# Ticket Fairy Checkout for React Native
+
+Native React components and a headless checkout engine for selling Ticket Fairy
+tickets. Start with `EmbeddedCheckout`, compose individual sections, or own the
+presentation using `useCheckout` and the shared API. The package includes its
+private shared core; hosts do not install `tf-checkout-shared`.
+
+This reference is for **`tf-checkout-react-native@2.0.0-beta.24`**, a
+prerelease with a different API from 1.x (including its `CheckoutV2`). Pin the
+version: `latest` and `beta` tags can move; check `npm view tf-checkout-react-native dist-tags`.
+The [API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/docs/API.md)
+covers components and hooks; the [declarations](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/dist/index.d.ts)
+contain all types. The [web package](https://www.npmjs.com/package/tf-checkout-react/v/2.0.0-beta.24)
+shares the engine but has different UI and ports. Availability depends on the
+backend, event, gateway, account and device; installation does not establish
+hosted-checkout parity or payment acceptance.
+
+## Contents
+
+- [Requirements and installation](#requirements-and-installation)
+- [Initialize secure storage and configure](#initialize-secure-storage-and-configure)
+- [Embed a checkout](#embed-a-checkout)
+- [Compose sections and navigation](#compose-sections-and-navigation)
+- [Checkout section reference](#checkout-section-reference)
+- [Tickets, seats, codes and attribution](#tickets-seats-codes-and-attribution)
+- [Billing, custom fields and consent](#billing-custom-fields-and-consent)
+- [Payments and safe completion](#payments-and-safe-completion)
+- [Headless checkout](#headless-checkout)
+- [Hooks and API](#hooks-and-api)
+- [Authentication and account components](#authentication-and-account-components)
+- [Theme, primitives and localization](#theme-primitives-and-localization)
+- [Migration from 1.x](#migration-from-1x)
+- [Testing and troubleshooting](#testing-and-troubleshooting)
+
+## Requirements and installation
+
+The package declares Node `>=20.19.4`, React `>=19.1`, React Native `>=0.81`,
+`@tanstack/react-query >=5`, `@stripe/stripe-react-native >=0.45.0`,
+`@react-native-clipboard/clipboard >=1.14.0`, `react-native-webview >=13.15.0`,
+and `react-native-render-html >=6.3.4 <7` as host requirements or peers. The
+supported RN 0.81 cohort uses the New Architecture, iOS 15.1+ and Android API
+24+. Check the native dependencies' own requirements and the versions supported
+by your app; a peer range is not proof that every combination has been tested.
+The package itself declares `axios`, `entities` and `htmlparser2` as runtime
+dependencies. Use one copy of React, React Query and each native module in the
+host. `npm ls react @tanstack/react-query @stripe/stripe-react-native` helps
+identify duplicates.
+
+For an Expo project with compatible React and RN versions:
+
+```sh
+npx expo install tf-checkout-react-native@2.0.0-beta.24 \
+  @tanstack/react-query @stripe/stripe-react-native \
+  @react-native-clipboard/clipboard react-native-webview \
+  react-native-render-html@6.3.4 expo-secure-store
 ```
 
-Bare React Native:
-
-```bash
-npm install tf-checkout-react-native@2.0.0-beta.22 @tanstack/react-query @stripe/stripe-react-native @react-native-clipboard/clipboard react-native-webview react-native-render-html@6.3.4
-```
-
-These are **peer dependencies** on purpose. React contexts and native
-modules must exist exactly once in an app — a second copy of react-query means
-your `<QueryClientProvider>` is invisible to our hooks, and a second Stripe
-means a duplicate pod. As peers there is one copy and no Metro aliasing is ever
-needed.
-
-Everything else — the SDK core, the flow, the UI — ships inside the package.
-
-Beta.21 retains the `react-native-render-html` peer `>=6.3.4 <7`
-for formatted ticket, add-on, bundle and accommodation descriptions and its
-public `RichText` renderer. Development and component tests use `6.3.4`; the
-install commands above pin that compatible version. See [native rich content](../../docs/integration/native-rich-content.md)
-for the rendering contract and pending acceptance coverage.
-
-## Requirements
-
-- React Native `0.81+` with the New Architecture enabled (the supported build cohort)
-- React `19.1+`, Node `20.19.4+`
-- iOS 15.1+ · Android API 24+ (Stripe SDK minimums)
-- A development build. **Expo Go will not work** — this package uses native
-  modules.
-
-Add the Stripe plugin to `app.json`:
+The last package is used by the storage example below; the SDK does not install
+or require Expo SecureStore. Build a development client containing the native
+modules. Complete checkout compatibility with Expo Go is not established. Add
+the Stripe config plugin to the app configuration, choosing wallet settings for
+your own app, and rebuild after changing native configuration. For example,
+this starts without Google Pay:
 
 ```json
 {
   "expo": {
+    "scheme": "myapp",
     "plugins": [["@stripe/stripe-react-native", { "enableGooglePay": false }]]
   }
 }
 ```
 
-Then build a dev client once:
+Run `npx expo run:ios` or `npx expo run:android`, or make a development build
+using your normal process. For a bare React Native app, install the peers in
+the app (React and React Native are normally already present):
 
-```bash
-npx expo run:ios
+```sh
+npm install tf-checkout-react-native@2.0.0-beta.24 @tanstack/react-query \
+  @stripe/stripe-react-native @react-native-clipboard/clipboard \
+  react-native-webview react-native-render-html@6.3.4
 ```
 
-## Use it
+Configure autolinking and Stripe's native setup, run `pod install` in the iOS
+directory, and rebuild both platforms. Provide a Keychain/Keystore-backed
+storage adapter using a native library appropriate to the host. Consult the
+[Stripe React Native setup](https://docs.stripe.com/payments/accept-a-payment?platform=react-native)
+and [Expo SecureStore documentation](https://docs.expo.dev/versions/latest/sdk/securestore/)
+for native configuration and platform behavior. Configure wallet entitlements,
+merchant registration and deep links separately if those features are used.
+
+## Initialize secure storage and configure
+
+`configureCheckout(config)` is synchronous and must run **after credential
+storage is restored**, before any SDK API call, hook or component mounts. Its
+root export alias `configure` has the same native requirements. Configuration
+is app-wide. Set up one environment and buyer session at a time; avoid
+reconfiguring during checkout or payment.
+
+`storage` is required. It has synchronous `getItem(key): string | null |
+undefined`, `setItem(key, value): void`, `removeItem(key): void`, and optional
+`flush(): Promise<void>`. The wrapper checks method shape; it does not certify
+encryption, persistence, isolation, backup or correctness. `createMemoryStorage`
+is exported for tests and loses credentials at process exit; it is not a
+production secure store. Use separate storage namespaces per app/environment.
+Never put a confidential OAuth client secret or provider secret key in mobile
+code. Obtain a public SDK client ID authorized for the integration and use an
+empty `clientSecret` for public checkout; do not substitute a confidential
+credential. Environment variables compiled into an app are visible to its users.
+
+The SDK reads storage synchronously. The following Expo example asynchronously
+restores one protected snapshot first, then makes each subsequent OS write
+synchronously *before* publishing the new in-memory snapshot. The methods are
+not `async` and a failed write throws instead of reporting success. Replace the
+namespace with an app-owned, environment-specific key.
 
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { configureCheckout, EmbeddedCheckout } from 'tf-checkout-react-native'
-import { restoreCredentialStorage } from './credentialStorage'
-
-// Await this in the host's startup gate before rendering App or any SDK hook.
-export async function prepareCheckout() {
-  const storage = await restoreCredentialStorage('my_app_checkout_prod')
-  configureCheckout({
-    env: 'PROD',
-    clientId: 'PUBLIC_SDK_CLIENT_ID',
-    clientSecret: '',
-    storage,
-  })
+```ts
+// credentialStorage.ts
+import * as SecureStore from 'expo-secure-store'
+import type { StorageAdapter } from 'tf-checkout-react-native'
+
+export async function restoreCredentialStorage(key: string): Promise<StorageAdapter> {
+  const raw = await SecureStore.getItemAsync(key)
+  const parsed: unknown = raw === null ? {} : JSON.parse(raw)
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) ||
+      Object.values(parsed).some(value => typeof value !== 'string')) {
+    throw new Error('Could not restore checkout credentials')
+  }
+  let values = new Map(Object.entries(parsed as Record<string, string>))
+  const commit = (next: Map<string, string>) => {
+    SecureStore.setItem(key, JSON.stringify(Object.fromEntries(next)), {
+      keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+      requireAuthentication: false,
+    })
+    values = next
+  }
+  return {
+    getItem: name => values.get(name) ?? null,
+    setItem: (name, value) => { const next = new Map(values); next.set(name, value); commit(next) },
+    removeItem: name => { const next = new Map(values); next.delete(name); commit(next) },
+  }
 }
+```
 
-const queryClient = new QueryClient()
+This illustrative adapter does not request biometric authentication. Account
+for OS storage size limits, backup/restore policy, device locking and write
+failures in the host; synchronous storage can block the JS thread. If your
+persistence API is asynchronous, hydrate a synchronous mirror before setup,
+serialize its writes, implement `flush`, and await the final flush after every
+credential-changing operation before telling the user that persistence
+succeeded. Built-in auth completion does not await that final flush for you.
+Do not pass promises or async functions as the three synchronous methods. A
+corrupt snapshot or unavailable OS store must be handled explicitly; do not
+silently report durable sign-in. Migrate old credentials securely or require
+sign-in again.
 
-export default function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <EmbeddedCheckout eventId="14304" />
-    </QueryClientProvider>
-  )
+```ts
+// checkoutSetup.ts
+import { configureCheckout } from 'tf-checkout-react-native'
+import { restoreCredentialStorage } from './credentialStorage'
+
+let initialization: Promise<void> | undefined
+export function prepareCheckout(): Promise<void> {
+  if (!initialization) {
+    initialization = (async () => {
+      const storage = await restoreCredentialStorage('my_app_checkout_prod')
+      configureCheckout({
+        env: 'PROD',
+        clientId: 'YOUR_PUBLIC_SDK_CLIENT_ID',
+        clientSecret: '',
+        storage,
+      })
+    })().catch(error => { initialization = undefined; throw error })
+  }
+  return initialization
 }
 ```
 
-Copy the [Expo example's credential-storage mirror](example/src/credentialStorage.ts)
-or supply your own OS-protected adapter. The [complete example startup gate](example/src/app/_layout.tsx)
-waits for restoration before mounting checkout and offers retry on failure.
-Install `expo-secure-store` only if your host uses that example; the SDK adds no
-Expo storage peer. Bare React Native hosts can use their own Keychain/Keystore
-integration through the same `StorageAdapter` contract. The backend still validates
-every restored session. Setup does not read/probe storage or prove its security.
-The runnable example uses actual synchronous OS writes after hydration. If your
-host chooses asynchronous writes instead, built-in auth completion does not await
-the final flush automatically; follow the [host completion contract](../../docs/integration/native-session-storage.md).
+Configuration fields:
 
-### Checkout sessions and account scope
+| Field | Meaning |
+| --- | --- |
+| `clientId`, `clientSecret` | Required strings. Public checkout uses a registered public SDK ID and empty secret. |
+| `storage` | Required host-owned synchronous `StorageAdapter`, restored before setup. |
+| `env` | `PROD` (default, `www.ticketfairy.com`), `STAG` (`test.ticketfairy.com`) or `DEV` (`sandbox.ticketfairy.com`). |
+| `baseUrl` | Optional host origin overriding `env`; the SDK appends `/api`. Use only a trusted host. |
+| `sourceOrigin` | Optional `X-Source-Origin` header value. |
+| `auth` | Optional synchronous callback returning additional request headers. Treat credentials in headers as sensitive; the native wrapper also forces header-only session mode and no-store/no-cache. |
+| `cookieAuth` | Defaults to `true` on native. The native wrapper forces `withCredentials: false`; its header-backed session is stored via the adapter, rather than relying on ambient OS cookies. |
+| `accountAuth` | Opt in only for an authorized first-party full-account journey and deployed backend. Defaults off. |
+| `browserAuth`, `sdkCheckoutBrowserAuth` | Optional platform ports for supported browser authentication. The host owns secure proof generation and browser/callback handling. |
+| `sdkCheckoutPhoneAuth` | Opt in only when the corresponding first-party checkout phone journey is deployed. |
 
-The native wrapper defaults `cookieAuth` to true and disables ambient native
-cookie handling. Owned credentials use the SDK's header-backed session storage.
-Public checkout sign-in preserves the event-bound guest carrier and keeps its
-buyer credential server-side; it does not return a full-account ticket or grant
-private account access. First-party full-account flows explicitly use
-`accountAuth: true`; see the shared identity contract below.
+A restored session is still validated by the backend. Public checkout sign-in
+preserves the event-bound guest cart and keeps the checkout buyer credential
+server-side; it does not return a full-account ticket or grant private account
+access. Do not infer full account authorization from checkout authentication.
 
-### Environments
+## Embed a checkout
 
-```ts
-export async function prepareStagingCheckout() {
-  const storage = await restoreCredentialStorage('my_app_checkout_stag')
-  configureCheckout({
-    env: 'STAG',
-    clientId: 'PUBLIC_SDK_CLIENT_ID',
-    clientSecret: '',
-    storage,
-  })
-}
-```
-
-`PROD` → `www.ticketfairy.com`, `STAG` → `test.ticketfairy.com`, `DEV` →
-`sandbox.ticketfairy.com`. Pass `baseUrl` to point elsewhere.
-
-## `<EmbeddedCheckout />`
-
-| Prop                                | Type                                | Default     | Does                                          |
-| ----------------------------------- | ----------------------------------- | ----------- | --------------------------------------------- |
-| `eventId`                           | `string`                            | —           | The event to sell. Required.                  |
-| `onComplete`                        | `(order: PlaceOrderResult) => void` | —           | Fires once payment settles.                   |
-| `confirmationMode`                  | `'inline' \| 'redirect'`            | `'inline'`  | `redirect` leaves routing to `onComplete`.    |
-| `initialView`                       | `'tickets' \| 'seats'`              | `'tickets'` | Opening screen.                               |
-| `onViewChange`                      | `(view) => void`                    | —           | Reports the visible view.                     |
-| `requireEmailConfirmation`          | `boolean`                           | `true`      | Make guests repeat their email.               |
-| `collectTicketHolders`              | `boolean`                           | `true`      | One named holder per ticket.                  |
-| `collectHolderContact`              | `boolean`                           | `true`      | Also collect holder email/phone.              |
-| `skipBillingWhenProfileComplete`    | `boolean`                           | `false`     | Skip billing for complete signed-in profiles. |
-| `auth`                              | `false \| AuthOptions`              | built-in    | Configure or remove the login modal.          |
-| `onLogin`                           | `(email?: string) => void`          | —           | Open your own login UI instead.               |
-| `privacyPolicy`                     | `CheckoutPrivacyPolicy`             | —           | Your privacy policy link and brand name.      |
-| `additionalConditions`              | `EventCondition[]`                  | —           | Extra acknowledgements.                       |
-| `ttfOptInLabel` / `brandOptInLabel` | `string`                            | —           | Override the marketing opt-in copy.           |
-| `initialPromoCode`                  | `string`                            | —           | Apply a promo code on load.                   |
-| `referrer`                          | `string \| number`                  | —           | Attribute the sale.                           |
-| `showTestCardHint`                  | `boolean`                           | `false`     | Show sandbox card copy. Demos only.           |
-| `theme`                             | `CheckoutTheme`                     | —           | Recolor via design tokens.                    |
-
-`readAttributionFromUrl` is accepted for parity with web and is a no-op —
-there is no `window.location` on a device.
-
-## Theming
+Mount only after `prepareCheckout` resolves. `EmbeddedCheckout` provides its own
+`CheckoutProvider` and React Query client. Any separate React Query hooks outside
+that subtree need a `QueryClientProvider` of their own.
 
 ```tsx
-<EmbeddedCheckout
-  eventId="14304"
-  theme={{ colorScheme: 'dark', accent: '#ff2d55', radiusCard: 16 }}
-/>
+import React, { useEffect, useState } from 'react'
+import { Button, Text, View } from 'react-native'
+import { EmbeddedCheckout, type PlaceOrderResult } from 'tf-checkout-react-native'
+import { prepareCheckout } from './checkoutSetup'
+
+export default function EventCheckout() {
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading')
+  const [attempt, setAttempt] = useState(0)
+  const [order, setOrder] = useState<PlaceOrderResult | null>(null)
+  useEffect(() => {
+    let active = true
+    prepareCheckout().then(() => { if (active) setStatus('ready') })
+      .catch(() => { if (active) setStatus('error') })
+    return () => { active = false }
+  }, [attempt])
+
+  if (status === 'error') return (
+    <View><Text>Could not prepare checkout.</Text>
+      <Button title="Try again" onPress={() => { setStatus('loading'); setAttempt(n => n + 1) }} />
+    </View>
+  )
+  if (status !== 'ready') return <Text>Preparing checkout…</Text>
+
+  if (order) return (
+    <View>
+      <Text>Order submitted: {order.orderHash}. Check payment status before fulfillment.</Text>
+      {order.pending && <Text>Payment pending.</Text>}
+      {order.pendingVoucherUrl && <Text selectable>{order.pendingVoucherUrl}</Text>}
+      {order.needIdVerification && <Text>Identity verification is required.</Text>}
+      {order.free && <Text>Check if registration needs approval or verification.</Text>}
+    </View>
+  )
+  return <EmbeddedCheckout eventId="YOUR_EVENT_ID" confirmationMode="redirect"
+    onComplete={setOrder} />
+}
 ```
 
-The same token names as web: color (`accent`, `surface`, `text`, `muted`,
-`border`, `error`, `success`), shape, and typography. Read them anywhere with
-`useTheme()`.
-
-## Composing your own layout
-
-Every section reads the same `useCheckout()` store from the provider.
+`onComplete` is an order result, not proof of settled payment. `pending: true`
+requires pending instructions, but `pending !== true` also does not prove
+capture or settlement. `confirmationMode="inline"` (default) shows the stock
+receipt, which can say tickets are confirmed for a non-pending order before
+final capture/settlement. Hosts requiring verified paid status should use
+`"redirect"` or custom UI and reconcile with the authoritative backend and
+provider before presenting that status or fulfilling. Redirect mode delegates
+routing to `onComplete` and keeps checkout mounted during handoff; the host owns
+navigation. The example shows a local fallback, not a complete status screen:
+the host must implement reconciliation, retain the order reference and voucher
+across its navigation/restart, and arrange verification when required. Validate
+provider URLs against the host's policy before opening them.
+
+### `EmbeddedCheckout` props
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `eventId: string` | required | Event to sell. |
+| `onComplete?: (order: PlaceOrderResult) => void` | — | Reports ticket or bundle result; reconcile payment status, even if not marked pending. |
+| `confirmationMode?: 'inline' \| 'redirect'` | `inline` | Show receipt inline or let host route. |
+| `confirmationChildren?: ReactNode` | — | Content inside the inline ticket receipt, e.g. `Rewards`. |
+| `initialView?: 'tickets' \| 'seats'` | `tickets` | Initial selection screen. |
+| `onViewChange?: (view) => void` | — | Reports `tickets`, `seats` or `checkout`. |
+| `requireEmailConfirmation?: boolean` | `true` | Require matching guest email confirmation. |
+| `collectTicketHolders?: boolean` | `true` | Collect one named holder per ticket. |
+| `collectHolderContact?: boolean` | `true` | Also collect holder email/phone when holder details are shown. |
+| `skipBillingWhenProfileComplete?: boolean` | `false` | May hide billing for a complete profile; see the privacy-policy interaction below. |
+| `onLogin?: (email?: string) => void` | — | Use host login instead of the built-in modal. |
+| `auth?: false \| object` | built-in | `false` removes built-in auth; otherwise supports `allowRegistration`, `allowPasswordReset`, `requireRegistrationAddress`, `logoUrl`, `onCheckoutAuthenticated` and `onAuthenticated`. `onLogin` takes precedence. |
+| `privacyPolicy?: CheckoutPrivacyPolicy` | — | Host policy: `{ url, brandName, linkLabel? }`; requires acknowledgment. |
+| `additionalConditions?: EventCondition[]` | `[]` | Extra required/optional acknowledgment blocks. |
+| `ttfOptInLabel`, `brandOptInLabel` | SDK copy / absent | Label overrides; `privacyPolicy` reuses the Ticket Fairy opt-in value. See consent limitations below. |
+| `initialPromoCode?: string`, `referrer?: string \| number` | — | Explicit attribution supplied by the host. |
+| `readAttributionFromUrl?: boolean` | accepted, no-op | Native has no browser URL to read. |
+| `pickImage?: CheckoutImagePicker` | — | Host OS image picker for applicable questions. |
+| `showTestCardHint?: boolean` | `false` | Sandbox demo copy only; keep off in production. |
+| `theme?: CheckoutTheme` | light tokens | Partial token overrides. |
+
+`pickImage` is `() => Promise<{ base64: string; width?: number; height?: number } | null>`.
+Return raw base64, not a data URI, or `null` for cancellation. The SDK checks
+base64 encoding and the image signature, the 2 MiB maximum and any supplied
+dimensions (at most 4096 pixels per side); the server validates decoded bytes.
+The host owns permission and picker UX. For the separate event discussion picker, see its props below.
+
+## Compose sections and navigation
+
+`CheckoutProvider` owns a native `useCheckout()` instance, a query provider,
+theme and the built-in provider-page and installment modals. Sections inside
+it share the app checkout store. `useCheckoutContext()` reads this instance and
+throws outside the provider. The following intentionally uses one combined
+billing/payment form after reservation; callbacks route tickets and seats.
 
 ```tsx
+import React, { useState } from 'react'
+import { ScrollView, Text, View } from 'react-native'
 import {
-  CheckoutProvider,
-  Tickets,
-  AddOns,
-  BillingInfo,
-  Payment,
-  OrderSummary,
-  useCheckout,
+  CheckoutProvider, Tickets, SeatMap, AddOns, BillingInfo, WaiverSigning,
+  OrderSummary, Payment, IDVerification, useCheckoutContext,
+  type PlaceOrderResult,
 } from 'tf-checkout-react-native'
 
-const MyCheckout = () => (
-  <CheckoutProvider theme={{ colorScheme: 'dark' }}>
-    <ScrollView>
-      <Tickets />
-      <AddOns />
-      <BillingInfo />
-      <OrderSummary />
-      <Payment />
+function Flow({ eventId, onComplete }: {
+  eventId: string
+  onComplete: (order: PlaceOrderResult) => void
+}) {
+  const [view, setView] = useState<'tickets' | 'seats' | 'checkout'>('tickets')
+  const checkout = useCheckoutContext()
+  if (checkout.status === 'succeeded' && checkout.order) return (
+    <View>
+      <Text>Order submitted: {checkout.order.orderHash}. Check payment status.</Text>
+      {checkout.order.pending && <Text>Payment pending.</Text>}
+      {checkout.order.pendingVoucherUrl && <Text selectable>{checkout.order.pendingVoucherUrl}</Text>}
+      <IDVerification />
+    </View>
+  )
+  return (
+    <ScrollView keyboardShouldPersistTaps="handled">
+      {view === 'tickets' && <Tickets eventId={eventId}
+        onSelectSeats={() => setView('seats')}
+        onContinue={() => setView('checkout')} />}
+      {view === 'seats' && <SeatMap eventId={eventId}
+        onContinue={() => setView('checkout')} />}
+      {view === 'checkout' && <>
+        <AddOns eventId={eventId} />
+        <BillingInfo eventId={eventId} requireEmailConfirmation
+          collectTicketHolders collectHolderContact />
+        <WaiverSigning eventId={eventId} />
+        <OrderSummary eventId={eventId} />
+        <Payment requireEmailConfirmation collectTicketHolders requireHolderContact
+          onComplete={onComplete} />
+      </>}
     </ScrollView>
-  </CheckoutProvider>
-)
-```
-
-**Sections** — `Tickets`, `AddOns`, `BillingInfo`, `OrderSummary`, `Payment`,
-`IDVerification`, `Confirmation`.
-
-**UI primitives** — `Card`, `Button`, `BodyText`, `MutedText`, `Field`,
-`Select`, `QuantitySelect`, `PaymentMethods`, `Timer`, `TimerBanner`.
-
-**Auth** — `AuthModal`, `LoginForm`, `RegisterForm`, `ForgotPasswordForm`,
-`ResetPasswordForm`.
+  )
+}
 
-## Headless
+export function ComposedCheckout({ eventId, onComplete }: {
+  eventId: string
+  onComplete: (order: PlaceOrderResult) => void
+}) {
+  return <CheckoutProvider><Flow eventId={eventId} onComplete={onComplete} /></CheckoutProvider>
+}
+```
 
-`useCheckout()` gives you the whole flow with no UI.
+`AddOns` can render nothing when there are no applicable items; do not make a
+navigation transition depend solely on its `onContinue` unless your host handles
+that case. With no `onContinue`, `AddOns` and `BillingInfo` use combined-form
+behavior. Match `BillingInfo`'s email/holder policy to `Payment`'s
+`requireEmailConfirmation`, `collectTicketHolders` and `requireHolderContact`.
+The composed example renders the verification control for a required order;
+the buyer must press Verify. Before changing event, leaving payment or starting
+another cart, handle in-flight and retained orders as described under
+[safe completion](#payments-and-safe-completion).
+
+`CheckoutProvider` props: `children` (required), `theme`, `pickImage`,
+`options` (wallet/redirect `CheckoutOptions`), `paymentSheet`, `queryClient`,
+and `value`. Omit `value` to let the provider create the native hook, provider
+page and installment picker. If supplying `value`, create it with the native
+`useCheckout` and provide any necessary ports yourself; `options` and
+`paymentSheet` on a controlled provider do not configure that value. Keep the
+choice of controlled versus self-provided stable for the mount. A custom query
+client can be supplied with `queryClient`. `CheckoutThemeProvider` supplies only
+theme, not checkout state or a query client.
+
+## Checkout section reference
+
+Unless noted, these sections read checkout state from `CheckoutProvider` and
+are imported from `tf-checkout-react-native`. All props are optional except
+those marked **required**. Prop interfaces are represented on the component in
+the published declarations; not every `*Props` name is itself a top-level type
+export. Derive one if needed with `React.ComponentProps<typeof Tickets>`.
+
+### `Tickets`
+
+Loads the catalog, quantities, promo/access-code and waiting-list controls,
+currency and time slots when offered. Reserves/prices the cart before calling
+`onContinue`.
+
+| Prop | Description |
+| --- | --- |
+| `eventId: string` | **Required** event ID. |
+| `onContinue?: () => void` | Cart was primed; reveal the next screen. |
+| `onSelectSeats?: () => void` | Show a seat map for seated events. Without it the seat CTA is hidden. |
+| `title?: string \| false` | Catalog heading; default `false`. |
+| `buttonLabel?: string` | Reserve CTA; default `Get tickets`. |
+| `timeSlotDates?: string[]` | Force time-slot selection with ISO `yyyy-mm-dd` dates; omit to use event data. |
+| `initialPromoCode?: string`, `referrer?: string \| number` | Apply/attribute once on mount. |
+| `readAttributionFromUrl?: boolean` | Accepted for web parity; does nothing on native. |
+| `unstyled?: boolean` | Place catalog in the host's own container. |
+| `renderTicket?: (row) => ReactNode` | Replace row visuals. `row` has `ticket`, `quantity`, `range: {min,max,step}`, `unavailable`, `seated`, `onQuantityChange`. |
+| `renderContinue?: (cta) => ReactNode` | Replace CTA; `cta` has `onPress`, `disabled`, `loading`, `title`. |
+
+The render callbacks retain SDK selection/reservation logic. Preserve the
+provided disabled/loading state and accessible labels in custom UI.
+
+### `SeatMap`, `AddOns`, `Bundles`, `Accommodation`
+
+| Component | Props and behavior |
+| --- | --- |
+| `SeatMap` | **`eventId`**; `onContinue?` after a seat cart is primed. Internal or Seats.io maps render through WebView. The event and backend must support the chart, hold and cart contracts. |
+| `AddOns` | **`eventId`**; `onContinue?`, `onSkip?`, `buttonLabel?`, `eyebrow?`, `heading?`. Saves quantities and add-on answers; skip is hidden when a required add-on exists. It may render nothing. |
+| `Bundles` | **`eventId`**; `onPurchased?(orderHash)`, `onComplete?(order)`, `confirmationMode?: 'inline' \| 'redirect'`, `visible?`, `heading?`, `locale?`, `messages?`, `translate?`. Bundles use their own purchase/order flow, not the ticket cart. Set `visible={false}` while hidden so its card field is not mounted. |
+| `Accommodation` | **`eventId`**. Composes stay selection, quote and reservation state for supported events. Availability and authoritative prices come from the server. |
+
+### `BillingInfo`
+
+Collects buyer, order-level and ticket-holder answers, then saves them into the
+shared checkout. With `onContinue`, it has a continue button; without it, edits
+are committed in the combined form. It uses event gates and may show additional
+required fields. All props are optional:
+
+| Prop | Description |
+| --- | --- |
+| `eventId?: string` | Event context for country defaults. |
+| `onContinue?: () => void` | Called after valid billing is saved. |
+| `heading?`, `buttonLabel?` | Copy overrides. |
+| `onLogin?: (email?: string) => void` | Offer sign-in, including an email already associated with an account. |
+| `skipWhenProfileComplete?: boolean` | May hide the card for a complete signed-in profile; default `false`. Do not combine with `privacyPolicy` without a verified workaround. |
+| `requireEmailConfirmation?: boolean` | Require guest email confirmation; standalone default `false`. |
+| `collectTicketHolders?: boolean` | Require named holders beyond event gates; standalone default `false`. |
+| `collectHolderContact?: boolean` | Collect holder email and phone when holders are shown; standalone default `false`. |
+| `ttfOptInLabel?`, `brandOptInLabel?` | Label overrides; privacy and Ticket Fairy opt-in share a value when `privacyPolicy` is supplied. |
+| `privacyPolicy?: { url: string; brandName: string; linkLabel?: string }` | Host policy and required acknowledgment. |
+| `showPrivacyError?: boolean` | Show inline privacy error after a failed attempt. |
+| `step?: ReactNode` | Accepted for API parity but not rendered by native `SectionHeader`. |
+
+### `OrderSummary`, `WaiverSigning`, `Payment`, `IDVerification`, `Confirmation`
+
+| Component | Props and behavior |
+| --- | --- |
+| `OrderSummary` | `eventId?`, `locale?`, `messages?`, `translate?`. Displays server-priced cart totals and optional event name. |
+| `WaiverSigning` | **`eventId`**; `locale?`, `messages?`, `translate?`. Renders only when the event has a waiver; supports the server-offered signing methods. |
+| `Payment` | `onComplete?(order)`, `eventId?` (currently unused by native payment), `requireEmailConfirmation?`, `collectTicketHolders?`, `requireHolderContact?`, `additionalConditions?`, `requirePrivacyPolicy?`, `onPrivacyRequired?`, `showTestCardHint?`, `locale?`, `messages?`, `translate?`. Standalone boolean defaults are false. It validates, renders eligible methods and submits. |
+| `IDVerification` | No props. When required, it shows a Verify button; the buyer must press it to open and poll the provider. A stall proves neither failure nor settlement. |
+| `Confirmation` | `shareUrl?`, `shareMessage?`, `viewOrderUrl?`, `message?`, `children?`. Reads the current order. Its stock title and share copy do not independently verify payment settlement or referral eligibility; see below. |
+
+`Payment` gates its rendered event conditions, host `additionalConditions` and
+requested privacy acknowledgment in its UI. Each `EventCondition` is
+`{ id: string, name: string, content: string, isRequired: boolean }`. These
+acknowledgments are client-side and are not sent as separate server fields.
+Conditions use native `RichText`, which filters tags/styles and opens only
+HTTP(S) links; its rendering is not browser HTML parity. A headless
+`placeOrder` checks loaded event conditions in the engine, but does not receive
+host `additionalConditions` or enforce the UI privacy gate. Headless hosts must
+implement and test their own required host acknowledgments before placement.
+
+`Rewards` renders order-scoped rewards, a referral tree, ladder, packs and a
+native share sheet. Pass `orderHash` or an already loaded `data` payload; it also
+accepts `locale`, `messages`, `translate`. Embed it as a `Confirmation` child,
+or use `confirmationChildren` on `EmbeddedCheckout`. `RewardsTree` accepts
+**`tree`** and optional `size` (default 260); `RewardsLadder` accepts **`rows`**,
+**`translate`** and optional async `onSubmitDetails(awardId, details)`.
+Account-level `AccountRewardsSection` has separate read-only account semantics.
+`Rewards` uses the server's `share_link` and hides itself when
+`referrals_enabled` is explicitly false. Verify the returned eligibility and
+buyer-specific link against your deployed contract. Standalone `Confirmation`
+displays reward-promising share copy for any non-pending order when `shareUrl`
+is supplied, without checking eligibility or generating a buyer-specific link.
+Omit it unless your host has verified both; `EmbeddedCheckout` does not expose a
+`shareUrl` prop. The example below omits that block and assumes the host has
+already verified the status required to show confirmed receipt copy, and the
+original result was not pending. `Confirmation` reads the original
+`checkout.order.pending`; it does not refresh that flag after later settlement.
+Use a host status UI based on a fresh authoritative read for an asynchronously
+settled order.
 
 ```tsx
-const checkout = useCheckout({ eventId: '14304' })
+import { Confirmation, Rewards, useCheckoutContext } from 'tf-checkout-react-native'
 
-await checkout.setTickets('14304', [{ ticketTypeId: '1', quantity: 2 }])
-checkout.setBilling({ firstName, lastName, email, phone })
-checkout.setConsent({ ttfOptIn: true, brandOptIn: false })
-const order = await checkout.placeOrder('card')
+function Receipt({ verified }: { verified: boolean }) {
+  const checkout = useCheckoutContext()
+  if (!verified || checkout.order?.pending) return null
+  return (
+    <Confirmation>
+      {checkout.order?.orderHash ? <Rewards orderHash={checkout.order.orderHash} /> : null}
+    </Confirmation>
+  )
+}
 ```
 
-`placeOrder` is retry-safe: one order, one charge, however many times the button
-is pressed.
-
-### Starting a new checkout
-
-`reset()` discards the cart. It returns nothing, so
-`useEffect(() => checkout.reset(), [eventId])` works as it always has. Before
-any money moves it resets at once. While a payment is going through, it waits
-for the payment to finish, so the payment never lands in a new cart. An order
-that is not confirmed yet is kept when it is charged, or when a payment step
-failed without an answer that nothing was charged (a network error, a
-timeout, or a Stripe error that is not a decline or a cancel). A Razorpay or
-redirect payment page the buyer closes is kept only when a check of the order
-fails or finds a payment; otherwise it is a cancel. Pressing Pay again then
-finishes the order, or pays as usual when nothing was paid. A server refusal
-of the order, such as an expired reservation, releases it.
-
-To know which happened, await `resetWhenSettled()` instead. It resolves `true`
-once the checkout is reset, or `false` when it kept the order. In that case,
-show the buyer `PAID_ORDER_PENDING_MESSAGE`. While it waits for a payment
-(`status === 'placing'`), tell the buyer, for example "Finishing your
-payment…":
+## Tickets, seats, codes and attribution
+
+Use the server's current event catalog and displayed prices. Time-slot ticket
+IDs encode their selected session. `Tickets` supports ticket quantities,
+groups, promo/access codes, waiting-list forms and seat-map routing when the
+backend offers them. Waiting-list availability is a separate, authoritative
+catalog contract; a sold-out row alone does not imply that a list is open.
+
+Unlike 1.x, native `Tickets` has no password prompt or password prop. For a
+password-protected event, a host can collect the password and call
+`ttf.events.authenticate(eventId, password)`, handle wrong-password and session
+errors, then refetch the event/catalog for the same buyer and event context.
+Keep the password out of logs and verify the deployed password/session contract
+and the refreshed result; the API call alone is not proof of a working native
+unlock flow.
+
+For a headless flow, `TicketSelection` has `id`, `name`, `optionName`, `price`,
+`quantity` and `currency`. Build it from current catalog data and call
+`setTickets(eventId, selections)`. `setSeats` takes server-reserved `SeatLine`s;
+`setSeatsIo` takes a `SeatsIoSelection`. Do not fabricate seat holds. The
+native `SeatMap` drives the chart and shared selection controller; provider
+holds, server cart acceptance and actual device behavior need separate testing.
+
+Quantity retention across rotating encrypted IDs requires deployed canonical
+`selectionKey`s and dated numeric context (`display_price`, `price_with_fees`,
+`fee_included`, `price_currency`, `price_symbol`). Without those optional keys,
+opaque-ID compatibility remains; rotation retention is not guaranteed.
+
+Supply `initialPromoCode` and `referrer` explicitly to `EmbeddedCheckout` or
+`Tickets`, or use `applyPromoCode` / `attributeReferrer` from the hook. Native
+`readAttributionFromUrl` is a no-op; the host must parse and classify incoming
+links. An ambiguous numeric `?r=` can be a promo or referral. Do not send it as
+a referral without authoritative classification. This beta does not reproduce
+every hosted conditional-field visibility rule; conditional requiredness is
+left to the backend. Test your event's fields and referral/promo links against
+the deployed service before relying on parity.
+
+Post-purchase upgrade waiting is server-owned and separate from the event
+waiting list. `TicketChange` exposes it only for valid targets actually offered
+by the server; a sold-out ticket is not sufficient. Validate the organizer's
+configuration and deployed join/leave behavior.
+
+## Billing, custom fields and consent
+
+`CheckoutBilling` requires `firstName`, `lastName` and `email`. Other fields
+include `confirmEmail`, phone, address, `countryId`/`stateId` (backend numeric
+IDs encoded as strings), `countryCode`/`stateCode` (payment billing codes), DOB,
+`nationality`, `gender`, `instagramHandle` and order `dataCapture`. A
+`CheckoutHolder` requires `firstName`, `lastName`, `email` and may include
+`phone`, numeric `ticketTypeId` as a string and ticket `ticketDataCapture`.
+`CheckoutConsent` is `{ ttfOptIn: boolean, brandOptIn: boolean }`.
+
+The event supplies `buyerFields`, `fieldGates`, `customFields`, `conditions`,
+required add-ons and waiver requirements. Use the server's ticket breakdown to
+associate holder answers with ticket types. Add-on capture is separately keyed by
+add-on ID. Do not hard-code a minimal buyer form as valid for every event. The
+standalone `BillingInfo` default is less strict than `EmbeddedCheckout`'s holder
+and email-confirmation defaults; match it with the paired `Payment` props. The
+SDK's confirmation email value is a UI check; the order API uses the primary
+email. Recheck terms, privacy and marketing consent with your own policy.
+
+**Beta.23 consent limitation:** when `privacyPolicy` is supplied, the stock
+privacy checkbox reads and writes `consent.ttfOptIn`, which the order sends as
+`ttf_opt_in`. It is not independent of the Ticket Fairy marketing flag. The
+brand opt-in uses a separate value. If both opt-in labels are explicitly empty,
+`BillingInfo` can skip committing consent even while it shows the privacy
+checkbox, leaving the payment gate blocked. Also, enabling
+`skipBillingWhenProfileComplete` (or standalone `skipWhenProfileComplete`) can
+hide that checkbox while `Payment` still requires it. Avoid those combinations
+without a verified host workaround; where separate privacy and marketing consent
+is required, use a custom flow and a tested backend consent contract.
+
+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. Only a failed waiver read (except a 404) is
+recorded in `unavailableDetails` and retried/gated. 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.
+
+Waiver signatures are separate from holder fields. The waiver component reads
+the event's permitted methods and stores the uploaded signature reference. If
+waiver details could not be loaded, placement waits/retries that read rather
+than assuming no waiver. Image questions require a host `pickImage` adapter.
+
+## Payments and safe completion
+
+`Payment` uses server event/method configuration and device support. Free
+orders, card, native wallets, payment plans, OXXO, provider pages and other
+methods are different paths; an SDK export does not enable a method on your
+account. The server's review and breakdown are authoritative for amount,
+currency and receiving account. Never collect PAN or CVC in your JS form or
+logs. Use the provider-owned card field or eligible PaymentSheet.
+
+### Result, retry and reset
+
+`PlaceOrderResult` includes `orderHash`, `free`, `needIdVerification`, optional
+`currency`, `paymentIntentId`, `alreadyPaid`, `pending` and
+`pendingVoucherUrl`. `pending: true` represents an asynchronous result such as
+an OXXO voucher or PayPal settlement. Show pending instructions and verify
+status with the backend/provider; do not label it paid or fulfill it as paid.
+Conversely, `pending !== true` and `status === 'succeeded'` are not settlement
+proof: Stripe `Processing` and `RequiresCapture` can produce a result without
+`pending`. The stock non-pending receipt can show confirmed copy before final
+capture. Reconcile the authoritative order/provider status and use custom or
+redirect routing when your fulfillment policy requires verified payment.
+When `needIdVerification` is true, the host must arrange a separate verification
+journey. Inline `IDVerification` requires the buyer to press Verify; redirect
+mode does not render it. A composed host can render `IDVerification` under the
+active `CheckoutProvider`, or call `runIdVerification(orderHash)` from a custom
+flow. Handle navigation/returns; a failed or delayed verification proves neither
+payment failure nor settlement.
+
+**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
+`EmbeddedCheckout` can nevertheless say registration is complete and the buyer
+is registered while approval or verification is still outstanding. Use
+`confirmationMode="redirect"` with host-owned authoritative order and
+verification status, or a custom composed confirmation gated on that status.
+If the status is unavailable, contact support. Do not retry payment for a free
+order.
+
+`status` is `idle`, `priming`, `ready`, `repricing`, `placing`, `succeeded`,
+`expired` or `error`. Disable repeated submissions while `isBusy` or `placing`,
+show the reservation countdown and handle expiry. The engine coordinates
+concurrent placement and can retain the original order when payment may have
+moved. A timeout, dismissed provider page, navigation or app interruption is
+not proof that no payment occurred. Reconcile the original order with your
+backend and payment provider before retrying a purchase or fulfilling it. This
+is not an exactly-once charging guarantee across every host/provider.
+
+`reset()` starts a reset and returns no completion signal. Prefer
+`await resetWhenSettled()` when navigating to a new checkout: it waits for an
+in-flight payment and returns `true` only if reset completed. `false` can mean
+the original order is retained or the checkout was retired. Show
+`PAID_ORDER_PENDING_MESSAGE` where appropriate and reconcile; do not clear the
+store, start a new order or promise a refund merely to bypass this guard. A
+custom `providerPage` must settle on close/unmount with `{ event: 'dismiss' }`;
+other custom async ports must settle too, or reset can wait indefinitely.
 
 ```tsx
-if (checkout.status === 'placing') setNotice('Finishing your payment…')
-if (!(await checkout.resetWhenSettled())) setNotice(PAID_ORDER_PENDING_MESSAGE)
-```
+import { PAID_ORDER_PENDING_MESSAGE, useCheckoutContext } from 'tf-checkout-react-native'
 
-A custom `providerPage` must resolve `'dismiss'` when it closes or unmounts, and
-any other custom port must settle then too, or `resetWhenSettled()` waits for it.
+function useStartAgain(setNotice: (message: string) => void) {
+  const checkout = useCheckoutContext()
+  return async () => {
+    if (checkout.status === 'placing') setNotice('Finishing your payment…')
+    if (!(await checkout.resetWhenSettled())) setNotice(PAID_ORDER_PENDING_MESSAGE)
+  }
+}
+```
 
-A custom confirmer marks a decline or cancel by rejecting with
-`paymentProviderError(message, 'declined' | 'cancelled')`. Any other rejection
-counts as a payment that may have gone through, so the order is kept.
+`TtfError` exposes `message`, HTTP `status` (`0` for transport failure),
+optional backend `code`, `data` and `retryAfter` seconds. `errorMessage(error)`
+and `isCartExpiredError(error)` help with display and expiry handling. Do not
+log tokens, raw payment credentials or sensitive buyer data. An error after
+payment initiation can be ambiguous even when its UI says to retry.
 
-The full SDK is re-exported from this package — `ttf`, `api`, `hooks`, `dtos`,
-`logic`, and the engine. See the [SDK reference](https://github.com/theticketfairy/tf-shared-libraries/blob/main/packages/tf-checkout-shared/README.md).
+A custom confirmer can reject with `paymentProviderError(message, outcome)`:
+`declined`, `cancelled`, `notStarted` or `unknown`. Only classify the first
+three when the provider establishes that no charge occurred. Other rejections
+are treated as unknown. Preserve the original order and reconcile it.
 
-## Rewards
+### Stripe card and PaymentSheet
 
-The native analogue of the web Rewards section: standing, the referral tree,
-the prize ladder, packs, the share card, and one share button.
+By default, native `Payment` uses Stripe's native `CardInput` for an eligible
+card path. A host composing its own UI can opt into PaymentSheet on the
+provider. Use a static merchant name and scheme for the life of the mounted
+checkout. Configure the app to receive the same deep link and pass cold- and
+warm-start Stripe callback URLs to Stripe according to its React Native setup.
+The embedded component does not expose the PaymentSheet opt-in.
 
 ```tsx
-import { Confirmation, Rewards } from 'tf-checkout-react-native'
-;<Confirmation>
-  <Rewards orderHash={orderHash} />
-</Confirmation>
+import React from 'react'
+import { CheckoutProvider, Payment } from 'tf-checkout-react-native'
+
+export function PaymentStep() {
+  return (
+    <CheckoutProvider
+      options={{ urlScheme: 'myapp' }}
+      paymentSheet={{
+        merchantDisplayName: 'My Events',
+        returnURL: 'myapp://stripe-redirect',
+      }}
+    >
+      {/* Render the ticket, billing and consent sections in this provider too. */}
+      <Payment />
+    </CheckoutProvider>
+  )
+}
 ```
 
-When `<EmbeddedCheckout/>` renders the receipt itself, pass the block through
-`confirmationChildren`:
+The return URL must equal `${urlScheme}://stripe-redirect`; register the actual
+scheme in iOS and Android and route callbacks before normal navigation. A
+controlled provider must create its `value` with the same `paymentSheet` and
+`options` on `useCheckout` itself. Changing the config during a mount is not
+supported. In headless UI, use `checkout.paymentSheet?.placeOrder()` when
+available; the normal `Payment` section chooses it for the eligible card row.
+
+In beta.24 the sheet is limited to eligible non-MXN Stripe PaymentIntents whose
+original methods are card alone, or card plus Cash App Pay in USD. It does not
+admit delayed methods, create a new intent or add a Stripe Customer/saved-card
+contract. The SDK checks the original intent's identity, amount and currency
+against the order review. Where the method list or sheet setup cannot be
+admitted, the flow may ask for the native card form; a financial identity
+mismatch instead requires order review. MXN installment card payments and new
+card payment plans retain CardField. Account, event, device and provider
+eligibility still apply.
+
+Stripe may show card-mode Link when its account and session qualify; the SDK
+requests automatic Link display but cannot promise its availability. Link is
+not the same thing as OS/password-manager card autofill, which is also
+provider/device dependent. Test Link and callbacks on real devices and the
+actual receiving Stripe account.
+
+### Apple Pay, Google Pay and other providers
+
+Native wallet rows are separate from PaymentSheet. They appear only when the
+server enables the wallet, the corresponding OS/device supports it and Stripe's
+platform-pay check succeeds. Configure merchant entitlements and identifiers,
+the Stripe account, app scheme and native build for your app. The order review
+must supply valid wallet amount, currency and merchant country.
+A composed provider can pass:
 
 ```tsx
-<EmbeddedCheckout eventId={eventId} confirmationChildren={<MyRewards />} />
+<CheckoutProvider options={{
+  merchantIdentifier: 'merchant.com.example.app',
+  merchantName: 'My Events',
+  googlePayTestEnv: false,
+  urlScheme: 'myapp',
+}}>
+  {/* Render the ticket and billing sections in this provider too. */}
+  <Payment />
+</CheckoutProvider>
 ```
 
-Native adaptations, and why:
-
-- **No SVG.** The tree is positioned `View`s, from the same shared layout the
-  web SVG uses. Adding `react-native-svg` would be a new native peer for every
-  customer app; a dot-and-line picture does not need one.
-- **One share button.** Per-channel buttons collapse into `Share.share()` — the
-  OS sheet already lists every installed app, which is what the web's share
-  sheet channel reaches for through the browser.
-- **Copy comes in as props**, this package's idiom. `translate`, or `locale` and
-  `messages` for the built-in `rewards.*` catalogue.
+`CheckoutOptions` also accepts `stripePublishableKey` as an override and
+`redirectReturnUrl` and `merchantCountryCode`. Normally use the keys from the
+order review; do not hard code a connected account or infer it from the event.
+In this beta, native wallet confirmation takes merchant country from the
+authoritative order review rather than the `merchantCountryCode` option. The
+native confirmer uses `Order` as its merchant-name fallback; set your merchant
+name explicitly. The example matches the earlier `PROD` setup. For Google Pay,
+the `Payment` support probe uses test mode when `env` is `STAG` or `DEV`, while
+confirmation uses `options.googlePayTestEnv`. Set both consistently for the
+intended environment; a `baseUrl` override does not set `env`. Configure the
+native/plugin wallet setting and verify both the support probe and confirmation
+on device, especially with custom hosts. Expo settings, Apple entitlement,
+deep links and provider account approval are host responsibilities. Test
+eligibility, cancellation, return and settlement on each platform.
+
+`CheckoutProvider` without a controlled value supplies a WebView provider-page
+port and an installment picker. Provider pages may be used for PayPal,
+Razorpay, Xendit, Adyen or redirect methods when the backend enables them.
+Host routing and provider behavior still determine whether a particular flow
+works; check network, app-link, browser and return behavior on device. A
+headless `useCheckout` host must supply `ports.providerPage` and any other
+needed ports; `rnPorts` alone does not provide the provider-page UI. Its
+`providerPage` receives `{ uri?, html?, baseUrl?, returnUrlPrefix }` and resolves
+`{ event: 'success' | 'dismiss' | 'failed', returnUrl?, data?, description?,
+notOpened?, paymentOutcome? }`. Report `notOpened` or `paymentOutcome:
+'declined'` only when actually established. The engine still reconciles the
+provider outcome.
+
+### `CardInput` for custom payment UI
+
+`CardInput` props are `owner?: string` (default `checkout`),
+`visible?: boolean`, and `onComplete?: (complete: boolean) => void`. The
+native hook's default card claim uses the default owner. If multiple flows can
+mount card fields, give each its own owner and use the matching
+`claimCardField(owner)` and `cardClaimStep` as `placeOrder`'s `claimCard` option;
+otherwise one flow must not use another's field. Keep the field mounted and
+visible through its confirmation. `Payment` handles its own field ownership.
+Do not treat `onComplete` as confirmation or payment success.
+
+## Headless checkout
+
+`useCheckout()` is the native-wired React binding, not the old 1.x React Query
+mutation. It returns a flat `CheckoutSnapshot`, `snapshot`, `store`, derived
+state and actions. It injects the native Stripe confirmer and ports. Use it
+inside a React component after configuration, and supply a React Query provider
+where the host also uses query hooks. The app-wide checkout store is shared
+across native hook calls and provider sections: they are not independent carts.
 
-## Seat maps
-
-`SeatMap` uses the existing WebView peer to render internal charts or the event's
-Seats.io chart, with the shared core owning selection, holds and reservations.
-It requires the matching backend seating/session contracts. Provider-backed hold
-and deployed-cart acceptance remain separate checks; see the
-[seating contract and evidence](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/integration/app-sdk.md#seat-chart-and-ticket-refund-checkpoint--25-october-2026).
-
-## Known gaps vs web
-
-- **Smooth scroll** — no `scrollIntoView` equivalent, so `autoScroll` has no
-  native counterpart.
-
-## Development
-
-From the repo root:
-
-```bash
-pnpm run start:react-native
+```tsx
+import React, { useState } from 'react'
+import { Button, Text, View } from 'react-native'
+import { useCheckout, type TicketSelection } from 'tf-checkout-react-native'
+
+// selections must come from this event's current server catalog.
+export function Reserve({ eventId, selections }: {
+  eventId: string
+  selections: TicketSelection[]
+}) {
+  const checkout = useCheckout()
+  const [message, setMessage] = useState('')
+  const reserve = async () => {
+    try {
+      await checkout.setTickets(eventId, selections)
+      setMessage('Tickets reserved. Collect the required details next.')
+    } catch {
+      setMessage('Could not reserve tickets. Check availability and try again.')
+    }
+  }
+  return <View><Button title="Reserve" disabled={checkout.isBusy} onPress={() => { void reserve() }} />
+    <Text>{message}</Text></View>
+}
 ```
 
-`pnpm run playground:react-native` opens the playground mode instead.
+A real headless host must collect the event's gated buyer/holder data, custom
+answers, conditions, add-ons and waivers, render a provider-owned payment input
+or wallet/provider UI, validate against the event, and handle every result and
+error before placing an order. Enforce host privacy and `additionalConditions`
+yourself; the headless engine does not receive these `Payment` props. The short
+example only primes the cart.
+
+### Snapshot and actions
+
+| Member | Purpose |
+| --- | --- |
+| `status`, `error`, `order`, `orderFixed` | Lifecycle, error text, result and whether order inputs are frozen. |
+| `eventId`, `selections`, `ticketTypeIds`, `breakdown`, `priceBreakdown` | Current cart and server-priced display data. |
+| `secondsLeft`, `expiresAt`, `isBusy` | Countdown in whole seconds, absolute expiry in epoch ms and operation state. `secondsLeft` can be undefined. |
+| `customFields`, `buyerFields`, `fieldGates`, `holderNamesRequired` | Event-specific capture requirements. |
+| `requiredAddOns`, `missingRequiredAddonNames`, `addOns`, `addOnDataCapture` | Add-on requirements and selections. |
+| `billing`, `holders`, `consent`, `conditions`, `acceptedConditions` | Buyer data and acknowledgments. |
+| `waiver`, `waiverSignatures`, `waiverSigningIndexes`, `unavailableDetails` | Waiver state; `unavailableDetails` tracks waiver failures, not other failed detail reads. |
+| `gateway`, `stripe`, `paymentStripe`, `paymentPlan`, `redirectPaymentMethods`, `walletAvailability`, `currency` | Server/engine payment and currency context. Their presence is not a guarantee of provider eligibility. |
+| `extraItems`, `extraDraft`, `extraQuotes`, `extraRejections`, `extraExpiresAt`, `reviewedExtraOrderTotal` | Accommodation/extra reservation and price state. |
+| `setTickets(eventId, selections)` | Prime ticket cart and price it. |
+| `setSeats(eventId, lines)`, `setSeatsIo(eventId, selection)`, `resumeCart(eventId, options?)` | Prime a seat cart or attach to a supported existing cart. |
+| `setAddons(selection)` | Set add-on quantities and reprice; await it. |
+| `setExtraItems(items)`, `setExtraDraft(items \| undefined)` | Reserve or edit accommodation/extras. |
+| `setBilling(billing)`, `setHolders(holders, options?)`, `setConsent(consent)` | Commit buyer data; optional holder `backfilled` describes copies of buyer details. |
+| `setAcceptedConditions(map)`, `acceptCondition(id, accepted)` | Commit required/optional acknowledgment state. |
+| `setAddonDataCapture(capture)` | Set answers keyed by add-on ID. |
+| `holdWaiverSigning(index)`, `setWaiverSignature(index, signature, hold?)` | Bind a signature to its original cart/holder; release the returned hold after saving. |
+| `checkBuyerEmail(email)`, `reloadCheckoutDetails()` | Check for an existing account; retry an unavailable waiver read. |
+| `placeOrder(method?, options?)` | Place/pay via an eligible method; returns `Promise<PlaceOrderResult>`. Options include `autoRunIdVerification`, `idVerification`, `claimCard`. |
+| `runIdVerification(orderHash, options?)` | Open/poll verification as a separate post-order step. |
+| `syncCurrency(eventId, code?, options?)` | Seed/change currency; refetch catalog and re-prime as needed. |
+| `applyPromoCode(eventId, promo)`, `attributeReferrer(eventId, referrer)`, `joinWaitingList(eventId, entry)` | Event engagement helpers. |
+| `reset()`, `resetWhenSettled()` | Reset subject to payment safety; use the awaited form to know its outcome. |
+| `paymentSheet?.placeOrder()` | Present the explicitly configured eligible native sheet. May be absent. |
+
+`placeOrder` supports simple `'card'`, `'applePay'`, `'googlePay'` or typed
+`PaymentRequest` objects: `auto`, `card`, `applePay`, `googlePay`, `redirect`
+(with `methodType`), `oxxo`, `xenditEWallet` (with `walletKey` and optional extra),
+`paypal`, `razorpay`, `adyen`, `xenditCard`, or `paymentPlan`. A union member
+is not an availability promise. Render choices from server/provider eligibility
+and supply the required port. `UseCheckoutOptions` accepts `{ ports?, options?,
+paymentSheet? }`; ports merge over `rnPorts`. `createRnStripeConfirmer`,
+`createRnPorts`, `rnConfirmer` and `rnPorts` are exported for advanced hosts.
+For non-React integration, `createEngine({ ports, options?, store? })` provides
+`prime`, `placeOrder`, `getSnapshot` and `subscribe`; its required `confirmer`
+and optional ports are described by the published `CheckoutPorts` type.
+
+## Hooks and API
+
+Import the shared React Query hooks through the **`hooks` namespace**, not as
+individual top-level imports. `CheckoutProvider` includes a query provider for
+its descendants; outside it, wrap your components with your own
+`QueryClientProvider`. Query hooks expose React Query states such as `data`,
+`isLoading`, `error` and `refetch`; mutation hooks expose `mutate` /
+`mutateAsync`, pending state and error. Query and mutation options follow the
+published `QueryOpts` and `MutationOpts` types. Event/order hooks can be gated
+until their ID is available.
 
-Both need a dev client. Build one with:
+```tsx
+import React from 'react'
+import { Text } from 'react-native'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { hooks } from 'tf-checkout-react-native'
 
-```bash
-cd example && pnpm run ios
+const queryClient = new QueryClient()
+function CatalogName({ eventId }: { eventId: string }) {
+  const tickets = hooks.useTickets(eventId)
+  if (tickets.isLoading) return <Text>Loading tickets…</Text>
+  if (tickets.error) return <Text>Could not load tickets.</Text>
+  return <Text>{tickets.data?.length ?? 0} ticket types</Text>
+}
+export function Catalog({ eventId }: { eventId: string }) {
+  return <QueryClientProvider client={queryClient}><CatalogName eventId={eventId} /></QueryClientProvider>
+}
 ```
 
-Set credentials in `example/.env` (`EXPO_PUBLIC_`-prefixed); see
-`example/.env.example`.
+The API reference lists the available hooks by domain and their parameters.
+
+The top-level native `useCheckout()` adds native ports. `hooks.useCheckout` is
+the shared lower-level binding and expects an `EngineConfig` with ports; do not
+substitute it into the native quick start. The root also exports `ttf` (a
+configured domain-grouped API facade), `api` (raw API namespace), types,
+`createEngine`, store/logic utilities and translation functions. For example,
+`ttf.events.tickets(eventId)`, `ttf.geo.countries()`, `ttf.orders.get(orderId)`
+and `ttf.order.review(orderHash)` are promise-returning calls. Private account
+reads require an appropriately authorized account session; the checkout buyer
+scope does not grant it. Low-level APIs do not replace checkout preflight or
+payment reconciliation.
+
+The [API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/docs/API.md)
+includes the full component and hook catalog.
+
+## Authentication and account components
+
+`AuthModal` accepts required `open` and `onClose`, plus `checkoutEventId`,
+`onCheckoutAuthenticated`, `onAuthenticated`, `allowRegistration`,
+`allowPasswordReset`, `requireRegistrationAddress`, `logoUrl`, `initialEmail`
+and `message`. Supply `checkoutEventId` for checkout-scoped auth. The
+`LoginForm`, `RegisterForm`, `ForgotPasswordForm`, `TwoFactorForm` and
+`EmailCodeForm` present fields and delegate their callbacks/state to the host
+or shared controller. `ResetPasswordForm` takes a required reset `token` and
+optional `onSuccess` / `onBackToLogin`. `PasswordInput` wraps `Input` with a
+visibility toggle. The expanded reference lists required form callbacks.
+
+Additional exports include `TicketChange`, `TicketRefund`, `TicketGift`,
+`Passes`, `Trips`, `AccountRewardsSection`, `AccountInformationSection`,
+`AccountPaymentPlanSection`, account deletion, profile and notification views,
+`Streaming`, `PhoneAuthentication`, `AccountEmailEnrichment`,
+`EventDiscussionView` and post reactions. Their availability depends on the
+deployed backend, authorized account scope and host-owned navigation. See the
+[API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/docs/API.md)
+for component variants and required props.
+
+Standalone account components that use query hooks need a `QueryClientProvider`;
+`CheckoutThemeProvider` can theme them without creating a checkout. The `View`
+variants let a host create and retain a shared flow itself. The host must handle
+account sign-in, deep links, browser handoff and navigation; these components do
+not grant account scope by being rendered.
+
+## Theme, primitives and localization
+
+Pass a partial `CheckoutTheme` to `EmbeddedCheckout`, `CheckoutProvider` or
+`CheckoutThemeProvider`. `colorScheme` is `'light'` (default) or `'dark'`;
+other tokens are `accent`, `accentContrast`, `surface`, `surfaceMuted`,
+`background`, `text`, `muted`, `border`, `error`, `success`, `radiusCard`,
+`radiusControl`, `fontSize`, `fontFamily`. Colors/fonts are strings; radii and
+font size are numbers. `resolveTheme(theme)` returns all resolved tokens and
+`useTheme()` reads the current theme. Check contrast and native accessibility.
 
-The example's `metro.config.js` pins React, react-query, and Stripe to single
-copies. That is a **workspace-only** concern — it exists because the example
-consumes the library through a symlink. Consumers installing from npm need
-nothing of the sort.
-
----
-
-Part of the [TicketFairy checkout monorepo](https://github.com/theticketfairy/tf-shared-libraries/blob/main/README.md).
+```tsx
+<EmbeddedCheckout eventId="YOUR_EVENT_ID" theme={{
+  colorScheme: 'dark', accent: '#7c3aed', accentContrast: '#ffffff', radiusCard: 16,
+}} />
+```
 
-Public checkout sign-in uses event-scoped server-only buyer binding, without a bundled
-client secret. The checkout's auth modal supplies the event automatically; standalone
-`AuthModal` callers pass `checkoutEventId` and can receive the narrow
-`onCheckoutAuthenticated(CheckoutBuyerProfile)` callback. Password/signup/email/phone
-proofs still complete required two-factor verification. These credentials cannot read
-private account preferences or tickets. See the [shared identity contract](https://github.com/theticketfairy/tf-shared-libraries/blob/main/packages/tf-checkout-shared/README.md) for
-scope, retry, logout and configuration ownership. Existing confidential OAuth clients
-are trusted-server integrations; never distribute their secrets in browser/native code.
+The exported theme-aware primitives are `Loader`, `Card`, `SectionHeader`,
+`Divider`, `BodyText`, `MutedText`, `ErrorText`, `Button`, `FrozenFields`,
+`Field`, `Input`, `Checkbox`, `Select`, `QuantitySelect`, `Timer`, `TimerBanner`,
+`PaymentMethods` and `RichText`. `useStyles` and `useFrozen` are also exported.
+`PaymentMethods` is a controlled presentation component, not a Pay action.
+`RichText` accepts `html`, `textStyle`, `tagsStyles`, `onLinkPress` and
+`selectable`; it uses the render-html peer. Test external links with your host's
+navigation policy. `FrozenFields` disables its supported SDK controls when the
+order is fixed; custom controls need the same guard. The expanded API reference
+has the individual control props.
+
+Selected sections accept `locale`, `messages` and `translate`; these are per
+component, not a promise that every `EmbeddedCheckout` string can be globally
+replaced. Shared localization exports include `createTranslator`,
+`resolveLocale`, `registerCatalogue` and `DEFAULT_LOCALE`. Organizer-authored
+content is data, and should not be assumed to have a translation.
+
+## Migration from 1.x
+
+This is a major integration change. Pin 1.x while planning migration and test
+against the exact new version, backend and devices. The historical
+[1.0.47 README](https://unpkg.com/tf-checkout-react-native@1.0.47/README.md)
+and [1.0.47 declarations](https://unpkg.com/tf-checkout-react-native@1.0.47/lib/typescript/src/index.d.ts)
+describe the old package; examples there are not 2.x instructions.
+
+| 1.x integration | 2.x beta.24 approach |
+| --- | --- |
+| `setConfig({ EVENT_ID, ENV, ... })` and event-bound global UI | Restore a secure adapter and call `configureCheckout({ env, clientId, clientSecret: '', storage })`; pass `eventId` to the checkout or section. |
+| `Tickets` callbacks such as `onAddToCartSuccess` / `onPressMyOrders` | `Tickets` uses `onContinue` / `onSelectSeats`; the host owns orders navigation. Rework the host flow, not just prop names. |
+| 1.x `Checkout`, `CheckoutV2`, `BillingInfo` and older core components | Use `EmbeddedCheckout` or compose the 2.x sections and `CheckoutProvider`. The 1.x `CheckoutV2` name does not mean this 2.x API. |
+| 1.x `useCheckout()` mutation | Native `useCheckout()` is a stateful engine binding with `setTickets`, setters and `placeOrder`; query hooks are under `hooks`. |
+| Implicit old native storage and session behavior | Supply and restore an OS-protected synchronous adapter. Migrate credentials securely or ask the buyer to sign in again. Checkout-only and account scopes differ. |
+| Per-component style/text props from the old UI | Use theme tokens, available render callbacks and section props; rebuild custom presentation where required. |
+| Existing Stripe setup | Verify current peer/native builds, receiving account, provider URLs, return scheme, wallets and PaymentSheet separately. |
+
+Rebuild the native binary after replacing native dependencies and pods. The 1.x
+My Orders/order-detail screens, PDF handling and resale screen are not drop-in
+2.x equivalents: build the needed host UI, navigation and PDF handling around
+the available order/resale hooks and APIs. Revalidate refund, resale, account
+and password-protected event flows against the deployed service.
+
+## Testing and troubleshooting
+
+1. Pin the SDK and peer versions in the lockfile; verify one React, React Query
+   and native-module instance. Make a clean development build and install pods.
+2. Use an authorized test event and receiving account. Check free and paid
+   orders, stock and pricing, required fields/waivers, add-ons, holders, promo
+   and referral classification, time slots and seat holds. Verify actual orders
+   against the backend and provider, including fee/currency/account context.
+3. Test supported iOS/Android devices: backgrounding, cold/warm returns,
+   interruption, network loss, duplicate taps, expiry, cancellation, guest
+   sign-in and account changes. Test each enabled method, wallet and account.
+4. Configure production merchant credentials, entitlements, public client ID,
+   HTTPS endpoint and callback scheme. Remove test-card hints; verify storage,
+   privacy and backend contracts. Never log real card details.
+
+| Symptom | Check |
+| --- | --- |
+| `TS2304: Cannot find name 'Crypto'` in SDK declarations | A host without DOM and without a compatible ambient `Crypto` type may report this. Prefer compatible host type definitions. `skipLibCheck` skips declaration-file checks, and unresolved `Crypto` can degrade affected types to `any`, allowing invalid `newBundleIdempotencyKey` arguments. Neither option installs runtime crypto. |
+| Configuration/storage error | Hydrate first, then pass an object with synchronous `getItem`, `setItem`, `removeItem`; check native storage failures. |
+| `No QueryClient set` or provider context error | Wrap standalone query hooks in `QueryClientProvider`, and checkout sections in `CheckoutProvider`; check duplicate React Query copies. |
+| Blank chart or missing seat CTA | Confirm event seating support, pass `onSelectSeats`, rebuild WebView, and verify provider/chart/hold contracts. |
+| Missing Apple Pay / Google Pay / Link | Check backend eligibility, real receiving account, device support and host wallet configuration; a simulator or local configuration alone may not qualify. |
+| PaymentSheet unavailable or card field requested | Check static scheme/return URL, original intent and supported method/currency combination. The embedded component does not expose sheet configuration. |
+| Redirect does not return | Register and route the exact app scheme, including cold starts; verify the provider account and allowed return URL. |
+| Email/holder/privacy validation does not match UI | Align `BillingInfo` and `Payment` policies; load current event gates and custom fields. |
+| Outcome unclear or reset returns false | Keep the original order and reconcile backend/provider status. A page close or timeout is not proof of no charge. |
+| Code/referral or conditional question differs from hosted checkout | Classify incoming links server-side or from an authoritative source; native URL reading is a no-op and conditional visibility is incomplete in this beta. |