@flopay/react 1.6.0 → 1.7.0

package/dist/index.d.cts

@@ -1,63 +1,257 @@
-import React from 'react';
-import { FloPay, FloPayElements } from '@flopay/js';
 import * as _flopay_shared from '@flopay/shared';
-import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, PayPalProviderObjectType, CardCaptureAdapter, VaultCardThemeColors, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
-export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch, SentryEventLike, SentryStackFrameLike, dropThirdPartyOnlyError } from '@flopay/shared';
+import { InlineSessionDraft, CheckoutButtonMethod, CheckoutProduct, CheckoutItem, CheckoutSubscription, ThemeId, FloPayAppearance, ButtonsLayoutTheme, ButtonsLayoutStyles, PaymentResult, CheckoutSession, FloPayError, DeclineEvent, GatewayEnvironment, PayPalProviderObjectType, TokenizedBody, InlineSessionPatch, ElementOptions, ElementChangeEvent, FloInstrumentEvent, BeforeButtonClickEvent, CheckoutMode, AVSFieldConfig, CardCaptureAdapter, VaultCardThemeColors } from '@flopay/shared';
+export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, FloInstrumentEvent, InlineSessionDraft, InlineSessionPatch, SentryEventLike, SentryStackFrameLike, dropThirdPartyOnlyError } from '@flopay/shared';
+import React from 'react';
 export { FloPayCardSetup, FloPayCardSetupCancelEvent, FloPayCardSetupCompleteEvent, FloPayCardSetupDeclineEvent, FloPayCardSetupError, FloPayCardSetupProps } from './card-setup-entry.cjs';
+import { FloPayElements, FloPay } from '@flopay/js';
 
-/** Props for the `FloPayProvider` component. */
-interface FloPayProviderProps {
-    /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
-    flopay: Promise<FloPay> | FloPay;
+interface FloPayAutomaticPaymentSuccessEvent {
+    result: PaymentResult;
+    session: CheckoutSession | null;
+    sessionId: string | null;
+    autoCompleted: boolean;
+}
+interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onError'> {
+    sessionId?: string;
     /**
-     * Optional Stripe `FloPay` instance used to drive the Stripe-rendered PayPal
-     * fallback. When omitted or `null`, the Stripe-rendered PayPal button is
-     * not rendered. Direct PayPal (`gateways.paypal`) does not use this prop.
+     * Session-bound checkout token for a consumer-supplied {@link sessionId}
+     * (the `nonce` returned when that session was created). Post-#640 backends
+     * require it as `x-checkout-session-token` to read the session and to
+     * `/process` it; without it the existing-session path 401s with
+     * "Missing checkout session token.". Ignored on the create-session path,
+     * where the SDK mints and threads the nonce itself.
      */
-    paypalFlopay?: Promise<FloPay> | FloPay | null;
-    /** Optional configuration applied when creating the elements group. */
-    options?: {
-        locale?: string;
-        appearance?: FloPayAppearance;
-        /**
-         * Client secret for an existing non-card PaymentIntent or SetupIntent.
-         * The SDK verifies the provider intent against the `PaymentElement`'s
-         * explicit `paymentMethodTypes` allowlist before mounting and rejects card
-         * or undeclared methods. Card checkout uses the hosted vault.
-         */
-        clientSecret?: string;
-        /** Total amount in cents for deferred non-card Elements without a client secret. */
-        amount?: number;
-        /** ISO 4217 currency code for deferred non-card Elements without a client secret. */
-        currency?: string;
-        /** How non-card payment methods are created: `'manual'` or `'auto'` (needed for PayPal). */
-        paymentMethodCreation?: 'manual' | 'auto';
-        /** Requests reusable payment credentials for future payments. */
-        setupFutureUsage?: 'off_session' | 'on_session';
-        /** Billing API base URL. Set once here so child components don't need to repeat it. */
-        billingApiUrl?: string;
+    nonce?: string;
+    createSession?: InlineSessionDraft;
+    /**
+     * @deprecated Ignored. The backend now picks the customer's most recent
+     * vaulted payment method via `getLatestByUserId` and rebinds the session's
+     * gateway to match it (see `apps/api`'s `createSingle` auto-checkout
+     * branch). Passing this prop has no effect — it is retained only to avoid
+     * breaking existing integrations.
+     */
+    paymentMethodId?: string;
+    /**
+     * @deprecated Ignored. The backend orchestrates gateway routing — clients
+     * no longer choose between card and PayPal at the SDK boundary. Passing
+     * this prop has no effect.
+     */
+    checkoutMethod?: CheckoutButtonMethod;
+    clientId?: string;
+    /**
+     * Unified products array (TeamFloPay/backend#760). When supplied,
+     * `items`/`subscriptions` are ignored. The SDK folds the legacy fields
+     * into this shape internally.
+     */
+    products?: CheckoutProduct[];
+    items?: CheckoutItem[];
+    subscriptions?: CheckoutSubscription[];
+    account?: InlineSessionDraft['account'];
+    successUrl?: string;
+    cancelUrl?: string;
+    couponCodes?: string[];
+    tagsData?: InlineSessionDraft['tagsData'];
+    utmMetadata?: InlineSessionDraft['utmMetadata'];
+    billingApiUrl?: string;
+    locale?: string;
+    /**
+     * High-level theme bundle that styles the button (and the fallback
+     * `FloPayCheckout` modal that opens when the saved-payment charge needs
+     * user interaction). One of: `'classic'`, `'modern-light'`, `'modern-dark'`,
+     * `'bold-light'`, `'bold-dark'`, `'glass-light'`, `'glass-dark'`. Explicit
+     * `buttonsStyles` still wins for fine-grained overrides.
+     */
+    theme?: ThemeId;
+    /**
+     * Per-checkout appearance overrides layered on top of the chosen `theme`
+     * (same shape as {@link FloPayCheckout}'s `appearance`). Its `colorPrimary` /
+     * `colorPrimaryHover` / `borderRadius` re-skin the button — and the fallback
+     * `FloPayCheckout` modal — so the auto-pay button matches the rest of the
+     * themed checkout. Without this the button only saw the bundle's defaults.
+     */
+    appearance?: FloPayAppearance;
+    /**
+     * @deprecated Use `theme` instead. Legacy buttons-layout preset
+     * (`'default' | 'minimal' | 'rounded' | 'dark'`). Still honored for
+     * back-compat.
+     */
+    buttonsTheme?: ButtonsLayoutTheme;
+    buttonsStyles?: ButtonsLayoutStyles;
+    onSuccess?: (event: FloPayAutomaticPaymentSuccessEvent) => void;
+    onError?: (error: FloPayError) => void;
+    onDecline?: (decline: DeclineEvent) => void;
+    children?: React.ReactNode;
+}
+declare function FloPayAutomaticPaymentButton({ sessionId, nonce, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, products, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, appearance, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): React.JSX.Element;
+
+/**
+ * Overrides that `SplitCardForm`'s tokenized-body dispatcher uses to apply a
+ * `runBeforeButtonClick` patch to the in-flight processPayment call. Kept in
+ * sync structurally with `TokenizedBodyOverrides` in `split-card-form.tsx`.
+ */
+interface DirectPayPalTokenizedOverrides {
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+    nonce?: string;
+}
+/**
+ * Internal handler signature aligned with `SplitCardForm`'s tokenized-body
+ * dispatcher. Direct PayPal completes via the backend's process endpoint and
+ * never produces a Stripe PaymentIntent, so we still forward a synthetic
+ * `TokenizedBody` describing the captured order, optionally with the
+ * session/account patch captured at click-time.
+ */
+type DirectPayPalTokenizedHandler = (body: TokenizedBody, overrides?: DirectPayPalTokenizedOverrides) => void;
+/** Click-time `runBeforeButtonClick` result, structurally compatible with `SplitCardForm`. */
+interface DirectPayPalBeforeButtonClickResult {
+    proceed: boolean;
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+    nonce?: string;
+}
+/**
+ * Click-time gate. Mirrors `RunBeforeButtonClick` in `SplitCardForm`: lets the
+ * consumer patch the session/account before PayPal creates the order, and lets
+ * them abort the click entirely by returning `proceed: false`.
+ */
+type DirectPayPalRunBeforeButtonClick = (method: CheckoutButtonMethod) => Promise<DirectPayPalBeforeButtonClickResult>;
+type DirectPayPalInitializationState = 'loading' | 'retrying' | 'ready' | 'exhausted';
+type DirectPayPalTechnicalFailureHandler = (method: 'paypal', err: unknown, options?: {
+    code?: string;
+    popupBlocked?: boolean;
+}) => void;
+interface DirectPayPalButtonProps {
+    /** Checkout session ID. */
+    sessionId: string;
+    /**
+     * Session-bound checkout token returned by session creation. Forwarded as
+     * `x-checkout-session-token` on every continuation request — required by
+     * post-#640 backends. `FloPayCheckout` plumbs this prop automatically.
+     */
+    nonce?: string;
+    /** Billing API base URL. */
+    billingApiUrl: string;
+    /** Buyer email. */
+    email?: string;
+    /** PayPal client identifier (`gateways.paypal.publishableKey`). */
+    clientId: string;
+    /** Gateway environment, drives the sandbox/live SDK script. */
+    environment?: GatewayEnvironment;
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Whether the session is a subscription (drives intent + flow selection). */
+    isSubscription: boolean;
+    /**
+     * Provider object the backend advertised for this PayPal continuation.
+     * When omitted, legacy sessions continue to derive the flow from
+     * `isSubscription`. An advertised `'order'`/`'setup_token'` opts intent and
+     * process requests into the Flo-owned `paypal_vaulted` payment-method
+     * channel; an advertised `'subscription'` or an omission keeps the released
+     * `paypal` requests byte-identical.
+     */
+    providerObjectType?: PayPalProviderObjectType;
+    /**
+     * If provided, called with the tokenized body once PayPal capture
+     * completes. When omitted, the component processes payment internally.
+     */
+    onTokenizedBody?: DirectPayPalTokenizedHandler;
+    /** Called when the full self-contained payment flow succeeds. */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when an error occurs. */
+    onErrorChange?: (error: string | null) => void;
+    /** Decline emitter (mirrors SplitCardForm semantics). */
+    onDecline?: (decline: DeclineEvent) => void;
+    /** Called for post-click technical failures before PayPal authorization completes. */
+    onTechnicalFailure?: DirectPayPalTechnicalFailureHandler;
+    /** External processing state. */
+    isProcessing?: boolean;
+    /** Notify the parent of the loading state for placeholder swapping. */
+    onLoadStateChange?: (ready: boolean) => void;
+    /** Notify a PayPal-only wrapper about pre-render recovery state. */
+    onInitializationStateChange?: (state: DirectPayPalInitializationState) => void;
+    /** Disable the automatic retry for a buyer-initiated single manual attempt. */
+    allowAutomaticRetry?: boolean;
+    /** Tracks button-click for analytics. */
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Click-time gate (runs before PayPal creates the order). When provided, the
+     * returned patch is applied to the in-flight create-intent and tokenized
+     * dispatch so callers using `onBeforeButtonClick` see the same session/email
+     * the Stripe-rendered PayPal flow does.
+     */
+    runBeforeButtonClick?: DirectPayPalRunBeforeButtonClick;
+    /** Backing session — used for self-contained accountData population. */
+    session?: CheckoutSession | null;
+    /**
+     * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
+     * true) to bind the button to. When set, the button skips its usual
+     * session-scoped create-intent round-trip on click and feeds this
+     * id straight into PayPal's create-order / create-subscription callback.
+     *
+     * Used by `SplitCardForm`'s `paypal_direct_required` retry path: backend
+     * creates a fresh PayPal order after a stalled process attempt and returns
+     * its id; the SDK re-renders this button bound to that id so the buyer can
+     * confirm with one more click without the backend re-creating the order on
+     * each retry.
+     *
+     * Changing this value remounts the PayPal SDK so the new createOrder
+     * binding takes effect (PayPal's render() options aren't live-updatable).
+     */
+    existingOrderId?: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set `false` to opt out. */
+    telemetry?: boolean;
+    /**
+     * When true, renders an on-screen lifecycle tracer panel above the button
+     * (mount, loadScript, eligibility, render, errors). Intended for debugging
+     * in-app browsers (Facebook IAB, etc.) where remote console access is
+     * impractical. Off by default — leave disabled in production.
+     */
+    debug?: boolean;
+}
+/** Public direct-PayPal surface: telemetry accepts only the boolean opt-out. */
+declare function DirectPayPalButton(props: DirectPayPalButtonProps): React.ReactElement | null;
+
+/** Common props shared by all element components. */
+interface ElementComponentProps {
+    /** Additional CSS class for the wrapper div. */
+    className?: string;
+    /** Element id attribute for the wrapper div. */
+    id?: string;
+    /** Inline styles for the wrapper div. */
+    style?: React.CSSProperties;
+    /** Options forwarded to the underlying element. */
+    options?: Partial<ElementOptions>;
+    /** Fired when the element's value changes. */
+    onChange?: (event: ElementChangeEvent) => void;
+    /** Fired when the element is fully rendered and ready. */
+    onReady?: () => void;
+    /** Fired when the element gains focus. */
+    onFocus?: () => void;
+    /** Fired when the element loses focus. */
+    onBlur?: () => void;
+    /** Fired when the Escape key is pressed inside the element. */
+    onEscape?: () => void;
+}
+/** Props for the standalone non-card Payment Element. */
+interface PaymentElementProps extends Omit<ElementComponentProps, 'options'> {
+    /**
+     * Element options with an explicit wallet/APM allowlist. `card` is removed
+     * at runtime; an empty result is rejected before the provider is called.
+     */
+    options: Omit<Partial<ElementOptions>, 'paymentMethodTypes'> & {
+        paymentMethodTypes: readonly string[];
     };
-    children: React.ReactNode;
 }
 /**
- * Provides FloPay SDK context to the component tree.
- *
- * Wrap provider-context elements with this provider:
- *
- * ```tsx
- * <FloPayProvider flopay={loadFloPay('pk_test_...')}>
- *   <PaymentElement options={{ paymentMethodTypes: ['cashapp', 'ideal'] }} />
- * </FloPayProvider>
- * ```
- *
- * `FloPayCheckout` is a standalone integration that owns its provider and
- * session-specific Elements setup:
- *
- * ```tsx
- * <FloPayCheckout sessionId="sess_..." />
- * ```
+ * Renders a provider Payment Element restricted to the declared non-card
+ * wallet/APM methods. Card collection is available only through the hosted
+ * vault checkout surfaces.
+ */
+declare const PaymentElement: React.FC<PaymentElementProps>;
+/**
+ * Renders an address input element.
  */
-declare function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPayProp, options, children, }: FloPayProviderProps): React.ReactElement;
+declare const AddressElement: React.FC<ElementComponentProps>;
 
 /** Props for the all-in-one `FloPayCheckout` wrapper. */
 interface FloPayCheckoutProps {
@@ -94,6 +288,8 @@ interface FloPayCheckoutProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Receives the versioned, privacy-safe checkout instrument feed. */
+    onInstrument?: (event: FloInstrumentEvent) => void;
     /** Called when a payment is declined or the authentication step fails. */
     onDecline?: (decline: DeclineEvent) => void;
     /** Called when the AVS country dropdown changes. */
@@ -189,7 +385,7 @@ interface FloPayCheckoutProps {
      * In `layout="buttons"` with `createSession`, the returned patch is merged
      * into the inline session params before the selected flow continues.
      */
-    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => void | false | Promise<void | false | InlineSessionPatch> | InlineSessionPatch;
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => undefined | false | Promise<undefined | false | InlineSessionPatch> | InlineSessionPatch;
     /**
      * Enable AVS (Address Verification).
      * - `true` — show country + postal code (backward compatible default)
@@ -261,7 +457,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, telemetry, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onCountryChange, onZipChange, showPayPal, showStripe, enabledPaymentMethods: enabledPaymentMethodsProp, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, cardFieldOrder, cardPreFormSlot, avsLayout, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, telemetry, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onInstrument, onDecline, onCountryChange, onZipChange, showPayPal, showStripe, enabledPaymentMethods: enabledPaymentMethodsProp, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, cardFieldOrder, cardPreFormSlot, avsLayout, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -300,47 +496,121 @@ interface CheckoutState {
  */
 declare function useCheckout(): CheckoutState;
 
-/** Common props shared by all element components. */
-interface ElementComponentProps {
-    /** Additional CSS class for the wrapper div. */
-    className?: string;
-    /** Element id attribute for the wrapper div. */
-    id?: string;
-    /** Inline styles for the wrapper div. */
-    style?: React.CSSProperties;
-    /** Options forwarded to the underlying element. */
-    options?: Partial<ElementOptions>;
-    /** Fired when the element's value changes. */
-    onChange?: (event: ElementChangeEvent) => void;
-    /** Fired when the element is fully rendered and ready. */
-    onReady?: () => void;
-    /** Fired when the element gains focus. */
-    onFocus?: () => void;
-    /** Fired when the element loses focus. */
-    onBlur?: () => void;
-    /** Fired when the Escape key is pressed inside the element. */
-    onEscape?: () => void;
-}
-/** Props for the standalone non-card Payment Element. */
-interface PaymentElementProps extends Omit<ElementComponentProps, 'options'> {
+/**
+ * Props for the `PayPalButton` component.
+ *
+ * Must be rendered inside its own `FloPayProvider` with `paymentMethodCreation: undefined`
+ * (not 'manual') because this PayPal flow needs automatic payment-method creation.
+ */
+interface PayPalButtonProps {
+    /** The checkout session ID (UUID from billing API). */
+    sessionId: string;
     /**
-     * Element options with an explicit wallet/APM allowlist. `card` is removed
-     * at runtime; an empty result is rejected before the provider is called.
+     * Session-bound checkout token returned by session creation. Forwarded as
+     * `x-checkout-session-token` on continuation requests — required by
+     * post-#640 backends.
      */
-    options: Omit<Partial<ElementOptions>, 'paymentMethodTypes'> & {
-        paymentMethodTypes: readonly string[];
-    };
+    nonce?: string;
+    /** Billing API base URL. Optional — defaults to the value from FloPayProvider or the shared constant. */
+    billingApiUrl?: string;
+    /** User's email. */
+    email?: string;
+    /** User ID for processing payments. */
+    userId?: string;
+    /** First name for billing. */
+    firstName?: string;
+    /** Last name for billing. */
+    lastName?: string;
+    /** Checkout version for tracking. */
+    chv?: string;
+    /**
+     * Called with tokenized data after PayPal authorization.
+     * If omitted, the component calls processPayment internally.
+     */
+    onTokenizedBody?: (body: TokenizedBody) => void;
+    /** Called on successful payment (self-contained mode). */
+    onComplete?: () => void;
+    /** Called when an error occurs. */
+    onErrorChange?: (error: string | null) => void;
+    /** External processing state. */
+    isProcessing?: boolean;
 }
 /**
- * Renders a provider Payment Element restricted to the declared non-card
- * wallet/APM methods. Card collection is available only through the hosted
- * vault checkout surfaces.
+ * PayPal button that handles the full PayPal payment flow.
+ *
+ * **Important**: PayPal requires its own `FloPayProvider` with automatic
+ * payment-method creation. Keep it separate from manually created wallet/APM
+ * Elements groups.
+ *
+ * ```tsx
+ * {/* Main checkout provider *\/}
+ * <FloPayProvider flopay={flopay} options={{ amount, currency }}>
+ *   <SplitCardForm ... />
+ * </FloPayProvider>
+ *
+ * {/* PayPal provider (no paymentMethodCreation) *\/}
+ * <FloPayProvider flopay={flopay} options={{ amount, currency, paymentMethodCreation: 'auto' }}>
+ *   <PayPalButton ... />
+ * </FloPayProvider>
+ * ```
  */
-declare const PaymentElement: React.FC<PaymentElementProps>;
+declare function PayPalButton({ sessionId, nonce, billingApiUrl, email, userId, firstName, lastName, chv, onTokenizedBody, onComplete, onErrorChange, isProcessing, }: PayPalButtonProps): React.ReactElement;
+
+/** Props for the `FloPayProvider` component. */
+interface FloPayProviderProps {
+    /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
+    flopay: Promise<FloPay> | FloPay;
+    /**
+     * Optional Stripe `FloPay` instance used to drive the Stripe-rendered PayPal
+     * fallback. When omitted or `null`, the Stripe-rendered PayPal button is
+     * not rendered. Direct PayPal (`gateways.paypal`) does not use this prop.
+     */
+    paypalFlopay?: Promise<FloPay> | FloPay | null;
+    /** Optional configuration applied when creating the elements group. */
+    options?: {
+        locale?: string;
+        appearance?: FloPayAppearance;
+        /**
+         * Client secret for an existing non-card PaymentIntent or SetupIntent.
+         * The SDK verifies the provider intent against the `PaymentElement`'s
+         * explicit `paymentMethodTypes` allowlist before mounting and rejects card
+         * or undeclared methods. Card checkout uses the hosted vault.
+         */
+        clientSecret?: string;
+        /** Total amount in cents for deferred non-card Elements without a client secret. */
+        amount?: number;
+        /** ISO 4217 currency code for deferred non-card Elements without a client secret. */
+        currency?: string;
+        /** How non-card payment methods are created: `'manual'` or `'auto'` (needed for PayPal). */
+        paymentMethodCreation?: 'manual' | 'auto';
+        /** Requests reusable payment credentials for future payments. */
+        setupFutureUsage?: 'off_session' | 'on_session';
+        /** Billing API base URL. Set once here so child components don't need to repeat it. */
+        billingApiUrl?: string;
+    };
+    /** Receives the versioned, privacy-safe checkout instrument feed. */
+    onInstrument?: (event: FloInstrumentEvent) => void;
+    children: React.ReactNode;
+}
 /**
- * Renders an address input element.
+ * Provides FloPay SDK context to the component tree.
+ *
+ * Wrap provider-context elements with this provider:
+ *
+ * ```tsx
+ * <FloPayProvider flopay={loadFloPay('pk_test_...')}>
+ *   <PaymentElement options={{ paymentMethodTypes: ['cashapp', 'ideal'] }} />
+ * </FloPayProvider>
+ * ```
+ *
+ * `FloPayCheckout` is a standalone integration that owns its provider and
+ * session-specific Elements setup:
+ *
+ * ```tsx
+ * <FloPayCheckout sessionId="sess_..." />
+ * ```
  */
-declare const AddressElement: React.FC<ElementComponentProps>;
+declare function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPayProp, options, onInstrument, children, }: FloPayProviderProps): React.ReactElement;
 
 type MaybePromise<T> = T | Promise<T>;
 
@@ -487,425 +757,159 @@ interface SplitCardFormProps {
      */
     onButtonClick?: (method: CheckoutButtonMethod) => void;
     /**
-     * Called before a payment button continues in `layout="buttons"`.
-     * Runs for card, PayPal, Apple Pay, and Google Pay.
-     */
-    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => MaybePromise<void | false | InlineSessionPatch>;
-    /**
-     * Enable AVS (Address Verification).
-     * - `true` — show country + postal code (backward compatible default)
-     * - `AVSFieldConfig` — granular per-field control, optionally scoped to country codes
-     * - `false` / omitted — AVS disabled
-     */
-    enableAVS?: boolean | AVSFieldConfig;
-    /**
-     * Per-merchant order of the hosted vault card rows — a permutation of
-     * `['name','number','expiry']` (`'expiry'` is the combined expiry+CVV row;
-     * the submit button stays last). Drives both the visual order and the tab
-     * order inside the widget. Omit for the default (`name`, `number`, `expiry`).
-     * Only applies on the vault card path.
-     */
-    cardFieldOrder?: _flopay_shared.VaultCardFieldKey[];
-    /** Content rendered above the hosted vault card widget (below the wallet divider). */
-    cardPreFormSlot?: React.ReactNode;
-    /** Layout for AVS fields: 'row' (side-by-side, default) or 'column' (stacked). */
-    avsLayout?: 'row' | 'column';
-    /** Pre-filled country code (ISO 3166-1 alpha-2) for AVS. */
-    country?: string;
-    /** Pre-filled ZIP/postal code for AVS. */
-    zip?: string;
-    /** Pre-filled street address (line 1) for AVS. Typically from a partner GeoIP / profile lookup. */
-    addressLine1?: string;
-    /** Pre-filled apt/suite/unit (line 2) for AVS. */
-    addressLine2?: string;
-    /** Pre-filled city for AVS. Typically from a partner GeoIP / profile lookup. */
-    city?: string;
-    /** Pre-filled state/province for AVS. Typically from a partner GeoIP / profile lookup. */
-    state?: string;
-    /** Callback when AVS country changes. */
-    onCountryChange?: (country: string) => void;
-    /** Callback when AVS ZIP/postal code changes. */
-    onZipChange?: (zip: string) => void;
-    /** Whether AVS was enabled (sent to backend for analytics). */
-    avsCheck?: boolean;
-    /** Checkout type: 'standard_checkout' or 'embedded_checkout'. */
-    checkoutType?: string;
-    /** Checkout layout: 'default_layout', 'buttons_layout', or 'custom_layout'. */
-    checkoutLayout?: string;
-    /** Total amount in cents (smallest currency unit). Used for wallet/PayPal Elements config. */
-    totalAmount?: number;
-    /** Currency code (used for PayPal Elements config). */
-    currency?: string;
-    /** Render the card form expanded on first paint when `layout="buttons"`. */
-    initialCardOpen?: boolean;
-    /**
-     * Direct PayPal gateway configuration. When provided, PayPal renders via
-     * the official PayPal JS SDK (in-app browser compliant) instead of via
-     * Stripe's ExpressCheckoutElement. Selection is mutually exclusive:
-     * setting this disables the Stripe-rendered PayPal path automatically.
-     */
-    directPaypal?: {
-        clientId: string;
-        environment?: GatewayEnvironment;
-        providerObjectType?: PayPalProviderObjectType;
-    };
-    /** Whether the active session represents a subscription (drives direct PayPal intent). */
-    isSubscription?: boolean;
-    /** Backing session — forwarded to direct-PayPal so it can populate accountData. */
-    session?: CheckoutSession | null;
-    /**
-     * True while a **detached** session's background claim is still in flight
-     * (TeamFloPay/backend#1099).
-     *
-     * The hosted card widget is already mounted and the buyer can fill it in, but
-     * the session has no cart attached yet, so nothing may be submitted: the
-     * billing API rejects process / intent calls on an unclaimed session with
-     * `409 checkout_session_data_attachment_required`, and holds an unclaimed
-     * vault charge with a retryable `503`. While true, the card submit is gated
-     * and the non-card surfaces stay hidden; all of them enable together the
-     * moment the claim lands. `FloPayCheckout` plumbs this prop automatically.
-     */
-    dataAttachmentPending?: boolean;
-    /**
-     * Enables on-screen diagnostic panels for the PayPal/wallet gating decision
-     * and the `DirectPayPalButton` lifecycle. Intended for debugging in-app
-     * browsers where remote console access is impractical. Off by default.
-     */
-    debug?: boolean;
-}
-/**
- * Checkout surface combining hosted vault card capture with wallets, APMs,
- * and PayPal. Card entry is hosted-vault-only.
- *
- * Stripe-hosted PayPal uses its own Elements instance; direct PayPal uses the
- * official PayPal SDK when the session advertises that gateway.
- */
-declare function SplitCardForm(props: SplitCardFormProps): React.JSX.Element;
-
-/** Props for {@link VaultCardFields}. */
-interface VaultCardFieldsProps {
-    /**
-     * The card-capture adapter (typically `useFloPay().cardCapture()`). Owns
-     * injecting + bootstrapping the hosted vault widget. Changing this instance
-     * (or {@link VaultCardFieldsProps.html}) remounts the widget.
-     */
-    capture: CardCaptureAdapter;
-    /**
-     * Server-rendered hosted vault widget HTML (the session's
-     * {@link CheckoutSession.vault} block `html`, or one fetched from
-     * `POST /vault/capture`). The widget owns the card fields, submit button,
-     * tokenization, charge, and 3DS; this component only injects it.
-     */
-    html: string;
-    /**
-     * Per-session integrity token (the vault block's `messageToken`). Forwarded
-     * to the adapter so it can reject forged terminal `postMessage` outcomes that
-     * omit/mismatch it. Omitted when the backend does not (yet) mint one.
-     */
-    messageToken?: string;
-    /**
-     * Exact origin expected for the widget's terminal `postMessage` outcomes
-     * (the vault block's `expectedOrigin`). Forwarded to the adapter's origin
-     * gate; omitted to skip it.
-     */
-    expectedOrigin?: string;
-    /**
-     * Merchant theme colors pushed into the hosted widget so the card form
-     * matches the surrounding checkout. Applied live on change (no remount).
-     */
-    theme?: VaultCardThemeColors;
-    /** Inline styles for the container the widget mounts into. */
-    containerStyle?: React.CSSProperties;
-    /** Fired once the widget is injected and bootstrapping. */
-    onReady?: () => void;
-    /**
-     * Fired with a load/runtime error message from the widget, or `null` when it
-     * clears. Wired to the card form's shared error banner. Terminal payment
-     * outcomes (`complete` / `decline`) are observed by the parent form directly
-     * off the same adapter and are not surfaced here.
-     */
-    onError?: (message: string | null) => void;
-    /**
-     * Fired with the widget's inline field-validation message (live, debounced by
-     * the widget to changes), or `null` when validation clears. Surfaced in the
-     * card form's error banner and the merchant `onError`.
-     */
-    onValidation?: (message: string | null) => void;
-}
-/**
- * Renders the backend-served vault PCI card widget
- * (TeamFloPay/backend#823, Model A). The hosted widget
- * is a self-contained form: PAN / CVC, the submit button, the charge, and 3DS
- * all live inside it. This component only injects the widget HTML through the
- * {@link CardCaptureAdapter} and bridges its `ready` / `error` lifecycle events
- * back to the surrounding card form.
- */
-declare function VaultCardFields({ capture, html, messageToken, expectedOrigin, theme, containerStyle, onReady, onError, onValidation, }: VaultCardFieldsProps): React.ReactElement;
-
-/**
- * Props for the `PayPalButton` component.
- *
- * Must be rendered inside its own `FloPayProvider` with `paymentMethodCreation: undefined`
- * (not 'manual') because this PayPal flow needs automatic payment-method creation.
- */
-interface PayPalButtonProps {
-    /** The checkout session ID (UUID from billing API). */
-    sessionId: string;
-    /**
-     * Session-bound checkout token returned by session creation. Forwarded as
-     * `x-checkout-session-token` on continuation requests — required by
-     * post-#640 backends.
-     */
-    nonce?: string;
-    /** Billing API base URL. Optional — defaults to the value from FloPayProvider or the shared constant. */
-    billingApiUrl?: string;
-    /** User's email. */
-    email?: string;
-    /** User ID for processing payments. */
-    userId?: string;
-    /** First name for billing. */
-    firstName?: string;
-    /** Last name for billing. */
-    lastName?: string;
-    /** Checkout version for tracking. */
-    chv?: string;
-    /**
-     * Called with tokenized data after PayPal authorization.
-     * If omitted, the component calls processPayment internally.
-     */
-    onTokenizedBody?: (body: TokenizedBody) => void;
-    /** Called on successful payment (self-contained mode). */
-    onComplete?: () => void;
-    /** Called when an error occurs. */
-    onErrorChange?: (error: string | null) => void;
-    /** External processing state. */
-    isProcessing?: boolean;
-}
-/**
- * PayPal button that handles the full PayPal payment flow.
- *
- * **Important**: PayPal requires its own `FloPayProvider` with automatic
- * payment-method creation. Keep it separate from manually created wallet/APM
- * Elements groups.
- *
- * ```tsx
- * {/* Main checkout provider *\/}
- * <FloPayProvider flopay={flopay} options={{ amount, currency }}>
- *   <SplitCardForm ... />
- * </FloPayProvider>
- *
- * {/* PayPal provider (no paymentMethodCreation) *\/}
- * <FloPayProvider flopay={flopay} options={{ amount, currency, paymentMethodCreation: 'auto' }}>
- *   <PayPalButton ... />
- * </FloPayProvider>
- * ```
- */
-declare function PayPalButton({ sessionId, nonce, billingApiUrl, email, userId, firstName, lastName, chv, onTokenizedBody, onComplete, onErrorChange, isProcessing, }: PayPalButtonProps): React.ReactElement;
-
-/**
- * Overrides that `SplitCardForm`'s tokenized-body dispatcher uses to apply a
- * `runBeforeButtonClick` patch to the in-flight processPayment call. Kept in
- * sync structurally with `TokenizedBodyOverrides` in `split-card-form.tsx`.
- */
-interface DirectPayPalTokenizedOverrides {
-    accountPatch?: InlineSessionPatch['account'];
-    sessionId?: string;
-    nonce?: string;
-}
-/**
- * Internal handler signature aligned with `SplitCardForm`'s tokenized-body
- * dispatcher. Direct PayPal completes via the backend's process endpoint and
- * never produces a Stripe PaymentIntent, so we still forward a synthetic
- * `TokenizedBody` describing the captured order, optionally with the
- * session/account patch captured at click-time.
- */
-type DirectPayPalTokenizedHandler = (body: TokenizedBody, overrides?: DirectPayPalTokenizedOverrides) => void;
-/** Click-time `runBeforeButtonClick` result, structurally compatible with `SplitCardForm`. */
-interface DirectPayPalBeforeButtonClickResult {
-    proceed: boolean;
-    accountPatch?: InlineSessionPatch['account'];
-    sessionId?: string;
-    nonce?: string;
-}
-/**
- * Click-time gate. Mirrors `RunBeforeButtonClick` in `SplitCardForm`: lets the
- * consumer patch the session/account before PayPal creates the order, and lets
- * them abort the click entirely by returning `proceed: false`.
- */
-type DirectPayPalRunBeforeButtonClick = (method: CheckoutButtonMethod) => Promise<DirectPayPalBeforeButtonClickResult>;
-type DirectPayPalInitializationState = 'loading' | 'retrying' | 'ready' | 'exhausted';
-type DirectPayPalTechnicalFailureHandler = (method: 'paypal', err: unknown, options?: {
-    code?: string;
-    popupBlocked?: boolean;
-}) => void;
-interface DirectPayPalButtonProps {
-    /** Checkout session ID. */
-    sessionId: string;
-    /**
-     * Session-bound checkout token returned by session creation. Forwarded as
-     * `x-checkout-session-token` on every continuation request — required by
-     * post-#640 backends. `FloPayCheckout` plumbs this prop automatically.
+     * Called before a payment button continues in `layout="buttons"`.
+     * Runs for card, PayPal, Apple Pay, and Google Pay.
      */
-    nonce?: string;
-    /** Billing API base URL. */
-    billingApiUrl: string;
-    /** Buyer email. */
-    email?: string;
-    /** PayPal client identifier (`gateways.paypal.publishableKey`). */
-    clientId: string;
-    /** Gateway environment, drives the sandbox/live SDK script. */
-    environment?: GatewayEnvironment;
-    /** ISO 4217 currency code. */
-    currency: string;
-    /** Whether the session is a subscription (drives intent + flow selection). */
-    isSubscription: boolean;
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => MaybePromise<undefined | false | InlineSessionPatch>;
     /**
-     * Provider object the backend advertised for this PayPal continuation.
-     * When omitted, legacy sessions continue to derive the flow from
-     * `isSubscription`. An advertised `'order'`/`'setup_token'` opts intent and
-     * process requests into the Flo-owned `paypal_vaulted` payment-method
-     * channel; an advertised `'subscription'` or an omission keeps the released
-     * `paypal` requests byte-identical.
+     * Enable AVS (Address Verification).
+     * - `true` — show country + postal code (backward compatible default)
+     * - `AVSFieldConfig` — granular per-field control, optionally scoped to country codes
+     * - `false` / omitted — AVS disabled
      */
-    providerObjectType?: PayPalProviderObjectType;
+    enableAVS?: boolean | AVSFieldConfig;
     /**
-     * If provided, called with the tokenized body once PayPal capture
-     * completes. When omitted, the component processes payment internally.
+     * Per-merchant order of the hosted vault card rows — a permutation of
+     * `['name','number','expiry']` (`'expiry'` is the combined expiry+CVV row;
+     * the submit button stays last). Drives both the visual order and the tab
+     * order inside the widget. Omit for the default (`name`, `number`, `expiry`).
+     * Only applies on the vault card path.
      */
-    onTokenizedBody?: DirectPayPalTokenizedHandler;
-    /** Called when the full self-contained payment flow succeeds. */
-    onComplete?: (result: PaymentResult) => void;
-    /** Called when an error occurs. */
-    onErrorChange?: (error: string | null) => void;
-    /** Decline emitter (mirrors SplitCardForm semantics). */
-    onDecline?: (decline: DeclineEvent) => void;
-    /** Called for post-click technical failures before PayPal authorization completes. */
-    onTechnicalFailure?: DirectPayPalTechnicalFailureHandler;
-    /** External processing state. */
-    isProcessing?: boolean;
-    /** Notify the parent of the loading state for placeholder swapping. */
-    onLoadStateChange?: (ready: boolean) => void;
-    /** Notify a PayPal-only wrapper about pre-render recovery state. */
-    onInitializationStateChange?: (state: DirectPayPalInitializationState) => void;
-    /** Disable the automatic retry for a buyer-initiated single manual attempt. */
-    allowAutomaticRetry?: boolean;
-    /** Tracks button-click for analytics. */
-    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    cardFieldOrder?: _flopay_shared.VaultCardFieldKey[];
+    /** Content rendered above the hosted vault card widget (below the wallet divider). */
+    cardPreFormSlot?: React.ReactNode;
+    /** Layout for AVS fields: 'row' (side-by-side, default) or 'column' (stacked). */
+    avsLayout?: 'row' | 'column';
+    /** Pre-filled country code (ISO 3166-1 alpha-2) for AVS. */
+    country?: string;
+    /** Pre-filled ZIP/postal code for AVS. */
+    zip?: string;
+    /** Pre-filled street address (line 1) for AVS. Typically from a partner GeoIP / profile lookup. */
+    addressLine1?: string;
+    /** Pre-filled apt/suite/unit (line 2) for AVS. */
+    addressLine2?: string;
+    /** Pre-filled city for AVS. Typically from a partner GeoIP / profile lookup. */
+    city?: string;
+    /** Pre-filled state/province for AVS. Typically from a partner GeoIP / profile lookup. */
+    state?: string;
+    /** Callback when AVS country changes. */
+    onCountryChange?: (country: string) => void;
+    /** Callback when AVS ZIP/postal code changes. */
+    onZipChange?: (zip: string) => void;
+    /** Whether AVS was enabled (sent to backend for analytics). */
+    avsCheck?: boolean;
+    /** Checkout type: 'standard_checkout' or 'embedded_checkout'. */
+    checkoutType?: string;
+    /** Checkout layout: 'default_layout', 'buttons_layout', or 'custom_layout'. */
+    checkoutLayout?: string;
+    /** Total amount in cents (smallest currency unit). Used for wallet/PayPal Elements config. */
+    totalAmount?: number;
+    /** Currency code (used for PayPal Elements config). */
+    currency?: string;
+    /** Render the card form expanded on first paint when `layout="buttons"`. */
+    initialCardOpen?: boolean;
     /**
-     * Click-time gate (runs before PayPal creates the order). When provided, the
-     * returned patch is applied to the in-flight create-intent and tokenized
-     * dispatch so callers using `onBeforeButtonClick` see the same session/email
-     * the Stripe-rendered PayPal flow does.
+     * Direct PayPal gateway configuration. When provided, PayPal renders via
+     * the official PayPal JS SDK (in-app browser compliant) instead of via
+     * Stripe's ExpressCheckoutElement. Selection is mutually exclusive:
+     * setting this disables the Stripe-rendered PayPal path automatically.
      */
-    runBeforeButtonClick?: DirectPayPalRunBeforeButtonClick;
-    /** Backing session — used for self-contained accountData population. */
+    directPaypal?: {
+        clientId: string;
+        environment?: GatewayEnvironment;
+        providerObjectType?: PayPalProviderObjectType;
+    };
+    /** Whether the active session represents a subscription (drives direct PayPal intent). */
+    isSubscription?: boolean;
+    /** Backing session — forwarded to direct-PayPal so it can populate accountData. */
     session?: CheckoutSession | null;
     /**
-     * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
-     * true) to bind the button to. When set, the button skips its usual
-     * session-scoped create-intent round-trip on click and feeds this
-     * id straight into PayPal's create-order / create-subscription callback.
-     *
-     * Used by `SplitCardForm`'s `paypal_direct_required` retry path: backend
-     * creates a fresh PayPal order after a stalled process attempt and returns
-     * its id; the SDK re-renders this button bound to that id so the buyer can
-     * confirm with one more click without the backend re-creating the order on
-     * each retry.
+     * True while a **detached** session's background claim is still in flight
+     * (TeamFloPay/backend#1099).
      *
-     * Changing this value remounts the PayPal SDK so the new createOrder
-     * binding takes effect (PayPal's render() options aren't live-updatable).
+     * The hosted card widget is already mounted and the buyer can fill it in, but
+     * the session has no cart attached yet, so nothing may be submitted: the
+     * billing API rejects process / intent calls on an unclaimed session with
+     * `409 checkout_session_data_attachment_required`, and holds an unclaimed
+     * vault charge with a retryable `503`. While true, the card submit is gated
+     * and the non-card surfaces stay hidden; all of them enable together the
+     * moment the claim lands. `FloPayCheckout` plumbs this prop automatically.
      */
-    existingOrderId?: string;
-    /** Flo-owned privacy-safe telemetry is enabled by default; set `false` to opt out. */
-    telemetry?: boolean;
+    dataAttachmentPending?: boolean;
     /**
-     * When true, renders an on-screen lifecycle tracer panel above the button
-     * (mount, loadScript, eligibility, render, errors). Intended for debugging
-     * in-app browsers (Facebook IAB, etc.) where remote console access is
-     * impractical. Off by default — leave disabled in production.
+     * Enables on-screen diagnostic panels for the PayPal/wallet gating decision
+     * and the `DirectPayPalButton` lifecycle. Intended for debugging in-app
+     * browsers where remote console access is impractical. Off by default.
      */
     debug?: boolean;
 }
-/** Public direct-PayPal surface: telemetry accepts only the boolean opt-out. */
-declare function DirectPayPalButton(props: DirectPayPalButtonProps): React.ReactElement | null;
+/**
+ * Checkout surface combining hosted vault card capture with wallets, APMs,
+ * and PayPal. Card entry is hosted-vault-only.
+ *
+ * Stripe-hosted PayPal uses its own Elements instance; direct PayPal uses the
+ * official PayPal SDK when the session advertises that gateway.
+ */
+declare function SplitCardForm(props: SplitCardFormProps): React.JSX.Element;
 
-interface FloPayAutomaticPaymentSuccessEvent {
-    result: PaymentResult;
-    session: CheckoutSession | null;
-    sessionId: string | null;
-    autoCompleted: boolean;
-}
-interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onError'> {
-    sessionId?: string;
+/** Props for {@link VaultCardFields}. */
+interface VaultCardFieldsProps {
     /**
-     * Session-bound checkout token for a consumer-supplied {@link sessionId}
-     * (the `nonce` returned when that session was created). Post-#640 backends
-     * require it as `x-checkout-session-token` to read the session and to
-     * `/process` it; without it the existing-session path 401s with
-     * "Missing checkout session token.". Ignored on the create-session path,
-     * where the SDK mints and threads the nonce itself.
+     * The card-capture adapter (typically `useFloPay().cardCapture()`). Owns
+     * injecting + bootstrapping the hosted vault widget. Changing this instance
+     * (or {@link VaultCardFieldsProps.html}) remounts the widget.
      */
-    nonce?: string;
-    createSession?: InlineSessionDraft;
+    capture: CardCaptureAdapter;
     /**
-     * @deprecated Ignored. The backend now picks the customer's most recent
-     * vaulted payment method via `getLatestByUserId` and rebinds the session's
-     * gateway to match it (see `apps/api`'s `createSingle` auto-checkout
-     * branch). Passing this prop has no effect — it is retained only to avoid
-     * breaking existing integrations.
+     * Server-rendered hosted vault widget HTML (the session's
+     * {@link CheckoutSession.vault} block `html`, or one fetched from
+     * `POST /vault/capture`). The widget owns the card fields, submit button,
+     * tokenization, charge, and 3DS; this component only injects it.
      */
-    paymentMethodId?: string;
+    html: string;
     /**
-     * @deprecated Ignored. The backend orchestrates gateway routing — clients
-     * no longer choose between card and PayPal at the SDK boundary. Passing
-     * this prop has no effect.
+     * Per-session integrity token (the vault block's `messageToken`). Forwarded
+     * to the adapter so it can reject forged terminal `postMessage` outcomes that
+     * omit/mismatch it. Omitted when the backend does not (yet) mint one.
      */
-    checkoutMethod?: CheckoutButtonMethod;
-    clientId?: string;
+    messageToken?: string;
     /**
-     * Unified products array (TeamFloPay/backend#760). When supplied,
-     * `items`/`subscriptions` are ignored. The SDK folds the legacy fields
-     * into this shape internally.
+     * Exact origin expected for the widget's terminal `postMessage` outcomes
+     * (the vault block's `expectedOrigin`). Forwarded to the adapter's origin
+     * gate; omitted to skip it.
      */
-    products?: CheckoutProduct[];
-    items?: CheckoutItem[];
-    subscriptions?: CheckoutSubscription[];
-    account?: InlineSessionDraft['account'];
-    successUrl?: string;
-    cancelUrl?: string;
-    couponCodes?: string[];
-    tagsData?: InlineSessionDraft['tagsData'];
-    utmMetadata?: InlineSessionDraft['utmMetadata'];
-    billingApiUrl?: string;
-    locale?: string;
+    expectedOrigin?: string;
     /**
-     * High-level theme bundle that styles the button (and the fallback
-     * `FloPayCheckout` modal that opens when the saved-payment charge needs
-     * user interaction). One of: `'classic'`, `'modern-light'`, `'modern-dark'`,
-     * `'bold-light'`, `'bold-dark'`, `'glass-light'`, `'glass-dark'`. Explicit
-     * `buttonsStyles` still wins for fine-grained overrides.
+     * Merchant theme colors pushed into the hosted widget so the card form
+     * matches the surrounding checkout. Applied live on change (no remount).
      */
-    theme?: ThemeId;
+    theme?: VaultCardThemeColors;
+    /** Inline styles for the container the widget mounts into. */
+    containerStyle?: React.CSSProperties;
+    /** Fired once the widget is injected and bootstrapping. */
+    onReady?: () => void;
     /**
-     * Per-checkout appearance overrides layered on top of the chosen `theme`
-     * (same shape as {@link FloPayCheckout}'s `appearance`). Its `colorPrimary` /
-     * `colorPrimaryHover` / `borderRadius` re-skin the button — and the fallback
-     * `FloPayCheckout` modal — so the auto-pay button matches the rest of the
-     * themed checkout. Without this the button only saw the bundle's defaults.
+     * Fired with a load/runtime error message from the widget, or `null` when it
+     * clears. Wired to the card form's shared error banner. Terminal payment
+     * outcomes (`complete` / `decline`) are observed by the parent form directly
+     * off the same adapter and are not surfaced here.
      */
-    appearance?: FloPayAppearance;
+    onError?: (message: string | null) => void;
     /**
-     * @deprecated Use `theme` instead. Legacy buttons-layout preset
-     * (`'default' | 'minimal' | 'rounded' | 'dark'`). Still honored for
-     * back-compat.
+     * Fired with the widget's inline field-validation message (live, debounced by
+     * the widget to changes), or `null` when validation clears. Surfaced in the
+     * card form's error banner and the merchant `onError`.
      */
-    buttonsTheme?: ButtonsLayoutTheme;
-    buttonsStyles?: ButtonsLayoutStyles;
-    onSuccess?: (event: FloPayAutomaticPaymentSuccessEvent) => void;
-    onError?: (error: FloPayError) => void;
-    onDecline?: (decline: DeclineEvent) => void;
-    children?: React.ReactNode;
+    onValidation?: (message: string | null) => void;
 }
-declare function FloPayAutomaticPaymentButton({ sessionId, nonce, createSession, paymentMethodId: _deprecatedPaymentMethodId, checkoutMethod: _deprecatedCheckoutMethod, clientId, products, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, theme, appearance, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): React.JSX.Element;
+/**
+ * Renders the backend-served vault PCI card widget
+ * (TeamFloPay/backend#823, Model A). The hosted widget
+ * is a self-contained form: PAN / CVC, the submit button, the charge, and 3DS
+ * all live inside it. This component only injects the widget HTML through the
+ * {@link CardCaptureAdapter} and bridges its `ready` / `error` lifecycle events
+ * back to the surrounding card form.
+ */
+declare function VaultCardFields({ capture, html, messageToken, expectedOrigin, theme, containerStyle, onReady, onError, onValidation, }: VaultCardFieldsProps): React.ReactElement;
 
 export { AddressElement, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type DirectPayPalInitializationState, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, type PaymentElementProps, SplitCardForm, type SplitCardFormProps, VaultCardFields, type VaultCardFieldsProps, useCheckout, useElements, useFloPay, usePayPalFloPay };