npm - @flopay/react - Versions diffs - 1.9.15 → 1.9.17 - Mend

@flopay/react 1.9.15 → 1.9.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +466 -1104
package/package.json +3 -3

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @flopay/react
-React bindings for the FloPay SDK. Provides a context provider, drop-in checkout form components, individual element components, and hooks.
+React bindings for the FloPay SDK: a drop-in `FloPayCheckout`, a no-charge `FloPayCardSetup`, a one-click `FloPayAutomaticPaymentButton`, composable checkout components, and hooks. Cards are collected by the billing API's hosted PCI card form; wallets, alternative payment methods, and PayPal render beside it from the session's gateways.
 ## Installation
@@ -8,14 +8,11 @@ React bindings for the FloPay SDK. Provides a context provider, drop-in checkout
 pnpm add @flopay/react @flopay/js @flopay/shared react react-dom
 ```
-Peer dependencies: `react >= 18.0.0`, `react-dom >= 18.0.0`.
+Peer dependencies: `react >= 18.0.0` and `react-dom >= 18.0.0`. Install the same version of every `@flopay/*` package.
-## Environment Setup
-Configure which billing API the SDK uses. Choose one:
+Configure which billing API the SDK uses, once. Either set an environment variable:
 ```bash
-# Option A: Environment variable (recommended)
 # .env.production
 NEXT_PUBLIC_FLOPAY_ENV=production
@@ -23,1253 +20,618 @@ NEXT_PUBLIC_FLOPAY_ENV=production
 NEXT_PUBLIC_FLOPAY_ENV=staging
 ```
+or call `configureFlopay()` at startup:
 ```ts
-// Option B: Call at app startup
 import { configureFlopay } from '@flopay/shared';
 configureFlopay({ environment: 'production' });
 ```
-If neither is set, the SDK defaults to staging.
+If neither is set, the SDK uses the staging billing API.
-## Quick Start
+**Payment-method logos and CSP.** Brand logos load from the versioned, FloPay-owned URL `https://cdn.flopay.com/sdk-logos/v1/`. Plain absolute HTTPS URLs work in Vite with no SDK middleware or `optimizeDeps` override, and behave the same in webpack 5, Rollup, Next, and esbuild. Logos stay out of the package and your JavaScript bundle, and card-only and hosted-card checkouts request none. With a strict Content Security Policy, allow the host in your image directive, for example `img-src 'self' https://cdn.flopay.com;`. A failed or CSP-blocked logo request falls back to the method's inline monogram, so the tile stays branded without another request.
-### Recommended: FloPayCheckout
+## Usage
-The simplest integration — one component, one prop:
+### FloPayCheckout
-```tsx
-import { FloPayCheckout } from '@flopay/react';
+`FloPayCheckout` is the recommended integration. Give it a session and it fetches the session, initializes the right payment providers, and renders the hosted card form plus the session's supported wallets, alternative payment methods, and PayPal. Customer data (email, user id, name) comes from the session.
-function CheckoutPage() {
-  return (
-    <FloPayCheckout
-      sessionId="sess_abc123"
-      onComplete={(result) => {
-        window.location.href = '/success';
-      }}
-      onError={(err) => console.error(err)}
-    />
-  );
-}
+```tsx
+<FloPayCheckout
+  sessionId="sess_abc123"
+  nonce={sessionNonce}
+  onComplete={(result) => router.push('/success')}
+  onError={(error) => console.error(error)}
+/>
 ```
-`FloPayCheckout` automatically fetches the session, initializes the correct payment providers, and renders a `SplitCardForm` with the hosted vault card widget plus the session's supported wallets, APMs, and PayPal. Customer data (email, userId, name) is injected from the session.
-#### Buyer identity collection
+Pass `nonce`, the session-bound checkout token returned when the session was created, whenever you pass an existing `sessionId`.
-For inline checkout creation, `createSession.account.userId` remains required,
-but `email`, `firstName`, and `lastName` may be omitted. `FloPayCheckout`
-creates a mountable session shell first, immediately attaches the known catalog,
-and collects buyer identity at the method-appropriate point:
-- Hosted card checkout renders a required email field first, above name, AVS,
-  and the hosted card widget. Submit stays gated until the email passes the
-  shared `isValidEmail()` validator and a name is present.
-- Apple Pay, Google Pay, other Stripe wallets, and PayPal use provider-returned
-  email/name automatically when available. Their provider UI starts without a
-  Flo identity preflight.
-- A wallet, PayPal, or APM that does not return the missing fields opens a
-  single required fallback pane after that provider miss (or before submission
-  for a method that cannot return identity).
-The SDK never attaches a blank email. The merchant-supplied `userId` is not
-replaced by provider data. A legitimate merchant- or session-supplied buyer
-name remains authoritative over a different wallet name. The exact generic
-placeholder `Card Holder Name` is instead treated as missing after case and
-whitespace normalization, so an authorised wallet name can replace it. Name
-selection is atomic: first and last name always come from one source, and are
-omitted when neither source is usable. Email precedence is unchanged.
-#### Wallet confirmation recovery
-Google Pay and Apple Pay authentication may legitimately outlive the SDK's
-provider observation threshold. The SDK does not cancel that provider promise.
-Instead, it retrieves the original PaymentIntent or SetupIntent with the same
-client secret and routes the provider promise and status read through one
-settlement gate:
-- an authoritative success continues to `/process` exactly once;
-- `canceled` or `requires_payment_method` is treated as authoritative,
-  non-chargeable terminal evidence and exposes wallet retry;
-- `requires_action`, an unavailable/mismatched status, or a failed/bounded-out
-  status read keeps payment submission locked and exposes only **Check payment
-  status**.
-Rejected confirmations, returned technical errors, and malformed fulfilled
-results use this same recovery contract. A lost intent-create response also
-reuses the authorization-attempt UUID on deliberate retry, so provider
-idempotency cannot mint a second intent. A bounded pending-confirmation handoff
-keeps teardown/remount from exposing another wallet surface while the first
-intent may still complete. Existing component props and merchant callbacks are
-unchanged.
+#### Checkout modes
-#### Merchant instrument feed
+`checkoutMode` matches the billing API's `checkoutMode` and overrides the session's value:
-Use `onInstrument` on `FloPayCheckout` or `FloPayProvider` to forward a stable,
-privacy-safe checkout funnel to your own analytics. The callback receives the
-exported `FloInstrumentEvent` discriminated union; `schemaVersion` is always `1`,
-and `gateway` is included as `stripe` or `paypal` only when the event is
-attributable to that payment provider. Hosted-vault events may omit `gateway`,
-and `card_expanded` always does when the session can route cards to a
-[server-side card gateway](#server-side-card-gateways-worldpay).
+- **`full`** (default): the hosted card form plus supported non-card methods.
+- **`confirm`**: hides the payment form and shows a confirm button that pays with the buyer's saved payment method. If the saved card needs re-authentication, the 3DS challenge runs in place and the same attempt completes. `confirmLabel` labels that button.
+- **`auto`**: pays with the saved payment method as soon as the session loads, falling back to `full` if that cannot complete.
-```tsx
-import type { FloInstrumentEvent } from '@flopay/react';
-function forwardCheckoutInstrument(event: FloInstrumentEvent) {
-  window.analytics?.track(event.name, event);
-}
-<FloPayCheckout sessionId={sessionId} onInstrument={forwardCheckoutInstrument} />;
-```
+#### Buyer identity collection
-Lifecycle names are `checkout_mount`, `sdk_loaded`, `form_rendered`,
-`card_expanded`, `tokenize`, `process_attempt`, and `3ds_challenge`.
-`checkout_mount`, `sdk_loaded`, `form_rendered`, and `card_expanded` arrive at
-most once per logical checkout. `tokenize`, `process_attempt`, and
-`3ds_challenge` may repeat for each attempt.
-`checkout_error` adds one of four phases: `session_create`, `sdk_load`,
-`process`, or `wallets`.
+For inline session creation, `createSession.account.userId` is required but `email`, `firstName`, and `lastName` may be omitted. The checkout then collects identity at the right point for each method:
-The callback is an allowlisted projection with no card data, tokens, provider
-object IDs, secrets, or raw PII. A throwing `onInstrument` consumer never
-breaks checkout. This merchant-owned feed is independent of the Flo-owned
-backend telemetry setting, so `telemetry={false}` does not disable it.
+- The hosted card checkout shows a required email field above name, AVS, and the card form. Submit stays gated until the email passes `isValidEmail()` and a name is present.
+- Apple Pay, Google Pay, other Stripe wallets, and PayPal use the email and name the provider returns. Their provider UI opens without a FloPay identity step first.
+- A method that does not return the missing fields opens one required fallback pane after the provider returns (or before submission, for methods that cannot return identity).
-#### Checkout Modes
+The SDK never attaches a blank email and never replaces your `userId` with provider data. A buyer name you or the session supplied stays authoritative over a different wallet name, except the placeholder `Card Holder Name`, which an authorised wallet name can replace. First and last name always come from one source.
-`FloPayCheckout` supports three checkout modes matching the billing API's `checkoutMode` field:
+#### Inline session creation
-- **`full`** (default) — Shows the hosted card widget plus supported non-card methods.
-- **`confirm`** — Hides the payment form and shows a "Confirm Purchase" button. Uses a saved payment method on the backend. When the saved card needs re-authentication, the 3DS challenge runs in place and the same payment attempt completes — the button is not replaced by the card form.
-- **`auto`** — Auto-submits with a saved payment method after the session loads. Falls back to `full` mode on failure.
+Skip your own session-creation route and create the session inside the component with `createSession`:
 ```tsx
-// Confirm mode — one-click purchase with saved card
-<FloPayCheckout
-  sessionId="sess_abc123"
-  checkoutMode="confirm"
-  confirmLabel="Complete Purchase"
-  onComplete={(result) => router.push('/success')}
-/>
-// Auto mode — instant checkout, falls back to full form
 <FloPayCheckout
-  sessionId="sess_abc123"
-  checkoutMode="auto"
-  onComplete={(result) => router.push('/success')}
-  onSessionCompleted={(successUrl) => router.push(successUrl)}
+  createSession={{
+    clientId: 'your-client-id',
+    currency: 'EUR',
+    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
+    account: { userId: 'user_1' }, // email and name are collected in checkout
+    successUrl: '/success',
+    cancelUrl: '/cancel',
+    checkoutMetadata: { merchantOrderId: 'order-123' },
+  }}
+  onComplete={() => router.push('/success')}
 />
 ```
-The mode can also be set on the session itself via the billing API's `checkoutMode` field. The `checkoutMode` prop overrides the session value.
+- **Currency is required.** Pass `currency` on `createSession`, or on the first item, subscription, or product. Without one the SDK throws a `CurrencyRequired` validation error before sending anything.
+- **Detached creation (default).** The checkout creates a lightweight session *shell* first, then attaches the catalog in a background claim. The hosted card form mounts from the shell without waiting for the claim or Stripe.js; wallets, alternative payment methods, and PayPal load in parallel and appear when the claim lands. The card form's submit button stays gated until the claim settles, because the billing API refuses to charge an unclaimed session; a buyer who clicks during that window is asked to press pay again. Catalog and coupon errors surface as a checkout load error. `createSession.timeoutMs` applies separately to the shell and the claim (12 seconds each by default). Detached creation requires billing API v1.7.12 or newer and `checkoutMode: 'full'`, and is skipped when `tokenizedData` is supplied; pass `deferDataAttachment: false` to force a single request.
+- **Late buyer identity.** Any still-anonymous session the checkout renders (including an existing session passed as `sessionId` and `nonce` with `buyerIdentified: false`) attaches the buyer email the checkout collects, or a wallet or PayPal approval supplies, through the session claim before payment.
+- **Checkout metadata.** `checkoutMetadata` is sent unchanged on the initial request and never repeated in a claim. Omitting it keeps the request shape; an explicit `null` and `{}` stay distinct. Returned metadata is on the normalized session and its `data.session`. The billing API alone enforces size limits.
+- **Idempotency.** The create request sends a stable `Idempotency-Key` whenever a secure random source is available. `FloPayCheckout` resolves the key once per logical checkout, stores it with the inline-session cache in `sessionStorage`, and reuses it across retries, effect reruns, and remounts, so StrictMode double-mounts or navigation flicker cannot create two sessions or two charges. A logical checkout is identified by merchant, buyer, cart and pricing, coupons, and checkout metadata (keys canonicalized, raw metadata not stored); checkout-mode, token, and analytics prop changes do not rotate it. Pass `createSession.idempotencyKey` to control the key yourself; it must be non-empty, at most 255 characters, and never reused for a new purchase.
+- **Just-in-time updates.** With `layout="buttons"`, an `InlineSessionPatch` returned from `onBeforeButtonClick` is merged into the draft before the selected flow continues. A returned `checkoutMetadata` replaces the previous map; return `null` to clear it.
+#### Authorisation-only checkout
-`confirmLabel` only labels the saved-payment button in confirm mode. To change
-the full checkout's hosted card button, use
-[`submitLabel`](#hosted-card-submit-label).
+Set `captureMethod: 'manual'` in `createSession` for an eligible item-only card checkout. The buyer still reaches the success experience, but the overlay reads `PAYMENT AUTHORISED` and `onComplete` receives `status: 'authorized'` with `paymentId`, `sessionId`, and `authorizationExpiresAt`. `authorized` means funds are held, not paid. Capture is a merchant-authenticated REST operation that browser code can never perform; see the [payments and authorisations reference](https://flopay.com/docs/technical-reference/rest/payments). Manual capture is rejected for subscription carts.
 #### Hosted card submit label
-In full checkout, the button that pays by card lives inside the hosted vault
-widget. Set `submitLabel` on `FloPayCheckout` (or `SplitCardForm`) to replace
-its wording, for example with the amount the buyer is about to pay:
+In full checkout, the button that pays by card lives inside the hosted card form. Set `submitLabel` on `FloPayCheckout` or `SplitCardForm` to replace its wording, for example with the amount the buyer is about to pay.
-```tsx
-<FloPayCheckout
-  sessionId="sess_abc123"
-  submitLabel={`Pay ${orderSummary.formattedTotal}`} // e.g. "Pay $10"
-  onComplete={handleSuccess}
-/>
-```
+- **Your wording.** Pass final, already-localized plain text from your own order summary. The SDK does not calculate, format, or translate amounts.
+- **Live updates.** Changing the prop updates the button in place without remounting the card form, so entered card details, focus, and caret are kept. The SDK re-sends the label whenever the hosted form becomes ready again.
+- **Defaults and reset.** Omit the prop (or pass `null`) to keep the hosted default, `CONFIRM PAYMENT`. Clearing it after a label was shown restores that default, and so does blank text: the hosted form trims the label, allows up to 64 characters, rejects control and hidden formatting characters, and shows the default for anything it rejects. Card setup (`FloPayCardSetup`) keeps its own `ADD CARD` wording.
+- **Ownership.** `submitLabel` changes only the hosted card button. `confirmLabel` labels the saved-payment button in `checkoutMode="confirm"`, `cardButtonContent` renders the buttons-layout card tile, and wallet, PayPal, processing, and retry wording is unchanged.
+- **Custom layouts.** `FloPayCheckout` injects `submitLabel`, like `sessionId` and `nonce`, into its direct custom-layout children; a child's own `submitLabel` wins.
+- **Compatibility.** Custom labels need billing API v1.9.35 or newer, whose card form carries the `messageToken` and `expectedOrigin` that authenticate the label; the SDK sends it only to that exact origin. Older billing APIs keep the default wording.
-- **Merchant-owned wording.** Pass the final, already-localized plain text
-  from your own order summary. The SDK does not calculate, format, or translate
-  the amount; it sends your string unchanged.
-- **Live updates.** Changing the prop updates the hosted button in place,
-  without remounting the card form, so the buyer's entered card details, focus,
-  and caret are kept. The SDK re-sends the latest label whenever the hosted
-  form becomes ready again.
-- **Defaults and reset.** Omit the prop (or pass `null`) to keep the hosted
-  default, `CONFIRM PAYMENT`. Clearing it after a label was shown restores that
-  default, and so does blank text: the hosted form trims the label, allows up to 64
-  characters, rejects control and hidden formatting characters, and shows the
-  default for anything it rejects. Card setup (`FloPayCardSetup`) keeps its own
-  `ADD CARD` wording.
-- **Prop ownership.** `submitLabel` only changes the hosted card button.
-  `confirmLabel` labels the saved-payment button in `checkoutMode="confirm"`,
-  `cardButtonContent` renders the buttons-layout card tile, and wallet, PayPal,
-  processing, and retry wording is unchanged.
-- **Custom layouts.** Like `sessionId` and `nonce`, `FloPayCheckout` injects
-  `submitLabel` into its direct custom-layout children; a child's own
-  `submitLabel` wins.
-- **Compatibility.** Custom labels need billing API v1.9.35+, whose vault block
-  carries the `messageToken` and `expectedOrigin` that authenticate the label.
-  The SDK sends the label only to that exact origin, bound to the checkout
-  session. Against an older backend the hosted form keeps its default.
+#### Wallets and alternative payment methods
-#### Server-side card gateways (Worldpay)
+The payment-method list is gateway-driven: the billing API sends `gateways.stripe.enabledPaymentMethods` for each session, derived from the payment methods enabled on the merchant's Stripe account. Apple Pay, Google Pay, PayPal, Link, Amazon Pay, and Klarna render as express buttons; every other enabled method (for example Cash App Pay, Affirm, iDEAL, Bancontact, SEPA Debit) renders in an accordion. Enabling a new method in Stripe needs no SDK or application change. Wallets render only on supported devices.
-The billing API can route a checkout's cards to an approved Worldpay Corporate
-Gateway (TeamFloPay/backend#1563). It processes those payments entirely
-server-side behind the same hosted vault card form, so your checkout code does
-not change and never needs to know which gateway took the card:
-- **Opt-in on create.** An inline Full-mode checkout (`createSession`, or a
-  session created with `PaymentAPI.createAndFetchSession` /
-  `createDetachedSession`) declares the `worldpay-corporate-gateway-v1`
-  capability. Auto, Confirm, and pre-tokenized sessions do not, and neither do
-  older SDKs, so their routing is unchanged. See the `@flopay/js` README for the
-  wire contract.
-- **Same card surface.** `FloPayCheckout` and `SplitCardForm` mount the hosted
-  form with no Stripe runtime and no Worldpay browser SDK or credentials. When
-  a session read omitted the embedded vault block, an open session that
-  advertises `gateways.worldpayCorporateGateway` recovers the form from
-  `POST /v1/checkouts/sessions/{id}/vault/capture` instead of failing to mount.
-  A completed or authorized session is never offered the card form again.
-- **Same callbacks.** A success reaches `onComplete` as
-  `{ status: 'succeeded', checkoutMethod: 'card' }`, and a manual-capture hold
-  as `status: 'authorized'` with `paymentId`, `sessionId`, and
-  `authorizationExpiresAt`. `paymentIntentId` is omitted for these sessions
-  because the processor's order reference is not a Stripe object. A refusal
-  reaches `onDecline` with the stable `authorization_declined` code. A payment
-  the billing API is still reconciling when the hosted form stops waiting
-  reaches `onError`, never `onComplete`; a later session read reports the
-  settled status through `onComplete` or `onSessionCompleted`.
-- **Unattributed card funnel.** `card_expanded` omits `gateway` for these
-  sessions, because the billing API, not the browser, chooses the card's
-  gateway.
-### Secure saved-card setup
-Use `FloPayCardSetup` to let a customer add or verify a card without creating a
-purchase or charge. Your trusted server must first call the
-merchant-authenticated card-setup endpoint and pass only its opaque `sessionId`
-and bound `nonce` to the browser. Never send Client Basic credentials, OAuth
-tokens, or a customer identifier to this component.
+`card` in that list is a capability marker, not a Stripe-rendered method: it keeps **Credit / Debit Card** available and lets the SDK fetch the hosted card form on demand when the session has no embedded `vault` block.
-```tsx
-import { FloPayCardSetup } from '@flopay/react';
+- `showStripe` (default `true`) toggles Stripe wallets and alternative methods; `showPayPal` (default `true`) toggles PayPal. Turning both off with no PayPal gateway is reported through `onError` as a `validation_error` instead of rendering an empty form.
+- In `layout="buttons"`, **Credit / Debit Card** opens the inline card form. Cancelling a wallet or PayPal silently returns to the chooser. A technical failure after the click (including popup blocking, or a provider closing without a result) restores the chooser, focuses a retry control for that method, shows safe method-specific copy such as `We couldn't open Google Pay. Try again or choose another payment method.`, and calls `onError` with a `FloPayError`. A method that is unavailable before the click just disappears.
+- Wallet confirmation has one 25-second SDK budget inside the provider's 30-second callback deadline. If a wallet omits required buyer identity, the authorization is failed promptly, the SDK collects the missing email, and the buyer reopens the wallet to continue.
+- **Confirmation recovery.** Google Pay and Apple Pay authentication can outlive the SDK's observation window. The SDK never cancels that provider promise: it reads the original intent's status and settles once. A successful intent continues to payment exactly once; a cancelled or failed intent offers a wallet retry; an intent still needing action, or a status that cannot be read, keeps payment locked and offers only **Check payment status**. A retry after a lost intent-create response reuses the same authorization attempt id, so no second intent can be created.
+- `showApplePay` and `showGooglePay` are deprecated: wallet availability comes from the session's `enabledPaymentMethods`, and supplying them alongside it emits a one-time `console.warn`. Direct PayPal is resolved from `gateways.paypal`; the `SplitCardForm` `directPaypal` prop remains only for wiring PayPal manually.
-function AddCard({ sessionId, nonce }: { sessionId: string; nonce: string }) {
-  return (
-    <FloPayCardSetup
-      sessionId={sessionId}
-      nonce={nonce}
-      onComplete={({ paymentMethod }) => {
-        // Display-only when supplied. Re-list from the server if absent during
-        // a mixed-version backend rollout.
-        console.log(paymentMethod?.brand, paymentMethod?.lastFour);
-      }}
-      onDecline={({ message }) => showCardError(message)}
-      onValidation={(message) => showCardValidation(message)}
-      onError={(error) => {
-        if (error.retryable) showRetry();
-      }}
-      onCancel={() => closeAddCard()}
-    />
-  );
-}
-```
+#### PayPal
-The component reads and validates the setup session before injecting FloPay's
-hosted PCI card widget. It refuses purchase sessions, zero-amount non-setup
-sessions, non-zero setup sessions, and setup sessions containing products. Bank
-authentication is shown through the existing hosted challenge and does not
-count as success while pending. Completion fires only after verification says
-the card is usable; decline, validation, retryable technical failure, and
-unmount cancellation remain separate outcomes.
-Submission feedback matches checkout: the same processing overlay covers the
-form from the buyer's submit ("SAVING CARD...") and flips to "CARD SAVED"
-(held briefly before `onComplete`) or "CARD NOT SAVED" with the decline
-message (cleared automatically so the buyer can retry in place).
-#### Card-setup theming
-`theme` accepts the same `ThemeId` as `FloPayCheckout` (default
-`'modern-light'`) or raw `VaultCardThemeColors`. A named preset styles the
-whole card-setup experience coherently:
-- **Surface** — the container around the hosted form wears the preset's
-  complete credit-card pane treatment (`cardFormContainer`: background or
-  gradient, border, radius, shadow, padding), so `modern-dark` never places
-  dark hosted fields on a light, unthemed box.
-- **Hosted form** — the widget receives the preset's field colors and
-  typography plus the complete hosted submit snapshot
-  (`VaultCardThemeColors.submitButton`, billing API v1.9.6+): label color,
-  solid or gradient enabled/hover/disabled fills, typography, spacing, shadow,
-  radius, disabled opacity, and blur. The legacy flat keys are always sent
-  alongside it, so an older hosted asset keeps its solid approximation during a
-  rolling deployment, and an older SDK against a newer asset keeps its
-  historical flat-only behavior. `modern-dark`'s dark label stays at or above
-  4.5:1 in the enabled, hover, and disabled states, disabled compositing
-  included.
-- **Processing / success / error** — the overlay reuses the pane surface and
-  typography; processing wears the preset primary on its spinner, while success
-  and error keep semantic green/red accents chosen per color scheme so they
-  stay legible on every pane.
-`'classic'` keeps the historical card-setup appearance exactly: no derived
-surface, the neutral overlay, and no theme directive sent to a freshly mounted
-hosted form. Raw `VaultCardThemeColors` objects — including partial ones — are
-forwarded to the hosted form unchanged and add no surface or overlay treatment.
-Changing `theme` at runtime updates the SDK-owned surface and overlay in place
-and re-skins the mounted hosted form without remounting it, so entered card
-details, focus, and caret are preserved. Switching back to `'classic'` sends
-the hosted form's explicit reset (`theme: null`) so nothing from the previous
-preset lingers.
-##### `containerStyle` precedence
-`containerStyle` is merged over the preset surface with deterministic rules:
-1. Each `containerStyle` property wins over the preset value for the same
-   property.
-2. Declarations are applied preset-first, then `containerStyle` in your own key
-   order, so a longhand refines a preset shorthand of the same family the way
-   CSS cascades: `borderColor: 'red'` recolors the preset border and keeps its
-   width and style; `paddingTop: 0` adjusts one side.
-3. Background is the exception: any `background*` member in `containerStyle`
-   replaces the preset's background treatment entirely, so a color never shows
-   a glass preset's gradient through it.
-4. With `'classic'` or a raw theme there is no preset surface: `containerStyle`
-   applies alone, exactly as before.
+The SDK renders PayPal one of two ways, chosen per session from its gateways:
-```tsx
-<FloPayCardSetup
-  sessionId={sessionId}
-  nonce={nonce}
-  theme="glass-dark"
-  containerStyle={{ borderColor: '#60A5FA', padding: 16 }} // refines the glass-dark pane
-/>
-```
+- **Direct PayPal** (preferred, and works inside Facebook, Instagram, and other in-app browsers): when the session has `gateways.paypal`, PayPal renders through the official PayPal JS SDK with the client id and `environment` (`sandbox` or `live`) from the billing API. If only PayPal is advertised, `FloPayCheckout` skips Stripe entirely.
+- **Stripe-rendered PayPal**: when only `gateways.stripe` is configured, PayPal renders through Stripe's express checkout. It cannot render in Facebook or Instagram in-app browsers.
-Saved-card listing, setup-session creation, and deletion remain authenticated
-merchant REST calls. Replacement is composition: complete setup for the new
-card, then ask your server to delete the old card. `FloPayCardSetup` deliberately
-has no customer-id, merchant-credential, list, delete, purchase, or Stripe
-Elements prop.
+Direct PayPal never hides its button behind a FloPay identity step: after approval the SDK reads the payer's email and name, and asks once for anything missing. `gateways.paypal.providerObjectType` selects the operation: `order` (a one-time Order, even for a subscription-mode session), `subscription` (a PayPal-managed subscription), or `setup_token` (vault the account; the approval token is exchanged by the billing API). `approvalPresentation` selects the bounded `app_switch` mode only for a one-time Order in an in-app browser, where it enables PayPal's app switch; ordinary browsers, subscriptions, and setup tokens keep the popup flow. It is a mode, never a URL. If an in-app popup is blocked, `onTechnicalFailure` on `DirectPayPalButton` receives `popupBlocked: true` with guidance to open the page in the system browser, and PayPal stays visible for retry.
-Prefer importing it from the dedicated subpath on pages that never run a
-checkout:
+**Initialization recovery.** A Direct PayPal startup failure hides PayPal, waits one second, and remounts once, without creating a session, intent, or charge; other payment methods stay usable throughout. If Stripe-rendered PayPal is also available, it takes over during recovery. If both attempts fail in a mixed checkout, PayPal stays hidden and neither `onError` nor `onDecline` fires. In a PayPal-only checkout the component shows an accessible retrying status, then a **Retry PayPal** button, and calls `onError` once with `paypal_init_timeout`.
-```tsx
-import { FloPayCardSetup } from '@flopay/react/card-setup';
-```
+#### Server-side card gateways (Worldpay)
-The main entry re-exports the component for back-compat, but its module graph
-eagerly loads Stripe.js (a deliberate checkout preload); the `card-setup`
-entry's graph never reaches Stripe, so saved-card pages stay free of Stripe
-network activity by construction.
+The billing API can route a checkout's cards to an approved Worldpay Corporate Gateway, processed entirely server-side behind the same hosted card form. Your checkout code does not change:
-#### Expired Sessions
+- **No opt-in.** The billing API decides from the merchant's configured gateways whether a session can use Worldpay. The SDK sends no capability token or gateway hint, so routing is the same for every SDK version and create style. Auto, Confirm, and pre-tokenized sessions stay on the released routing because the billing API keeps them there, not because the SDK asks.
+- **Same card surface.** No Stripe runtime, Worldpay SDK, or browser credential is involved. An open session that advertises `gateways.worldpayCorporateGateway` but omits the embedded card form recovers it on demand; a completed or authorized session is never shown the card form again.
+- **Same callbacks.** Success reaches `onComplete` as `status: 'succeeded'`, and a manual-capture hold as `status: 'authorized'` with `paymentId`, `sessionId`, and `authorizationExpiresAt`; `paymentIntentId` is omitted because the processor's reference is not a Stripe object. A refusal reaches `onDecline` with `authorization_declined`. A payment still reconciling when the form stops waiting reaches `onError`, never `onComplete`, and a later session read reports the settled status.
+- The merchant instrument feed's `card_expanded` event omits `gateway` for these sessions, because the billing API chooses the card's gateway.
-When `FloPayCheckout` or `FloPayAutomaticPaymentButton` loads a checkout session whose `status` is `expired`, the component calls `onError` with a `FloPayError` so your app can route the customer into a recovery flow.
+#### Themes and layouts
-The error has:
+`FloPayCheckout`, `FloPayAutomaticPaymentButton`, `SplitCardForm`, and `FloPayCardSetup` accept one `theme` prop, a `ThemeId`:
-- `message: 'Checkout session has expired.'`
-- `type: 'api_error'`
-- `code: 'checkout_session_expired'`
+| Theme | Aesthetic |
+|-------|-----------|
+| `classic` | The historic FloPay look (no bundle applied); the default for checkout components |
+| `modern-light` / `modern-dark` | Clean and airy: Inter, soft shadows, FloPay-blue accents |
+| `bold-light` / `bold-dark` | Saturated FloPay blue with a gradient pill submit and heavy borders |
+| `glass-light` / `glass-dark` | Translucent surfaces with backdrop blur over a blue gradient |
-Use this code to create or request a fresh checkout session, then send the customer back through checkout:
+One value styles non-card Stripe Elements, the SDK-rendered wrapper and AVS fields, the hosted card form, and the automatic payment button's fallback checkout. `appearance` (Stripe-side overrides) and `buttonsStyles` (wrapper overrides) still win over the bundle for the fields they touch. The legacy `buttonsTheme` prop is deprecated in favor of `theme`; see the [ButtonsLayoutStyles reference](https://flopay.com/docs/technical-reference/react/flopay-checkout#buttonslayoutstyles-reference) for every override field.
-```tsx
-<FloPayCheckout
-  sessionId={sessionId}
-  onComplete={() => router.push('/success')}
-  onError={(error) => {
-    if (error.code === 'checkout_session_expired') {
-      router.push('/checkout/expired');
-      return;
-    }
+`layout="buttons"` stacks the payment methods as buttons with an expandable card form, and can change at runtime without recreating the session. In that layout, `onButtonClick` reports every method click, `onDecline` reports declines and cancellations, and `onBeforeButtonClick` runs before a method continues: return an `InlineSessionPatch` to update the inline draft, or `false` to stop. Keep it fast for PayPal, Apple Pay, and Google Pay, because it runs during the provider's button handshake.
-    console.error(error);
-  }}
-/>
-```
+#### Merchant instrument feed
-### Automatic Payment Buttons
+`onInstrument` on `FloPayCheckout` or `FloPayProvider` forwards a stable, privacy-safe checkout funnel to your own analytics as `FloInstrumentEvent` values. `schemaVersion` is always `1`, and `gateway` (`stripe` or `paypal`) is included only when an event is attributable to that provider.
-Use `FloPayAutomaticPaymentButton` when you want a single reusable button that:
+- Lifecycle names are `checkout_mount`, `sdk_loaded`, `form_rendered`, `card_expanded`, `tokenize`, `process_attempt`, and `3ds_challenge`. `checkout_mount`, `sdk_loaded`, `form_rendered`, and `card_expanded` arrive at most once per logical checkout; `tokenize`, `process_attempt`, and `3ds_challenge` may repeat for each attempt.
+- `checkout_error` adds one of four phases: `session_create`, `sdk_load`, `process`, or `wallets`.
-- creates an `auto` checkout session inline or reuses an existing `sessionId`
-- lets the backend resolve and charge the customer's most recently vaulted payment method (across providers)
-- shows the shared processing / success / failure modal
-- emits the same success and decline events without rendering a full checkout form
+The callback is an allowlisted projection with no card data, tokens, provider object IDs, secrets, or raw PII. A throwing `onInstrument` consumer never breaks checkout, and `telemetry={false}` does not disable this merchant-owned feed.
-The button accepts either:
+#### Privacy-safe operational telemetry
-- `sessionId`
-- or the same session-creation props you would normally post to the backend: `clientId`, `items`, `subscriptions`, `account`, `successUrl`, `cancelUrl`, `couponCodes`, `tagsData`, `utmMetadata`
+`FloPayCheckout` reports the same closed FloPay-owned lifecycle, error, and performance contract as `@flopay/js`, including render, interactivity, and provider readiness milestones. No endpoint, custom tag, user context, message, stack, or metadata can be configured, and callback exceptions are only logged to your console. Opt out with `telemetry={false}`.
-It accepts the same `theme` prop as `FloPayCheckout` and `SplitCardForm` (see [Theming](#theming) below) — the value is forwarded to the fallback `FloPayCheckout` modal so the entire flow stays visually consistent. When the saved-payment charge can't complete silently, the button opens the standard `FloPayCheckout` inline with the same theme already applied.
+If Stripe.js cannot initialize after the session resolves, a session that can use the hosted card form still shows it, and Direct PayPal still renders when advertised; only Stripe wallets and alternative methods are omitted. One **Retry payment methods** action retries provider initialization alone, never session creation, claims, intents, or payments. When neither the hosted card form nor Direct PayPal can render, `onError` and the `error` render prop receive `CheckoutInitializationFailed` with fixed buyer-safe copy.
-> **Removed in this version**: the legacy `paymentMethodId` and `checkoutMethod` props are now `@deprecated` and silently ignored. The backend's auto-checkout (`createSingle`) looks up the customer's latest vaulted payment method via `getLatestByUserId` and rebinds the session's gateway to match, so the SDK no longer hand-picks a PM or a provider. Existing integrations that still pass these props continue to work — they have no effect.
+Hosts with their own Sentry client can use the re-exported filter as `beforeSend`:
-```tsx
-import { FloPayAutomaticPaymentButton } from '@flopay/react';
+```ts
+import * as Sentry from '@sentry/browser';
+import { dropThirdPartyOnlyError } from '@flopay/react';
-function UpsellButton() {
-  return (
-    <FloPayAutomaticPaymentButton
-      clientId="your-client-id"
-      account={{ userId: 'user_1', email: 'user@example.com' }}
-      items={[
-        {
-          providerItemId: 'upsell_1',
-          providerItemName: 'AI Supercharger Pack',
-          totalAmount: 249,
-          overrideAmount: 80,
-          currency: 'EUR',
-          quantity: 1,
-        },
-      ]}
-      successUrl={`${window.location.origin}/success`}
-      cancelUrl={`${window.location.origin}/success`}
-      theme="bold-dark"
-      onClick={() => {
-        window.dataLayer?.push({ event: 'automatic_payment_button_click' });
-      }}
-      onSuccess={() => {
-        console.log('automatic payment succeeded');
-      }}
-      onError={(error) => {
-        console.error(error.message);
-      }}
-      onDecline={(decline) => {
-        console.log('automatic payment declined', decline);
-      }}
-    >
-      Purchase Item
-    </FloPayAutomaticPaymentButton>
-  );
-}
+Sentry.init({ beforeSend: dropThirdPartyOnlyError });
 ```
-`children` render inside the button, so you can treat them as slot content. If omitted, the default buttons-layout card content is used.
-#### Wallet Buttons & alternative payment methods
-The payment-method list is now **gateway-driven**: the billing API ships
-`gateways.stripe.enabledPaymentMethods` per session, derived from the Stripe
-Payment Method Configurations enabled on the merchant account. The SDK
-partitions that list into two regions inside `SplitCardForm`:
-- `ExpressCheckoutElement` — `apple_pay`, `google_pay`, `paypal`, `link`,
-  `amazon_pay`, `klarna` (everything supported as a native big button).
-- `PaymentElement` (accordion) — every other enabled method, e.g. `cashapp`,
-  `affirm`, `ideal`, `bancontact`, `sepa_debit`.
-`card` is a capability marker, not a Stripe-rendered method. It keeps the
-**Credit / Debit Card** path available and tells SDK 1.4.9+ that the hosted
-vault form can be requested lazily when `session.vault` is absent.
-Enabling Cash App Pay (or any future Stripe method) in the Stripe dashboard is
-the entire integration change — no SDK redeploy or consumer code update is
-required. Wallets only render on supported devices regardless of dashboard
-state (Apple Pay on Safari/macOS/iOS, Google Pay on Chrome).
-> **Payment-logo CDN and CSP:** APM brand logos load from the versioned,
-> FloPay-owned URL `https://cdn.flopay.com/sdk-logos/v1/`. Plain absolute HTTPS
-> URLs work in Vite with no SDK middleware or `optimizeDeps` override, and retain
-> the same behavior in webpack 5, Rollup, Next, and esbuild. Logos stay out of
-> the package and JavaScript bundle; card-only and vault checkouts never request
-> one. Merchants with a strict Content Security Policy must allow the host in
-> the image directive, for example `img-src 'self' https://cdn.flopay.com;`.
-> A failed or CSP-blocked logo request falls back to the method's existing
-> inline monogram, so the tile remains branded without another network request.
-In `layout="buttons"`, the **Credit / Debit Card** button always opens the
-inline card form. External wallets and PayPal keep their own lifecycle:
-buyer cancellation silently returns to the payment-method chooser with all
-eligible options available, while post-click technical failures, popup
-blocking, or a provider surface returning focus without a terminal callback
-restore the chooser, focus a visible retry control for the failed method, show safe method-specific copy such as
-`We couldn't open Google Pay. Try again or choose another payment method.`, and
-call `onError` with a structured `FloPayError`. Passive pre-click load or
-eligibility failures still collapse only the unavailable method and do not show
-a checkout error.
-Wallet confirmation has one 25-second SDK budget inside the provider's
-30-second callback deadline. Flo-owned intent requests are aborted when that
-budget expires, and every unsuccessful authorization settles the provider
-callback once. Payment and setup wallets are confirmed through the active
-`ExpressCheckoutElement` Elements instance. If a wallet omits required buyer
-identity, the current authorization is failed promptly, the SDK collects the
-missing email outside the wallet callback, and the buyer then reopens the
-wallet to continue. The resolved identity is kept unchanged through the late
-buyer claim, confirmation checkpoint, retry/resume, and final `/process`
-request.
-Toggle the whole Stripe region or the PayPal region independently with the
-two gateway-level props:
+It drops only complete exception stacks with no app or `@flopay/*` frame and at least one recognized browser-extension or Stripe controller frame; every other error passes through unchanged.
-```tsx
-<FloPayCheckout
-  sessionId="sess_abc123"
-  showStripe={true}  // default: true — Stripe wallets/APMs only
-  showPayPal={true}  // default: true — DirectPayPal when gateway present,
-                     //                  Stripe-rendered PayPal otherwise
-  onComplete={handleSuccess}
-/>
-```
+### FloPayCardSetup
-Setting both to `false` (with no PayPal gateway configured) is treated as a
-bootstrap-time validation error — `onError` fires with a
-`FloPayError({ type: 'validation_error' })` so the misconfiguration surfaces
-during integration instead of silently rendering an empty form.
+`FloPayCardSetup` lets a customer add or verify a card without a purchase or charge. Your trusted server first calls the merchant-authenticated card-setup endpoint and passes only its opaque `sessionId` and bound `nonce` to the browser; never send API credentials or a customer identifier to this component. See the [payment methods reference](https://flopay.com/docs/technical-reference/rest/payment-methods) for listing, setup, and deletion.
-##### Deprecated props
+- The component reads and validates the setup session before injecting the hosted card form. It refuses purchase sessions, non-zero or product-bearing setup sessions, and zero-amount sessions that are not setup sessions.
+- Bank authentication is shown in the hosted challenge and does not count as success while pending. `onComplete` fires only once verification says the card is usable; decline, validation, retryable technical failure, and unmount cancellation are separate callbacks.
+- Submission feedback matches checkout: a processing overlay reads `SAVING CARD...`, then `CARD SAVED` before `onComplete`, or `CARD NOT SAVED` with the decline message, cleared automatically so the buyer can retry.
+- Replacing a card is composition: complete setup for the new card, then ask your server to delete the old one. The component has no customer-id, credential, list, delete, purchase, or Stripe Elements prop.
+- Import it from `@flopay/react/card-setup` on pages that never run a checkout. The main entry re-exports it, but its module graph eagerly loads Stripe.js; the `card-setup` entry never reaches Stripe.
-`showApplePay`, `showGooglePay`, and `directPaypal` are still accepted but
-emit a one-time `console.warn` when supplied alongside the new
-`enabledPaymentMethods` payload. They are no-ops once the backend ships the
-field — Apple Pay / Google Pay are dashboard-controlled at Stripe, and direct
-PayPal is auto-resolved from `gateways.paypal` on the session response. The
-legacy props will be removed in `2.0`.
+**Theming.** `theme` accepts a `ThemeId` (default `modern-light`) or raw `VaultCardThemeColors`. A named preset styles the container surface, the hosted form (including its complete submit-button snapshot, billing API v1.9.6+), and the processing, success, and error overlay coherently. `classic` keeps the historic appearance, and raw colors are forwarded to the hosted form unchanged with no surface treatment. Changing `theme` re-skins everything in place without remounting the form.
-#### Theming
+**`containerStyle` precedence.** Each `containerStyle` property wins over the preset's value for the same property, applied preset-first so a longhand refines a preset shorthand (for example `borderColor` keeps the preset border's width). Any `background*` member replaces the preset background entirely. With `classic` or raw colors, `containerStyle` applies alone.
-`FloPayCheckout`, `FloPayAutomaticPaymentButton`, `SplitCardForm`, and `FloPayCardSetup` accept a single `theme` prop that maps to a coherent `{appearance, buttonsLayout}` bundle in `@flopay/shared`'s `THEMES` map. (`FloPayCardSetup` has no surrounding Stripe Elements: the preset styles its container surface, the hosted vault widget, and its outcome overlay — see [Card-setup theming](#card-setup-theming) — and unlike the checkout components it defaults to `'modern-light'` rather than `'classic'`.) One value styles non-card Stripe Elements, the React-rendered wrapper and AVS inputs, the hosted vault widget, and — for `FloPayAutomaticPaymentButton` — the fallback modal that opens when a saved-payment charge can't complete silently.
+### FloPayAutomaticPaymentButton
-| `theme` | Aesthetic |
-|---|---|
-| `'classic'` | Historic FloPay look (no bundle applied — `#EDEDFF` wrapper, indigo submit). |
-| `'modern-light'` / `'modern-dark'` | Clean & airy, Inter, soft shadows, FloPay-blue accents. |
-| `'bold-light'` / `'bold-dark'` | Saturated FloPay blue with gradient pill submit and heavy borders. |
-| `'glass-light'` / `'glass-dark'` | Translucent surfaces with backdrop blur over a blue gradient. |
+`FloPayAutomaticPaymentButton` is a single reusable button that creates an `auto` checkout session inline (or reuses a `sessionId`), lets the billing API charge the customer's most recently saved payment method across providers, and shows the shared processing, success, and failure modal. It accepts either `sessionId` and `nonce`, or the session-creation props `clientId`, `items`, `subscriptions`, `products`, `account`, `successUrl`, `cancelUrl`, `couponCodes`, `tagsData`, and `utmMetadata`. `children` render inside the button.
-```tsx
-<FloPayCheckout
-  sessionId="sess_abc123"
-  theme="bold-dark"
-  onComplete={handleSuccess}
-/>
+When the saved payment method cannot complete silently, the button opens a `FloPayCheckout` with the same `theme`. The `paymentMethodId` and `checkoutMethod` props are deprecated and ignored: the billing API selects the payment method and gateway.
-<FloPayAutomaticPaymentButton
-  sessionId="sess_abc123"
-  theme="bold-dark" // applied to the button AND the fallback modal
-  onSuccess={handleSuccess}
-/>
-```
+### Composing your own checkout
-`appearance` (Stripe-side overrides) and `buttonsStyles` (per-field wrapper overrides) still work — both win over the resolved bundle for the fields they touch, so you can layer customizations on top of a theme:
+`FloPayProvider`, `SplitCardForm`, and the hooks let you compose the provider and session yourself. Card checkout still uses the hosted card form: supply the session (with its `vault` block) and nonce, or a session whose `gateways.stripe.enabledPaymentMethods` includes `card` so the form can be fetched on demand. A session with neither never calls the recovery endpoint; its other methods remain usable, and if none remain `onError` receives `UnsupportedBackendVaultCapability`. `FloPayCheckout` and `SplitCardForm` never fall back to Stripe card fields.
-```tsx
-<FloPayCheckout
-  theme="modern-light"
-  buttonsStyles={{ submitButton: { backgroundColor: '#FF0099' } }} // wins
-/>
-```
+- Wallets, alternative methods, and PayPal create intents through the nonce-protected session intent route, and client-observed failures use the session decline route without tokens, provider object ids, card data, or personal data.
+- **Hosted card form.** The widget owns the card fields, its own submit button, tokenization, the charge, 3DS, and the result, so no Stripe.js runs on the card path. `SplitCardForm` renders no card fields or submit button of its own, and Host-collected AVS fields remain outside the PCI widget and gate its submit. After the widget reports it is submitting, the processing overlay stays up until `complete`, `decline`, or `error`. In `layout="buttons"`, the recovery request for the form waits until the buyer selects Card, and concurrent renders share one request.
+- **AVS.** With `enableAVS`, the SDK collects the billing address outside the PCI form and gates the form's submit synchronously on it. The postcode is validated against the selected country with the same rules as the billing API: a supported country blocks an empty or malformed postcode with an inline message, and a country without postcodes makes the field optional. Email and street, city, and state fields gate submit the same way. On submit, the address is saved in parallel with the charge: a rejected address (`4xx`) shows inline and reaches `onError` for the next attempt, while a transient failure or a 10-second timeout falls back to the session's saved address and still completes.
+- `useCheckout()` exposes `claimPending`, which stays true while a detached session shell is not yet safe to charge.
-#### Buttons Layout
+## Examples
-Switch from the default form layout to stacked payment buttons with an expandable card form:
+A complete checkout page for an existing session:
 ```tsx
-<FloPayCheckout
-  sessionId="sess_abc123"
-  layout="buttons"
-  theme="bold-dark"
-  onButtonClick={(method) => console.log('clicked:', method)}
-  onComplete={handleSuccess}
-/>
-```
-`layout` can be changed at runtime. Switching a mounted `FloPayCheckout` from
-the default layout to `"buttons"` keeps the resolved checkout session and its
-gateway capabilities, so the **Credit / Debit Card** choice remains available
-without recreating the session.
-> **Deprecated**: the legacy `buttonsTheme` prop (`'default'` / `'minimal'` / `'rounded'` / `'dark'`) still works but new code should use `theme` so the same value drives both the buttons-layout wrapper and the auto-payment fallback. See [ButtonsLayoutStyles reference](https://flopay.com/docs/api-reference/react/flopay-checkout#buttonslayoutstyles-reference) for the underlying override fields.
-#### Button Hooks
-Use `onButtonClick` to track button interactions, `onDecline` to track declines/cancellations, and `onBeforeButtonClick` to enrich any buttons-layout payment method before it continues:
+import { FloPayCheckout } from '@flopay/react';
-```tsx
-<FloPayCheckout
-  layout="buttons"
-  createSession={{
-    clientId: 'your-client-id',
-    currency: 'EUR',
-    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
-    account: { userId: 'user_1', email: 'test@email.com' },
-    successUrl: '/success',
-    cancelUrl: '/cancel',
-  }}
-  onBeforeButtonClick={async ({ method, createSession }) => {
-    if (method !== 'card') {
-      return {
-        tagsData: { sessionId: `checkout_${method}_clicked` },
-      };
-    }
-    const email = await openEmailCaptureModal({
-      initialEmail: createSession?.account.email ?? '',
-    });
-    if (!email) return false;
-    return {
-      account: { email },
-      tagsData: { sessionId: 'checkout_email_captured' },
-    };
-  }}
-  onButtonClick={(method) => {
-    window.dataLayer?.push({ event: 'checkout_button_click', payment_method: method });
-  }}
-  onDecline={(decline) => {
-    window.dataLayer?.push({ event: 'checkout_decline', ...decline });
-  }}
-  onComplete={handleSuccess}
-/>
+export function CheckoutPage({ sessionId, nonce }: { sessionId: string; nonce: string }) {
+  return (
+    <FloPayCheckout
+      sessionId={sessionId}
+      nonce={nonce}
+      theme="modern-light"
+      submitLabel="Pay $10"
+      onComplete={(result) => {
+        if (result.status === 'authorized') {
+          console.log('Funds held for payment', result.paymentId, 'until', result.authorizationExpiresAt);
+        }
+        window.location.assign('/success');
+      }}
+      onDecline={(decline) => console.warn(`${decline.method} declined: ${decline.message}`)}
+      onError={(error) => {
+        if (error.code === 'checkout_session_expired') {
+          window.location.assign('/checkout/expired');
+          return;
+        }
+        console.error(error.message);
+      }}
+      onSessionCompleted={(successUrl) => window.location.assign(successUrl)}
+    />
+  );
+}
 ```
-`onBeforeButtonClick` runs for every payment button in `layout="buttons"`. Branch on `method` if only some flows need extra work. For PayPal, Apple Pay, and Google Pay, keep the hook fast because it runs during the provider button handshake before the wallet sheet or PayPal window opens.
-#### Inline Session Creation
-Skip the backend API route — create the session directly in the component:
+Create the session inline, with the buttons layout, a just-in-time email step for cards, and analytics:
 ```tsx
-<FloPayCheckout
-  layout="buttons"
-  createSession={{
-    clientId: 'your-client-id',
-    currency: 'EUR',
-    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
-    account: { userId: 'user_1' }, // email and name are collected in checkout
-    successUrl: '/success',
-    cancelUrl: '/cancel',
-    checkoutMetadata: { merchantOrderId: 'order-123', campaign: 'summer' },
-  }}
-  onComplete={(result) => window.location.href = '/success'}
-/>
-```
+import { type FloInstrumentEvent, FloPayCheckout } from '@flopay/react';
-The component creates a lightweight shell, attaches the catalog immediately,
-renders every otherwise-eligible method, and identifies the buyer later from
-the selected method or its fallback — zero merchant backend code needed.
-`checkoutMetadata?: Record<string, string> | null` is sent unchanged on that
-initial shell request and never repeated in the catalog or late-buyer claim.
-Omission keeps the previous request shape; explicit `null` and `{}` remain
-distinct wire values. Returned metadata is available on the normalized result
-and its `data.session`. Backend validation errors retain their structured
-`FloPayError` code, message, and HTTP status; React does not duplicate backend
-size or length limits.
+function trackInstrument(event: FloInstrumentEvent) {
+  console.log('checkout instrument', event.name, event);
+}
-#### Authorisation-only checkout
+export function InlineCheckout() {
+  return (
+    <FloPayCheckout
+      layout="buttons"
+      theme="bold-dark"
+      createSession={{
+        clientId: 'your-client-id',
+        currency: 'EUR',
+        items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
+        account: { userId: 'user_1' },
+        successUrl: '/success',
+        cancelUrl: '/cancel',
+        checkoutMetadata: { merchantOrderId: 'order-123' },
+        idempotencyKey: 'checkout:order-123',
+      }}
+      onBeforeButtonClick={async ({ method, createSession }) => {
+        if (method !== 'card') {
+          return { checkoutMetadata: { merchantOrderId: 'order-123', selectedMethod: method } };
+        }
+        const email = window.prompt('Email for your receipt', createSession?.account.email ?? '');
+        return email ? { account: { email } } : false;
+      }}
+      onButtonClick={(method) => console.log('clicked', method)}
+      onInstrument={trackInstrument}
+      onComplete={() => window.location.assign('/success')}
+    />
+  );
+}
+```
-Set `captureMethod: 'manual'` in the same `createSession` draft for an eligible
-item-only card checkout:
+Authorise a one-time card payment now and capture it later from your server:
 ```tsx
-<FloPayCheckout
-  createSession={{
-    clientId: 'your-client-id',
-    captureMethod: 'manual',
-    currency: 'EUR',
-    items: [{ code: 'order_123', totalAmount: 29.99 }],
-    account: { userId: 'user_1', email: 'user@example.com' },
-    successUrl: '/success',
-    cancelUrl: '/cancel',
-  }}
-  onComplete={(result) => {
-    if (result.status === 'authorized') {
-      saveAuthorisation({
-        paymentId: result.paymentId,
-        sessionId: result.sessionId,
-        expiresAt: result.authorizationExpiresAt,
-      });
-    }
-  }}
-  onSessionCompleted={(successUrl) => router.push(successUrl)}
-/>
+import { FloPayCheckout } from '@flopay/react';
+export function AuthorisationCheckout() {
+  return (
+    <FloPayCheckout
+      createSession={{
+        clientId: 'your-client-id',
+        captureMethod: 'manual',
+        currency: 'EUR',
+        items: [{ providerItemId: 'order_123', totalAmount: 29.99 }],
+        account: { userId: 'user_1', email: 'user@example.com' },
+        successUrl: '/success',
+        cancelUrl: '/cancel',
+      }}
+      onComplete={(result) => {
+        if (result.status === 'authorized') {
+          void fetch('/api/authorisations', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              paymentId: result.paymentId,
+              sessionId: result.sessionId,
+              expiresAt: result.authorizationExpiresAt,
+            }),
+          });
+        }
+      }}
+      onSessionCompleted={(successUrl) => window.location.assign(successUrl)}
+    />
+  );
+}
 ```
-The component still releases the buyer to the success experience, but its
-overlay says `PAYMENT AUTHORISED`. `authorized` means funds are held, not paid.
-Capture remains a merchant-authenticated REST operation and is never available
-to browser code. Manual capture is rejected for subscription carts. See the
-repository's [pre-authorisation guide](../../docs/PREAUTHORIZATION.md).
-That create POST sends a stable `Idempotency-Key` header automatically whenever a
-secure RNG is available. `FloPayCheckout` resolves the key once per logical
-checkout, stores it with the inline-session cache in `sessionStorage`, and reuses
-it across transport retries, effect reruns, and component remounts. Concurrent
-mounts (StrictMode double-mount, Suspense remount, or navigation flicker) share
-both the session create and the auto-mode payment attempt, so one purchase cannot
-fan out into multiple creates or charges.
-Logical checkout identity is based on the merchant, buyer, cart/pricing,
-coupons, and checkout metadata. Metadata keys are canonicalized for identity,
-so key-order-only changes reuse the current session while a material metadata
-change creates a new one. Raw metadata is not stored in the inline-session
-cache. Checkout-mode changes, refreshed payment tokens, and analytics/UTM prop
-churn do not rotate the key while that purchase is active. A different cart or
-buyer gets a different key; an email-less buyer is separated by `account.userId`.
-To control the key yourself — for example to keep it stable across your own
-server retries — pass `idempotencyKey` on `createSession`:
+Add a card without charging it:
 ```tsx
-<FloPayCheckout
-  createSession={{
-    /* … */
-    idempotencyKey: `checkout:${orderId}`, // one logical checkout; never reuse for a new purchase
-  }}
-/>
+import { FloPayCardSetup } from '@flopay/react/card-setup';
+export function AddCard({ sessionId, nonce }: { sessionId: string; nonce: string }) {
+  return (
+    <FloPayCardSetup
+      sessionId={sessionId}
+      nonce={nonce}
+      theme="glass-dark"
+      containerStyle={{ borderColor: '#60A5FA', padding: 16 }}
+      onComplete={({ paymentMethod }) => {
+        // Display-only when present; re-list cards from your server when it is absent.
+        console.log(paymentMethod?.brand, paymentMethod?.lastFour);
+      }}
+      onDecline={({ message }) => console.warn(message)}
+      onValidation={(message) => console.log(message)}
+      onError={(error) => console.error(error.code, error.retryable ? 'retry' : 'do not retry')}
+      onCancel={() => console.log('Card setup closed before it finished')}
+    />
+  );
+}
 ```
-The key must be non-empty and at most 255 characters; an invalid value throws a
-`FloPayError('validation_error')` before any request. Omit it and the SDK
-generates a fresh cryptographically random key per logical create when a secure
-RNG is available; without one it omits the header, and a merchant-supplied
-`idempotencyKey` stays the way to remain idempotent. See the
-[`@flopay/js` idempotency docs](../js/README.md#idempotent-checkout-creation)
-for the full contract.
-Session-level `currency` is now **required**. The backend (#760) enforces `@IsNotEmpty` on the field; the SDK pre-validates and throws `FloPayError({ type: 'validation_error', code: 'CurrencyRequired' })` before issuing the request when neither the session nor any item/subscription/product carries a currency. Pass `currency` at the top of `createSession` (preferred), or rely on the legacy fallback to the first item/subscription/product `currency`.
-When you use `onBeforeButtonClick` with `createSession`, any returned
-`InlineSessionPatch` is merged into the draft session params before the selected
-buttons-layout flow continues. That lets you add tracking data or update account
-fields just in time without pre-creating a separate backend session. A returned
-`checkoutMetadata` map replaces the prior map as a whole; return `null` to clear
-it before creation.
-### Detached session creation (default)
-`createSession` checkouts are created in two phases (TeamFloPay/backend#1099):
-a lightweight session *shell* that skips catalog validation and the
-buyer-identity advisory locks, then a background **claim** that attaches the
-catalog. If the draft already contains an email, that claim also attaches the
-buyer. Otherwise it deliberately omits `accountData` and returns a complete,
-still-anonymous session (`buyerIdentified: false`).
-The optional `createSession.timeoutMs` value is applied independently to both
-phases (12 seconds each by default). The shell POST stops its deadline as soon
-as the shell is usable, and the initial catalogue claim PATCH starts with a
-fresh signal and the full budget. Opting out of detached creation keeps the
-one-shot request's single total deadline.
-`FloPayCheckout` renders from the shell, so the hosted card form mounts and
-becomes interactive without waiting for either the claim or Stripe.js — Stripe
-wallets, APMs and PayPal load in parallel with the catalog claim and appear
-from its full `enabledPaymentMethods` list when it lands. The card widget's
-submit button stays gated for that window, because the
-billing API rejects a charge against an unclaimed session; if a buyer clicks
-during it, the widget cancels the click and the form asks them to press pay
-again. In practice the claim resolves while the card is still being filled in.
-Nothing else changes for you: the same session, the same callbacks, the same
-results. Catalog and coupon errors still surface as a checkout load error, just
-from the claim rather than the create. Missing buyer identity never delays this
-catalog claim: provider-capable methods identify the buyer during payment, and
-`claim(account)` performs a separate buyer-only attachment when manual
-collection is needed.
-That buyer-only attachment is not specific to detached creation. Any
-still-anonymous session the checkout renders — a one-shot create without an
-email, or an existing session passed as `sessionId` + `nonce` that the billing
-API returns with `buyerIdentified: false` — gets the same late-buyer claim
-rebuilt from the session's nonce, so the email the SDK collects (or a wallet /
-PayPal approval supplies) reaches `PATCH /v1/checkouts/sessions/{id}/claim`
-before payment. The hosted vault widget's charge is refused server-side for a
-session with no bound buyer, so without that claim an email-less session loaded
-by id would never complete.
-Opt out per session to restore the original single-request create:
+Charge a saved payment method with one button:
 ```tsx
-<FloPayCheckout
-  createSession={{
-    /* … */
-    deferDataAttachment: false, // one-shot create
-  }}
-/>
-```
-Detached creation applies only to `checkoutMode: 'full'` (the billing API
-rejects it for `auto` / `confirm`) and is skipped when `tokenizedData` is
-supplied. There is **no fallback** to the one-shot create — it requires a
-billing API `v1.7.12` or newer that exposes the independent catalog/buyer
-`PATCH /v1/checkouts/sessions/{id}/claim` contract.
+import { FloPayAutomaticPaymentButton } from '@flopay/react';
-### Advanced: Manual Provider Setup
+export function UpsellButton() {
+  return (
+    <FloPayAutomaticPaymentButton
+      clientId="your-client-id"
+      account={{ userId: 'user_1', email: 'user@example.com' }}
+      items={[
+        {
+          providerItemId: 'upsell_1',
+          providerItemName: 'AI Supercharger Pack',
+          totalAmount: 249,
+          overrideAmount: 80,
+          currency: 'EUR',
+          quantity: 1,
+        },
+      ]}
+      successUrl="https://shop.example.com/success"
+      cancelUrl="https://shop.example.com/cancel"
+      theme="bold-dark"
+      onClick={() => console.log('automatic payment button clicked')}
+      onSuccess={({ sessionId, autoCompleted }) => console.log('paid', sessionId, autoCompleted)}
+      onDecline={(decline) => console.warn('declined', decline.message)}
+      onError={(error) => console.error(error.message)}
+    >
+      Purchase Item
+    </FloPayAutomaticPaymentButton>
+  );
+}
+```
-Use `SplitCardForm` when you need to compose the provider and session yourself.
-Card checkout uses the backend-hosted vault widget; Stripe remains limited to
-wallets/APMs and saved-payment authentication. The session can supply the
-widget eagerly in `session.vault`, or explicitly advertise `card` in
-`gateways.stripe.enabledPaymentMethods` so the SDK recovers it on demand.
+Compose the provider, a checkout surface, and the hooks yourself:
 ```tsx
-import { FloPayProvider, SplitCardForm } from '@flopay/react';
 import { loadFloPay } from '@flopay/js';
+import type { CheckoutSession } from '@flopay/shared';
+import { FloPayProvider, SplitCardForm, useCheckout, useFloPay } from '@flopay/react';
 const floPayPromise = loadFloPay('pk_test_...');
-function CheckoutPage() {
+function PaymentStatus() {
+  const flopay = useFloPay();
+  const { loading, error, claimPending } = useCheckout();
+  if (!flopay || loading) return <p>Loading payment methods…</p>;
+  if (error) return <p role="alert">{error.message}</p>;
+  return claimPending ? <p>Preparing your order…</p> : null;
+}
+export function ComposedCheckout({ session, nonce }: { session: CheckoutSession; nonce: string }) {
   return (
-    <FloPayProvider
-      flopay={floPayPromise}
-      options={{
-        amount: 2999,
-        currency: 'usd',
-      }}
-    >
+    <FloPayProvider flopay={floPayPromise} options={{ billingApiUrl: 'https://billing.example.com' }}>
+      <PaymentStatus />
       <SplitCardForm
-        sessionId="session_uuid"
-        nonce={sessionNonce}
+        sessionId={session.id}
+        nonce={nonce}
         session={session}
-        billingApiUrl="https://billing.example.com"
         email="user@example.com"
         userId="user_1"
-        totalAmount={2999}     // cents
+        totalAmount={2999}
         currency="usd"
+        enableAVS
         enabledPaymentMethods={session.gateways?.stripe?.enabledPaymentMethods}
         onComplete={(result) => {
-          if (result.status === 'succeeded') {
-            window.location.href = '/success';
-          }
+          if (result.status === 'succeeded') window.location.assign('/success');
         }}
-        onError={(err) => console.error(err)}
-        onFirstNameChange={(name) => setFirstName(name)}
-        onLastNameChange={(name) => setLastName(name)}
+        onError={(error) => console.error(error.message)}
       />
     </FloPayProvider>
   );
 }
 ```
-The resulting surfaces are:
-1. Wallet buttons and supported APM tiles from the session gateway capability.
-2. Direct or Stripe-hosted PayPal, selected from the session gateways.
-3. The hosted vault widget for sessions with embedded vault HTML or an explicit
-   Stripe `card` capability.
-Wallets, APMs, and PayPal create intents through
-`POST /v1/checkouts/sessions/{id}/intents`. The discriminated request separates
-provider, payment-method category/type/id, and intent kind. Direct-card intent
-requests are unsupported. Client-observed non-card failures use the
-nonce-protected session decline endpoint and contain no payment tokens,
-provider object IDs, card data, credentials, or PII.
-For SDK 1.4.9+, an explicit Stripe `card` capability keeps card checkout
-visible even when the backend omits the vault block. In `layout="buttons"`,
-`POST /v1/checkouts/sessions/{id}/vault/capture` is deferred until the buyer
-selects Card. An embedded block remains the preferred fast path and causes no
-recovery POST. Sessions that advertise neither an embedded block nor `card`
-do not call the recovery endpoint; their non-card methods remain usable, and
-if none remain, `onError` receives `UnsupportedBackendVaultCapability`.
-#### AVS postcode validation
-When AVS collection is enabled (`enableAVS`) and the postcode field is shown,
-`SplitCardForm` validates the postcode **format against the live selected
-country before the hosted vault captures the card**.
-It reuses `@flopay/shared`'s country-aware
-[postcode helpers](../shared/README.md#postal-code-helpers) (the same
-`validator` rules the billing API applies), so client and server agree.
-- **Supported country + malformed postcode** → the vault widget's submit is blocked
-  and an inline, country-specific message shows the expected format
-  (e.g. *"Enter a valid ZIP Code (e.g. 12345 or 12345-6789)"*). On the vault
-  path the inline message appears once the field is blurred, since the disabled
-  submit means it can't be reached by a submit attempt.
-- **Supported country + empty postcode** → the same submit gate applies, and
-  once the field is blurred (or a submit is attempted) an inline *required*
-  message shows (e.g. *"ZIP Code is required"*) rather than the expected-format
-  copy.
-- **Country with no postal system** (or a locale `validator` doesn't recognise)
-  → the postcode field is shown but **optional**: empty and format checks are
-  both skipped, so these buyers are never blocked.
-The collected email field and the AVS street, city and state fields follow the
-same pattern: while empty (or, for email, malformed) they hold the submit gate
-shut, and once the buyer leaves the field (or a submit is attempted) they show
-the same red outline and inline `role="alert"` message (e.g. *"Street address is
-required"*, *"Enter a valid email address"*).
-On the **vault card path** the widget's submit button is gated **synchronously**
-on the client-side AVS check above. Because the client postcode rules mirror the
-backend validator (`validator@13.15.35`) verbatim, a postcode the server's
-`PATCH /v1/checkouts/sessions/{id}/account` would reject is already blocked here —
-before the button ever enables — with no network round-trip in the critical path.
-The gate is **never** held pending an async request: the hosted widget silently
-swallows a click that lands while the button is disabled and offers no way to
-auto-resubmit on release, so an async gate would strand any buyer (or single-click
-preview) who clicked before it resolved — the checkout would write no attempt and
-time out (sdk#124).
-When the buyer submits, `SplitCardForm` persists the billing snapshot
-best-effort **in parallel** with the widget's charge:
-- **Backend rejects the address (a `4xx`)** — a residual, non-postcode drift, since
-  the postcode is already client-validated — the specific message (e.g. *"Postal/ZIP
-  code is not valid for the selected country…"*) shows inline **and** fires `onError`
-  with the parsed `FloPayError`, and the processing overlay clears so the buyer can
-  correct and retry. The charge cannot be cancelled once submitted, so this surfaces
-  for the buyer's *next* attempt rather than stopping the in-flight one.
-- **Transient failure (`5xx` / network)** → best-effort and buyer-silent: the
-  backend listener falls back to the session's baseline address while the
-  widget completes the charge.
-- **Internal 10-second timeout** → the same functional fallback applies, and
-  successful widget completion still reaches `onComplete`. Telemetry records
-  the privacy-safe lifecycle event `operation.fallback` with
-  `processing` / `account_snapshot` / `timeout` dimensions instead of an
-  alert-level technical error. Direct and blocking timeout paths remain errors.
-### Vault PCI card form
-The card path renders a **backend-served, self-contained hosted vault widget**
-(`VaultCardFields`) (TeamFloPay/backend#823, Model A). The billing API may
-return it eagerly in `session.vault`, or advertise `card` under
-`gateways.stripe.enabledPaymentMethods` and let SDK 1.4.9+ request it lazily.
-It is fully **server-driven** — there is no consumer prop to toggle it. The
-widget owns the card fields, its own submit button, card tokenization, the
-PaymentIntent (created **and** confirmed server-side), **3DS**, and the result,
-so **no Stripe.js runs on the card path** and PAN / CVC never enter the SDK
-runtime. Wallets / PayPal / APMs render exactly as before.
-Because the widget owns the form, `SplitCardForm` renders no SDK card-entry
-fields or submit button of its own; `submitLabel` only sets the wording of the
-widget's button (see [Hosted card submit label](#hosted-card-submit-label)).
-Host-collected AVS fields remain outside the PCI
-widget and gate its submit. The flow is:
-```text
-session embeds session.vault or advertises gateways.stripe.enabledPaymentMethods: ['card']
-  → SDK uses embedded HTML, or requests POST /vault/capture when Card is needed
-  → concurrent renders/remounts share that active request
-  → buyer pays inside the widget (tokenize → charge → 3DS, all backend-owned)
-  → widget postMessages its outcome → SDK fires onComplete / onDecline / onError
-```
-- Embedded `session.vault.html` is the preferred fast path during rollout and
-  never triggers a recovery request.
-- Deferred capture uses
-  `POST /v1/checkouts/sessions/{id}/vault/capture`, with a ten-second timeout,
-  bounded transient-network retry, and one shared active request per
-  base URL/session/nonce.
-- **Returning customers** with a card on file (`session.providerPaymentMethodId`)
-  are charged by the backend's auto-checkout cascade.
-- **3DS** is handled inside the widget — there is no client-side `confirmCardPayment`.
-**Processing feedback:** after the hosted widget emits `submitting`, the SDK's
-full-checkout processing overlay remains visible continuously until the widget
-reports `complete`, `decline`, or `error`. Intermediate status polling and
-late card-field validation mutations cannot expose the completed form while a
-charge is still in flight. A synchronous card-validation rejection still
-returns the buyer to the form immediately, as does a `4xx` account-snapshot
-validation failure.
-**Failure modes:** `onDecline` / `onError` receive the mapped reason + message
-so consumers can react, and the SDK leaves an inline retry message after its
-terminal failure overlay clears.
-> **Backend dependencies:** the hosted widget must emit the `flopay-vault`
-> `postMessage` outcome the SDK listens for (otherwise it falls back to its own
-> success redirect), handle the 3DS step internally, and use the session account
-> snapshot for AVS. The SDK collects and validates those address fields outside
-> the PCI widget and persists them through the session account endpoint; the
-> widget owns only sensitive card-data capture. Because the widget is injected
-> **same-window**, every terminal outcome must be bound to the session id, and —
-> to fully defend against same-window forgery — the backend should mint a
-> per-session `messageToken` on the vault block and echo it in each
-> `postMessage`; the SDK threads it through and rejects outcomes that omit or
-> mismatch it (TeamFloPay/backend#823).
-### PayPal Handling
-The SDK supports two PayPal paths, selected per-session based on what the billing API advertises under `gateways.*`:
-- **Direct PayPal** (preferred where available — works inside Facebook, Instagram, and other in-app browsers): when the session exposes `gateways.paypal.publishableKey`, the SDK renders PayPal via the official PayPal JS SDK using `<DirectPayPalButton>`. The PayPal client ID and `environment` (`'sandbox'`/`'live'`) come directly from the backend.
-- **Stripe-rendered PayPal**: when only `gateways.stripe` is configured, PayPal renders through Stripe's `ExpressCheckoutElement` in its own Elements wrapper. This path can't render in Facebook/Instagram in-app browsers.
-Renderer selection is mutually exclusive per session — direct PayPal takes priority over Stripe-rendered PayPal. Consumer props such as `showPayPal` continue to gate visibility on the client side.
-**PayPal-only sessions:** When the backend advertises only `gateways.paypal` (no `gateways.stripe`), `FloPayCheckout` skips Stripe Elements entirely and renders `<DirectPayPalButton>` as the sole payment surface. Sessions that advertise no supported gateway at all throw a `validation_error` explaining the expected shape.
-**Provider-first buyer identity:** Direct PayPal never hides its Smart Button
-behind a Flo buyer-details preflight. An anonymous buyer starts PayPal normally;
-after approval the SDK reads the payer email/name, attaches valid returned
-details, and continues processing. If PayPal returns incomplete identity, the
-SDK shows exactly one required fallback pane after approval and resumes with
-the collected values. A checkout that supplied buyer details up front keeps its
-existing request bodies and callbacks.
-**In-app presentation and recovery:** Direct PayPal classifies the browser once
-per mount into a bounded app family; it never records the raw user agent.
-`approvalPresentation` selects the bounded `app_switch` mode only for a
-one-time Order in an in-app browser. When the backend advertises
-`gateways.paypal.approvalPresentation: 'app_switch'`, that mode enables PayPal's
-`appSwitchWhenAvailable` Buttons option.
-Ordinary browsers, legacy sessions, subscriptions, and setup tokens preserve
-the popup flow. The PayPal button stays visible in every environment as a
-result of this choice. If an in-app popup is blocked and no supported non-popup
-mode is available, `onTechnicalFailure` receives `popupBlocked: true` with
-fixed guidance to open the page in the system browser; ordinary browsers keep
-the existing allow-popups guidance, and PayPal remains visible for retry.
-`approvalPresentation` is a bounded mode, not a URL. Merchant code cannot
-inject a return URL or resume token. Although the shared response type reserves
-`'redirect'`, the classic Buttons adapter does not activate it: deterministic
-redirect remains gated on the backend-issued signed resume contract and a
-proven PayPal adapter that captures before merchant-success navigation. Until
-both land, a redirect advertisement safely preserves popup behavior. This
-instrumentation explains where approval attempts stop; it does not by itself
-attribute the historical conversion drop to a particular browser or provider
-failure.
-**Flo-owned subscription continuations:** `gateways.paypal.providerObjectType`
-selects the direct PayPal operation. `'order'` loads the PayPal SDK with
-`intent=capture` and invokes `createOrder`, even when the checkout session mode
-is subscription. `'subscription'` preserves the provider-managed
-`intent=subscription` / `createSubscription` flow. `'setup_token'` invokes
-`createVaultSetupToken`; approval submits the returned `vaultSetupToken` to the
-nonce-bound session `/process` route for backend exchange and activation. An
-advertised `'order'`/`'setup_token'` opts the intent request and tokenized
-process body into the `paypal_vaulted` payment-method channel; the intent
-response must match the advertised object type. When the field is absent,
-legacy sessions continue to derive Order versus Subscription from
-`isSubscription` and keep the released `paypal` requests byte-identical. See
-the full [channel-selection and cutover contract](../../docs/PAYPAL_FLO_SUBSCRIPTION_CONTINUATIONS.md).
-**Direct PayPal initialization recovery:** Any active-generation technical
-failure before PayPal becomes ready — script rejection, a namespace without a
-usable `Buttons` factory, an eligible pre-ready `onError`, a `render()`
-rejection, or the SDK's 11-second render watchdog — hides Direct PayPal, waits
-one second, and makes exactly one background remount. Recovery is based on
-lifecycle state, not provider error text. The retry uses a fresh render
-generation, and callbacks or promise settlements from the superseded generation
-are ignored. Startup remount does not create a checkout session, intent, or
-charge; the first recovered buyer click creates at most one intent under the
-existing per-click idempotency contract.
-In a mixed checkout, card, wallets, APMs, and any other eligible methods remain
-interactive throughout recovery. If Direct PayPal is configured alongside
-Stripe-rendered PayPal, the Stripe-rendered path activates while Direct PayPal
-is retrying or exhausted. If both Direct PayPal attempts fail, PayPal stays
-hidden for that component configuration; the SDK emits one sanitized console
-diagnostic and calls neither `onError` nor `onDecline`. Empty configuration,
-`isEligible() === false`, cancellation, supersession, unmount, and recognized
-lifecycle teardown are not automatically retried. Ineligibility still notifies
-the parent that PayPal is unavailable so a fallback can appear, without
-technical telemetry.
-In a PayPal-only checkout, `FloPayCheckout` shows an accessible retrying status
-instead of a blank surface. After automatic recovery is exhausted, it shows safe
-generic unavailable copy and a **Retry PayPal** button. `onError` fires once with
-a `FloPayError` whose `type` is `api_error` and whose stable `code` is
-`paypal_init_timeout`; `onDecline` does not fire and the raw provider message is
-never rendered. Manual retry reuses the current checkout session and performs
-one fresh render attempt without adding another automatic retry.
-The SDK exposes the relevant pieces in three ways:
-- **`SplitCardForm`** / **`FloPayCheckout`**: pick the renderer automatically based on `gateways.*`. No additional configuration needed.
-- **`FloPayProvider`** (manual composition): accepts an optional `paypalFlopay` prop used to drive Stripe's PayPal redirect leg. Load a second `FloPay` instance yourself only if you need to render PayPal manually. `usePayPalFloPay()` exposes it to descendants.
-- **`DirectPayPalButton`** (standalone): can be rendered outside `SplitCardForm` when you only need the PayPal button. Pass `clientId`, `currency`, `environment`, `isSubscription`, and the backend-advertised `providerObjectType` and `approvalPresentation` when present. The backing session is authoritative; `isSubscription` remains the compatibility fallback when the object type is absent.
-### Using Hooks
-```tsx
-import { useFloPay, useCheckout } from '@flopay/react';
-function PaymentStatus() {
-  const flopay = useFloPay();       // FloPay | null
-  const checkout = useCheckout();    // { session, loading, error, claimPending }
-  if (!flopay) return <div>Loading SDK...</div>;
-  // ...
-}
-```
-## API Reference
+## Public API
 ### Components
 | Component | Description |
 |-----------|-------------|
-| `FloPayProvider` | Context provider. Accepts `flopay` (instance or promise), optional `paypalFlopay`, `options?`, and `children`. |
-| `FloPayCheckout` | Recommended self-contained session checkout. Resolves gateways, mounts hosted-vault cards, and preserves wallets/APMs/PayPal/saved-payment flows. |
-| `FloPayCardSetup` | Browser-only no-charge card verification for a merchant-server-created setup session. Requires `sessionId` + `nonce`; reports ready, verified completion, decline, validation, retryable technical error, and cancellation outcomes. |
-| `SplitCardForm` | Advanced checkout surface combining hosted-vault cards with wallets, APMs, and PayPal. Supports `ref` for imperative next-action handling. |
-| `VaultCardFields` | Hosted vault PCI card fields. Used internally by `SplitCardForm` on the vault path; consumes a `CardCaptureAdapter` from `useFloPay().cardCapture()`. |
-| `DirectPayPalButton` | Standalone direct PayPal Order, provider-managed Subscription, or setup-token button using the session-scoped intent contract. |
+| `FloPayCheckout` | Recommended self-contained checkout. Resolves gateways, mounts the hosted card form, and renders wallets, alternative methods, PayPal, and saved-payment flows. |
+| `FloPayCardSetup` | No-charge card verification for a merchant-server-created setup session. Also exported from `@flopay/react/card-setup`. |
+| `FloPayAutomaticPaymentButton` | One-click button that charges the customer's saved payment method, falling back to `FloPayCheckout` |
+| `FloPayProvider` | Context provider for composed checkouts |
+| `SplitCardForm` | Checkout surface combining the hosted card form with wallets, alternative methods, and PayPal |
+| `VaultCardFields` | The hosted PCI card form. `SplitCardForm` uses it internally; it consumes a `CardCaptureAdapter` from `useFloPay().cardCapture()`. |
+| `DirectPayPalButton` | Standalone direct PayPal Order, PayPal-managed subscription, or setup-token button using the session intent contract |
 ### Hooks
 | Hook | Returns | Description |
 |------|---------|-------------|
-| `useFloPay()` | `FloPay \| null` | Current FloPay instance from context. `null` while loading. |
-| `useCheckout()` | `CheckoutState` | `{ session, loading, error, claimPending }` from CheckoutContext. `claimPending` remains true while a detached shell is not safe to charge. |
+| `useFloPay()` | `FloPay \| null` | The current FloPay instance, or `null` while it loads |
+| `useCheckout()` | `CheckoutState` | `{ session, loading, error, claimPending }` for the surrounding checkout |
+| `usePayPalFloPay()` | `FloPay \| null` | The optional FloPay instance used for Stripe-rendered PayPal |
-### FloPayProviderProps
+### Other exports
-| Prop | Type | Description |
-|------|------|-------------|
-| `flopay` | `Promise<FloPay> \| FloPay` | SDK instance or promise from `loadFloPay()` |
-| `paypalFlopay` | `Promise<FloPay> \| FloPay \| null` | Optional Stripe instance used for the Stripe-rendered PayPal redirect leg. |
-| `options.billingApiUrl` | `string?` | Billing API base URL exposed to child components. |
-| `onInstrument` | `(event: FloInstrumentEvent) => void` | Versioned, privacy-safe checkout funnel and phased error feed for merchant analytics. |
+| Export | Description |
+|--------|-------------|
+| `FloPayCardSetupError` | Card-setup error class: a `FloPayError` with an explicit `retryable` flag |
+| `dropThirdPartyOnlyError(event)` | Sentry `beforeSend` predicate re-exported from `@flopay/shared` |
-### FloPayCardSetupProps
+### FloPayCheckoutProps
 | Prop | Type | Description |
 |------|------|-------------|
-| `sessionId` | `string` | Opaque id returned by the merchant-authenticated setup-session endpoint. |
-| `nonce` | `string` | Required session-bound read/capture token. |
-| `billingApiUrl` | `string?` | Billing API base URL; defaults through normal FloPay environment resolution. |
-| `telemetry` | `boolean?` | Privacy-safe operational telemetry; set `false` to opt out. |
-| `theme` | `ThemeId \| VaultCardThemeColors?` | High-level theme id (same values as `FloPayCheckout`, resolved through the same bundle) or raw hosted-widget colors. A preset styles the surrounding surface, the hosted form (complete submit snapshot included), and the outcome overlay coherently; see [Card-setup theming](#card-setup-theming). Defaults to `'modern-light'`; `'classic'` keeps the historic FloPay look and raw objects are forwarded unchanged. |
-| `containerStyle` | `React.CSSProperties?` | Inline styles for the hosted-widget container, merged over a preset's surface with deterministic precedence: each property wins over the preset's, a longhand refines a preset shorthand, any `background*` member replaces the preset background, and `'classic'` / raw themes apply it alone. |
-| `loading` | `React.ReactNode?` | Content shown while the session and hosted widget load. |
-| `onReady` | `() => void` | Hosted widget is mounted and accepting input. |
-| `onComplete` | `(event: FloPayCardSetupCompleteEvent) => void` | Verified usable card. Includes `sessionId` and optional display-only `paymentMethod`; never amount, charge, or payment-success data. |
-| `onDecline` | `(event: FloPayCardSetupDeclineEvent) => void` | Terminal card-verification decline. |
-| `onValidation` | `(message: string \| null) => void` | Live hosted-field validation; not a technical error. |
-| `onError` | `(error: FloPayCardSetupError) => void` | Validation/technical failure with stable `code` and explicit `retryable`. |
-| `onCancel` | `(event: FloPayCardSetupCancelEvent) => void` | Fires once when the component unmounts before a terminal outcome. |
-### Privacy-safe operational telemetry
-`FloPayCheckout` emits the same closed Flo-owned lifecycle/error/performance
-contract as `@flopay/js`, including React render/interactivity and provider
-readiness milestones. Collection is best-effort; merchant callbacks remain
-available with their existing arguments and invocation order. Synchronous
-throws and rejected callback promises are contained and logged only to the
-merchant console; they are not uploaded as `CALLBACK_FAILED`. Set the single
-`telemetry={false}` prop to opt out:
+| `sessionId` | `string?` | Existing checkout session id. Required unless `createSession` is provided. |
+| `nonce` | `string?` | Session-bound checkout token for `sessionId` |
+| `createSession` | `InlineSessionDraft?` | Creates the session inline instead of using `sessionId` |
+| `checkoutMode` | `CheckoutMode?` | Overrides the session's checkout mode |
+| `billingApiUrl` | `string?` | Billing API base URL; defaults to the configured environment |
+| `layout` | `'default' \| 'buttons'` | Payment form layout |
+| `theme` | `ThemeId?` | Theme bundle for the whole checkout |
+| `appearance` | `FloPayAppearance?` | Stripe-side appearance overrides |
+| `buttonsStyles` | `ButtonsLayoutStyles?` | Wrapper style overrides layered on the theme |
+| `locale` | `string?` | Locale for payment elements |
+| `submitLabel` | `string \| null` | Live wording for the hosted card submit button |
+| `confirmLabel` | `string?` | Saved-payment button label in confirm mode |
+| `renderConfirmButton` | `function?` | Custom confirm-mode button renderer |
+| `showStripe` | `boolean?` | Show Stripe wallets and alternative methods (default `true`) |
+| `showPayPal` | `boolean?` | Show PayPal (default `true`) |
+| `enabledPaymentMethods` | `string[]?` | Overrides the session's advertised Stripe methods |
+| `enableAVS` | `boolean \| AVSFieldConfig` | Collect and validate the billing address |
+| `avsLayout` | `'row' \| 'column'` | AVS field layout |
+| `cardFieldOrder` | `VaultCardFieldKey[]?` | Order of the hosted card rows |
+| `cardPreFormSlot` | `ReactNode?` | Content rendered above the hosted card form |
+| `cardButtonContent` | `ReactNode?` | Card tile content in `layout="buttons"` |
+| `cardBackButtonContent` | `ReactNode?` | Back-button label in `layout="buttons"` |
+| `cardTitleContent` | `ReactNode?` | Card-form title |
+| `className` | `string?` | Extra wrapper class |
+| `loading` | `ReactNode?` | Custom loading UI |
+| `error` | `(error: FloPayError) => ReactNode` | Custom error UI |
+| `initialErrorMessage` | `string \| null` | Seeds an initial error message |
+| `children` | `ReactNode?` | Custom layout rendered instead of the default `SplitCardForm` |
+| `telemetry` | `boolean?` | Set `false` to opt out of operational telemetry |
+| `onComplete` | `(result: PaymentResult) => void` | Payment succeeded or was authorized |
+| `onDecline` | `(decline: DeclineEvent) => void` | A payment was declined or authentication failed |
+| `onError` | `(error: FloPayError) => void` | A checkout error occurred |
+| `onSessionCompleted` | `(successUrl: string) => void` | The session was already completed |
+| `onButtonClick` | `(method: CheckoutButtonMethod) => void` | A payment method button was clicked |
+| `onBeforeButtonClick` | `(event: BeforeButtonClickEvent) => ...` | Runs before a buttons-layout method continues; return a patch or `false` |
+| `onInstrument` | `(event: FloInstrumentEvent) => void` | Merchant instrument feed |
+| `onCountryChange` / `onZipChange` | `(value: string) => void` | AVS country or postcode changed |
+| `showApplePay` / `showGooglePay` / `buttonsTheme` | deprecated | Superseded by the session's methods and `theme` |
-```tsx
-<FloPayCheckout sessionId={sessionId} nonce={nonce} telemetry={false} />
-```
-No endpoint, custom tag, user context, message, stack, or metadata can be
-configured. See [`docs/TELEMETRY.md`](../../docs/TELEMETRY.md) for the complete
-privacy and retention contract.
+### FloPayProviderProps
-If the React host has its own Sentry client, use the re-exported pure filter as
-the host's `beforeSend` callback:
+| Prop | Type | Description |
+|------|------|-------------|
+| `flopay` | `FloPay \| Promise<FloPay> \| null` | A FloPay instance or the promise from `loadFloPay()` |
+| `paypalFlopay` | `FloPay \| Promise<FloPay> \| null` | Optional instance for the Stripe-rendered PayPal leg |
+| `options.billingApiUrl` | `string?` | Billing API base URL exposed to child components |
+| `onInstrument` | `(event: FloInstrumentEvent) => void` | Merchant instrument feed |
+| `children` | `ReactNode` | Checkout content |
-```ts
-import * as Sentry from '@sentry/browser';
-import { dropThirdPartyOnlyError } from '@flopay/react';
+### FloPayCardSetupProps
-Sentry.init({ beforeSend: dropThirdPartyOnlyError });
-```
+| Prop | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` | Opaque id from the merchant-authenticated setup-session endpoint |
+| `nonce` | `string` | Session-bound token returned with `sessionId` |
+| `billingApiUrl` | `string?` | Billing API base URL; defaults to the configured environment |
+| `telemetry` | `boolean?` | Set `false` to opt out of operational telemetry |
+| `theme` | `ThemeId \| VaultCardThemeColors` | Preset (default `modern-light`) or raw hosted-form colors |
+| `containerStyle` | `CSSProperties?` | Container styles merged over the preset surface |
+| `loading` | `ReactNode?` | Content shown while the session and form load |
+| `onReady` | `() => void` | The hosted form is mounted and accepting input |
+| `onComplete` | `(event: FloPayCardSetupCompleteEvent) => void` | The card is verified and usable |
+| `onDecline` | `(event: FloPayCardSetupDeclineEvent) => void` | Verification was declined |
+| `onValidation` | `(message: string \| null) => void` | Live hosted-field validation, not an error |
+| `onError` | `(error: FloPayCardSetupError) => void` | Validation or technical failure with `code` and `retryable` |
+| `onCancel` | `(event: FloPayCardSetupCancelEvent) => void` | Unmounted before a terminal outcome |
+### FloPayAutomaticPaymentButtonProps
+Also accepts every standard `button` attribute, such as `onClick`, `disabled`, and `className`.
-No Sentry package or configuration is bundled by FloPay. The predicate drops
-only complete exception stacks with no app or `@flopay/*` frame and at least
-one recognised browser-extension URL or Stripe `dahlia/stripe.js` path/module
-marker. Anonymous frames may accompany that marker. Mixed, unrelated,
-incomplete, and anonymous-only errors pass through unchanged. The `in_app`
-flag is ignored because host rewriting may set it to `true` on third-party
-frames.
-Inline session creation classifies bounded failures without inspecting raw
-errors: network/CORS/timeouts emit `transport_error`, 5xx responses emit
-`server_error`, and malformed response discriminants emit `invalid_response`.
-Stripe and PayPal SDK load/runtime failures emit `provider_runtime`. Inline
-4xx validation rejections and ordinary payment declines remain non-error
-`validation_rejected` / `payment_declined` outcomes and never carry
-`failureCategory`.
-If Stripe.js cannot initialize after `FloPayCheckout` resolves a full session,
-the checkout no longer hides a provider-independent payment surface. A
-vault-capable session continues with the hosted card form, and Direct PayPal
-continues when the session advertises it; Stripe wallets and APMs are omitted.
-The degraded surface exposes one **Retry payment methods** action. It retries
-only provider initialization and never repeats session read/create/claim,
-automatic checkout, intent creation, or payment processing. A failed retry is
-not offered again during that mount, and cards or Direct PayPal remain usable.
-When neither the hosted card form nor Direct PayPal can render, `onError` and
-the `error` render prop receive a `FloPayError` with code
-`CheckoutInitializationFailed`. The default error surface uses fixed buyer-safe
-copy. Raw provider messages are never placed in the DOM or merchant callback.
-Existing-session transport and malformed-response failures are separately
-reported at `session_read`; expected session outcomes remain non-alerting.
-Direct PayPal script and unusable-namespace failures remain
-`PROVIDER_LOAD_FAILED` at `provider_load`. Once PayPal reports the button as
-eligible, a pre-ready `onError` or rejected `render()` is instead
-`PROVIDER_RUNTIME_FAILED` at `provider_ready`. These bounded groups contain no
-provider message or stack. Ineligibility, superseded renders, and recognized
-PayPal teardown remain non-alerting; only true load failures project to the
-merchant instrument feed as `checkout_error` / `sdk_load`.
-The same classification applies to React-owned saved-payment processing in
-`auto` and `confirm` modes. An ordinary saved-payment `400` decline, a
-structured-field `400`, or a `422` still falls back to the usable full checkout
-and emits `operation.fallback`, but reports only the matching
-`payment_declined` or `validation_rejected` outcome. Genuine server,
-transport, malformed-response, and provider-runtime failures remain
-categorized technical errors. This does not change fallback rendering or
-merchant callback behavior, and no response body, provider payload, session
-value, payment data, or raw error message is added to telemetry.
+| Prop | Type | Description |
+|------|------|-------------|
+| `sessionId` / `nonce` | `string?` | Reuse an existing auto-mode session |
+| `createSession` | `InlineSessionDraft?` | Inline draft for the session to create |
+| `clientId` | `string?` | Merchant client id for inline creation |
+| `items` / `subscriptions` / `products` | arrays | Cart for inline creation |
+| `account` | `object?` | Buyer account; `userId` required, `email` optional |
+| `successUrl` / `cancelUrl` | `string?` | Redirect targets |
+| `couponCodes` | `string[]?` | Coupons to apply |
+| `tagsData` / `utmMetadata` | objects | Analytics context |
+| `billingApiUrl` | `string?` | Billing API base URL |
+| `locale` | `string?` | Locale for the fallback checkout |
+| `theme` | `ThemeId?` | Theme for the button and its fallback checkout |
+| `appearance` / `buttonsStyles` | objects | Appearance overrides |
+| `onSuccess` | `(event: FloPayAutomaticPaymentSuccessEvent) => void` | Payment completed |
+| `onDecline` | `(decline: DeclineEvent) => void` | Payment declined |
+| `onError` | `(error: FloPayError) => void` | Payment or setup error |
+| `children` | `ReactNode?` | Button content |
 ### SplitCardFormProps
-Key payment-surface props include:
+| Prop | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` | Checkout session id |
+| `nonce` | `string?` | Session-bound token forwarded on intent, decline, account, and process calls |
+| `session` | `CheckoutSession \| null` | Session capability data, including the optional `vault` block and gateways |
+| `billingApiUrl` | `string?` | Billing API base URL |
+| `email` / `userId` / `firstName` / `lastName` | `string?` | Buyer details |
+| `totalAmount` | `number?` | Amount in the smallest currency unit, for wallet and PayPal configuration |
+| `currency` | `string?` | Currency code for wallet and PayPal configuration |
+| `layout` | `'default' \| 'buttons'` | Payment form layout |
+| `theme` | `ThemeId?` | Theme bundle |
+| `submitLabel` | `(string \| null)?` | Live wording for the hosted card submit button; omitted, `null`, or blank shows the hosted default `CONFIRM PAYMENT` |
+| `showStripe` / `showPayPal` | `boolean?` | Toggle Stripe methods and PayPal |
+| `enabledPaymentMethods` | `string[]?` | Stripe method identifiers; `card` advertises the hosted card form |
+| `enableAVS` | `boolean \| AVSFieldConfig` | Collect and validate the billing address |
+| `cardFieldOrder` | `VaultCardFieldKey[]?` | Order of the hosted card rows |
+| `onBuyerIdentityReady` | `(identity) => MaybePromise<void>` | Attach a buyer identity collected by the form; `FloPayCheckout` wires its late-buyer claim here |
+| `onTokenizedBody` | `(body: TokenizedBody) => void` | Take over non-card backend submission yourself |
+| `onComplete` / `onDecline` / `onError` | callbacks | Checkout outcomes |
+| `directPaypal` | `object?` | Direct PayPal client configuration when wiring PayPal manually; `FloPayCheckout` resolves it from `gateways.paypal` |
+| `showApplePay` / `showGooglePay` | deprecated | Superseded by the session's `enabledPaymentMethods` |
+### DirectPayPalButtonProps
 | Prop | Type | Description |
 |------|------|-------------|
-| `sessionId` | `string` | Checkout session UUID. |
-| `nonce` | `string` | Session-bound token forwarded on intent, decline, account, and process calls. |
-| `session` | `CheckoutSession?` | Session capability data, including the optional hosted `vault` fast path and gateways. |
-| `billingApiUrl` | `string` | Billing API base URL. |
-| `showStripe` | `boolean` | Show Stripe-backed wallets/APMs and the hosted card path when the session embeds `vault` or advertises `card`. |
-| `showPayPal` | `boolean` | Show PayPal. Renderer chosen by `gateways.paypal` presence (DirectPayPal JS SDK when present; Stripe-rendered PayPal otherwise). Default: `true`. |
-| `enabledPaymentMethods` | `string[]?` | Per-session list of Stripe method type identifiers (`card`, `apple_pay`, `google_pay`, `cashapp`, `klarna`, `link`, `amazon_pay`, `sepa_debit`, `affirm`, `ideal`, …). Normally threaded automatically from `gateways.stripe.enabledPaymentMethods` by `FloPayCheckout`. The SDK partitions non-card methods between ExpressCheckoutElement and PaymentElement; `card` advertises the hosted-vault path and is never rendered by Stripe. |
-| `showApplePay` | `boolean` | *Deprecated.* Apple Pay availability is dashboard-controlled at Stripe and surfaces through `enabledPaymentMethods`. Emits a one-time `console.warn` when supplied alongside `enabledPaymentMethods` and is otherwise ignored. Removed in `2.0`. |
-| `showGooglePay` | `boolean` | *Deprecated.* See `showApplePay`. |
-| `directPaypal` | `{ clientId: string; environment?: GatewayEnvironment }?` | *Deprecated input on `FloPayCheckout`* — auto-resolved from `gateways.paypal` on the session response. Still accepted on `SplitCardForm` for advanced consumers wiring providers manually. |
-| `totalAmount` | `number` | Amount in cents for PayPal / wallet config |
-| `currency` | `string` | Currency code for PayPal / wallet config (default: `'usd'`) |
-| `submitLabel` | `(string \| null)?` | Final, already-localized wording for the hosted card button (e.g. `'Pay $10'`). Updates live without remounting the card form; omitted, cleared, `null`, or blank shows the hosted default `CONFIRM PAYMENT`. See [Hosted card submit label](#hosted-card-submit-label). |
-| `onFirstNameChange` | `(value: string) => void` | First name change callback |
-| `onLastNameChange` | `(value: string) => void` | Last name change callback |
-| `onBuyerIdentityReady` | `(identity) => MaybePromise<void>?` | Called once checkout has collected a missing buyer email (or a wallet / PayPal approval supplied one) on a still-anonymous session. `FloPayCheckout` wires its late-buyer `PATCH /claim` here — including for custom-layout children, via `CheckoutContext`. A standalone form around a `session` with `buyerIdentified: false` that is given neither a prop nor a context claim builds its own from `sessionId` + `nonce`, so the hosted vault charge is never submitted against an unbound buyer. Supply the prop to take the claim over yourself. |
-| `onComplete` / `onDecline` / `onError` | callbacks | Observable checkout outcomes. |
-#### Deferred-vault rollout boundary
-SDK `1.4.9` is the compatibility boundary for omitting embedded capture
-credentials. Keep the backend's current
-`link session → capture → complete idempotency → 201` ordering for requests
-from older or unknown SDK versions, and until the deployed `@flopay/react`
-population has crossed the adoption threshold chosen by the backend rollout.
-The SDK advertises its version in `x-flo-sdk-version` on session create/read.
-After that threshold, the backend may omit capture credentials from
-create/read/idempotent-replay responses for requests advertising SDK `>=1.4.9`,
-provided the session explicitly includes `card` in
-`gateways.stripe.enabledPaymentMethods` and the nonce-protected
-`POST /v1/checkouts/sessions/{id}/vault/capture` route remains available.
-Backend rollout verification should confirm that create/read/replay no longer
-invoke PCIVault and that capture issuance occurs only through the deferred
-endpoint when a buyer enters the card path.
+| `sessionId` / `nonce` | `string` | Checkout session and its token |
+| `billingApiUrl` | `string` | Billing API base URL |
+| `clientId` | `string` | PayPal client id (`gateways.paypal.publishableKey`) |
+| `environment` | `GatewayEnvironment?` | `sandbox` or `live` |
+| `currency` | `string` | ISO 4217 currency code |
+| `isSubscription` | `boolean` | Fallback flow selection when the session advertises no `providerObjectType` |
+| `approvalPresentation` | `PayPalApprovalPresentation?` | Billing-API-advertised approval mode |
+| `session` | `CheckoutSession \| null` | Backing session; its advertised values are authoritative |
+| `onComplete` / `onDecline` | callbacks | Payment outcomes |
+| `onTechnicalFailure` | callback | Post-click technical failures, including `popupBlocked` |
 ### Types
 | Type | Description |
 |------|-------------|
+| `FloPayCheckoutProps` | Props for `FloPayCheckout` |
 | `FloPayProviderProps` | Props for `FloPayProvider` |
 | `FloPayCardSetupProps` | Props for `FloPayCardSetup` |
-| `FloPayCardSetupCompleteEvent` | Verified setup completion with optional display-only `paymentMethod` |
-| `FloPayCardSetupDeclineEvent` | Terminal card-verification decline |
-| `FloPayCardSetupCancelEvent` | Unmount-before-terminal cancellation |
-| `FloPayCardSetupError` | Structured setup failure with stable `code` and `retryable` classification |
+| `FloPayCardSetupCompleteEvent` | Verified setup: `status`, `sessionId`, and optional display-only `paymentMethod` |
+| `FloPayCardSetupDeclineEvent` | Declined setup: `status`, `sessionId`, `reason?`, `message?` |
+| `FloPayCardSetupCancelEvent` | Unmounted before a terminal outcome: `status`, `sessionId` |
+| `FloPayAutomaticPaymentButtonProps` | Props for `FloPayAutomaticPaymentButton` |
+| `FloPayAutomaticPaymentSuccessEvent` | `result`, `session`, `sessionId`, and `autoCompleted` |
 | `SplitCardFormProps` | Props for `SplitCardForm` |
-| `CheckoutState` | `{ session, loading, error, claimPending }` |
-| `FloInstrumentEvent` | Versioned merchant instrument union with seven lifecycle names, four `checkout_error` phases, and an optional gateway. |
+| `DirectPayPalButtonProps` | Props for `DirectPayPalButton` |
+| `VaultCardFieldsProps` | Props for `VaultCardFields` |
+| `CheckoutState` | `session`, `loading`, `error`, `claimPending?` |
+| `DeclineEvent` | `method`, `message`, `code?`, `declineCode?` |
+| `BeforeButtonClickEvent` | `method`, `sessionId?`, `createSession?` |
+| `CheckoutButtonMethod` | The payment method a button represents |
+| `InlineSessionDraft` | Draft accepted by `FloPayCheckoutProps.createSession` |
+| `InlineSessionPatch` | Partial draft returned from `FloPayCheckoutProps.onBeforeButtonClick` |
+| `FloInstrumentEvent` | Versioned merchant instrument union |
+## Errors
+Checkout errors reach `onError` (and the `error` render prop) as `FloPayError` values from `@flopay/shared`. Branch on `type` and `code`; raw provider messages are never shown to buyers or passed to callbacks. Declines are not errors: they reach `onDecline` with a `DeclineEvent`.
+| Code | Type | When |
+|------|------|------|
+| `checkout_session_expired` | `api_error` | `FloPayCheckout` or `FloPayAutomaticPaymentButton` loaded an expired session. Create a fresh session and send the buyer back through checkout. |
+| `CurrencyRequired` | `validation_error` | `createSession` has no resolvable currency. Thrown before any request. |
+| `InvalidIdempotencyKey` | `validation_error` | `createSession.idempotencyKey` is blank or longer than 255 characters. |
+| `CaptureMethodUnsupportedForSubscription` | `validation_error` | Manual capture was requested for a cart with a subscription. |
+| `BuyerEmailCollectionRequired` | `validation_error` | A buyer email supplied to the checkout is not a valid email address. |
+| `UnsupportedBackendVaultCapability` | `api_error` | The session offers no hosted card form or card capability and no other usable payment method. |
+| `CheckoutInitializationFailed` | `api_error` | Neither the hosted card form nor Direct PayPal could render after Stripe.js failed to initialize. |
+| `paypal_init_timeout` | `api_error` | A PayPal-only checkout could not start PayPal after automatic recovery. The **Retry PayPal** button tries again. |
+| `external_payment_method_failed` | `api_error` | A wallet, PayPal, or alternative method failed technically after the buyer clicked it. The chooser offers a retry. |
+| `InvalidCardSetupSurface` | `validation_error` | `FloPayCheckout` was given a card-setup session; use `FloPayCardSetup`. |
+| `three_ds_aborted` / `three_ds_timeout` | `api_error` | The buyer cancelled, or did not finish, the authentication challenge for a saved card in confirm or auto mode. |
+| `InvalidPaymentProcessResponse` | `api_error` | Saved-payment processing returned a response the SDK could not use. |
+A `validation_error` is also reported when both `showStripe` and `showPayPal` are false with no PayPal gateway, or when a session advertises no supported gateway. When saving the AVS billing address is rejected with a `4xx`, `onError` receives the parsed billing API error while the message shows inline; the buyer corrects it for the next attempt.
+`FloPayCardSetup` reports failures to `onError` as `FloPayCardSetupError`, which adds `retryable`. Network, rate-limit, `5xx`, card-form timeout, and unexpected failures are retryable; validation failures are not.
+| Code | When |
+|------|------|
+| `MissingCheckoutSessionId` | Rendered without `sessionId` |
+| `MissingCheckoutSessionToken` | Rendered without `nonce` |
+| `InvalidCardSetupSession` | The session is not a zero-amount, product-free setup session |
+| `UnsupportedBackendVaultCapability` | The setup session has no hosted card capability |
+| `card_setup_widget_failed` | The hosted card form failed at runtime (retryable) |
+| `card_setup_load_failed` | Loading the session or card form failed for another reason |