@flopay/react 1.4.1 → 1.4.2

package/dist/index.d.ts

@@ -18,12 +18,18 @@ interface FloPayProviderProps {
     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 smallest currency unit (cents). Used when no clientSecret. */
+        /** Total amount in cents for deferred non-card Elements without a client secret. */
         amount?: number;
-        /** ISO 4217 currency code (lowercase). Used when no clientSecret. */
+        /** ISO 4217 currency code for deferred non-card Elements without a client secret. */
         currency?: string;
-        /** How payment methods are created. 'manual' (default for cards) or 'auto' (needed for PayPal). */
+        /** 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';
@@ -35,13 +41,20 @@ interface FloPayProviderProps {
 /**
  * Provides FloPay SDK context to the component tree.
  *
- * Wrap your checkout page (or your entire app) with this provider:
+ * Wrap provider-context elements with this provider:
  *
  * ```tsx
  * <FloPayProvider flopay={loadFloPay('pk_test_...')}>
- *   <CheckoutForm />
+ *   <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 function FloPayProvider({ flopay: floPayProp, paypalFlopay: paypalFloPayProp, options, children, }: FloPayProviderProps): React.ReactElement;
 
@@ -82,8 +95,6 @@ interface FloPayCheckoutProps {
     onError?: (error: FloPayError) => void;
     /** Called when a payment is declined or the authentication step fails. */
     onDecline?: (decline: DeclineEvent) => void;
-    /** Called when the full cardholder name input changes. */
-    onFullNameChange?: (value: string) => void;
     /** Called when the AVS country dropdown changes. */
     onCountryChange?: (country: string) => void;
     /** Called when the AVS ZIP/postcode input changes. */
@@ -95,8 +106,8 @@ interface FloPayCheckoutProps {
      */
     showPayPal?: boolean;
     /**
-     * Show the Stripe-rendered checkout — card fields, ExpressCheckoutElement,
-     * and the PaymentElement accordion (default: `true`). When `false`, only
+     * Show Stripe-rendered wallets/APMs alongside the vault-hosted card surface
+     * (default: `true`). When `false`, only
      * `DirectPayPalButton` can render. Both `showStripe=false` and
      * `showPayPal=false` (with no PayPal gateway configured) triggers a
      * bootstrap-time validation error.
@@ -122,9 +133,9 @@ interface FloPayCheckoutProps {
     /** Layout mode: 'default' (all visible) or 'buttons' (PayPal/wallets + expandable card form). */
     layout?: 'default' | 'buttons';
     /**
-     * High-level theme bundle that styles both the Stripe-side appearance and
-     * the FloPay wrapper / submit / inputs. One of: `'classic'` (historic FloPay
-     * look, no bundle applied), `'modern-light'`, `'modern-dark'`,
+     * High-level theme bundle that styles non-card Stripe Elements, the FloPay
+     * wrapper / AVS inputs, and the hosted vault widget. One of: `'classic'`
+     * (historic FloPay look, no bundle applied), `'modern-light'`, `'modern-dark'`,
      * `'bold-light'`, `'bold-dark'`, `'glass-light'`, `'glass-dark'`. Explicit
      * `appearance` / `buttonsStyles` props still override their respective
      * halves when supplied.
@@ -177,15 +188,13 @@ interface FloPayCheckoutProps {
      */
     cardFieldOrder?: _flopay_shared.VaultCardFieldKey[];
     /**
-     * Content rendered directly above the card form (below the "or pay with card"
-     * divider, above the card fields). Used by the demo playground to surface a
+     * Content rendered directly above the hosted vault card widget (below the
+     * "or pay with card" divider). Used by the demo playground to surface a
      * test-cards helper; harmless to omit in a normal integration.
      */
     cardPreFormSlot?: React.ReactNode;
     /** Layout for AVS fields: 'row' (side-by-side, default) or 'column' (stacked). */
     avsLayout?: 'row' | 'column';
-    /** Label for the submit button. */
-    submitLabel?: string;
     /** Additional CSS class for the wrapper. */
     className?: string;
     /** Seed an initial checkout error message for the rendered payment form. */
@@ -223,7 +232,7 @@ interface FloPayCheckoutProps {
  * payment provider, and renders the appropriate UI based on checkout mode.
  *
  * **Modes:**
- * - `full` (default) — renders `SplitCardForm` with card fields + wallet buttons
+ * - `full` (default) — renders hosted-vault card capture, wallets, APMs, and PayPal
  * - `confirm` — renders a "Confirm Purchase" button, uses saved payment method
  * - `auto` — auto-submits with saved PM, falls back to `full` on failure
  *
@@ -235,7 +244,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, nonce: nonceProp, createSession: createSessionParams, billingApiUrl, telemetry, appearance: appearanceOverride, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showStripe, showApplePay, showGooglePay, debug, layout, theme, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter: _showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, cardFieldOrder, cardPreFormSlot, avsLayout, submitLabel, 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, onDecline, onCountryChange, onZipChange, showPayPal, showStripe, 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
@@ -268,8 +277,7 @@ interface CheckoutState {
 /**
  * Returns the current checkout session state.
  *
- * Must be called within a `<CheckoutProvider>` (typically rendered
- * internally by `<CheckoutForm>`).
+ * Must be called within the checkout context rendered by `<FloPayCheckout>`.
  */
 declare function useCheckout(): CheckoutState;
 
@@ -294,139 +302,28 @@ interface ElementComponentProps {
     /** 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[];
+    };
+}
 /**
- * Renders the unified Payment Element — a single component that accepts
- * cards, wallets, and other payment methods.
- *
- * TODO: Will render inside an iframe for PCI compliance in a future phase.
- */
-declare const PaymentElement: React.FC<ElementComponentProps>;
-/**
- * Renders a combined card input (number + expiry + CVC).
- *
- * TODO: Will render inside an iframe for PCI compliance in a future phase.
- */
-declare const CardElement: React.FC<ElementComponentProps>;
-/**
- * Renders a card number input field.
- *
- * TODO: Will render inside an iframe for PCI compliance in a future phase.
- */
-declare const CardNumberElement: React.FC<ElementComponentProps>;
-/**
- * Renders a card expiry input field.
- *
- * TODO: Will render inside an iframe for PCI compliance in a future phase.
- */
-declare const CardExpiryElement: React.FC<ElementComponentProps>;
-/**
- * Renders a card CVC input field.
- *
- * TODO: Will render inside an iframe for PCI compliance in a future phase.
+ * 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 CardCvcElement: React.FC<ElementComponentProps>;
+declare const PaymentElement: React.FC<PaymentElementProps>;
 /**
  * Renders an address input element.
  */
 declare const AddressElement: React.FC<ElementComponentProps>;
 
-/** Methods exposed via ref for external 3DS handling. */
-interface CheckoutFormRef {
-    handleNextAction: (clientSecret: string) => Promise<void>;
-}
-/** Props for the drop-in `CheckoutForm` component. */
-interface CheckoutFormProps {
-    /** The checkout session ID (UUID from billing API). */
-    sessionId: string;
-    /**
-     * Session-bound checkout token returned by session creation
-     * (`CheckoutSessionResult.nonce` or `session.clientSecret`). Forwarded as
-     * `x-checkout-session-token` on every continuation request — required by
-     * post-#640 backends (`TeamFloPay/backend#640`), which 401 the call when the
-     * header is missing or does not match the session's stored nonce.
-     * `FloPayCheckout` plumbs this prop automatically.
-     */
-    nonce?: string;
-    /** Billing API base URL. Optional — defaults to the value from FloPayProvider or the shared constant. */
-    billingApiUrl?: string;
-    /** User's email (required for creating payment intents). */
-    email?: string;
-    /** User ID (required for processing payments). */
-    userId?: string;
-    /**
-     * Called when the full payment flow completes successfully.
-     * By default the form handles everything: tokenize → create intent →
-     * confirm → processPayment → 3DS retry. You just handle the success.
-     */
-    onComplete?: (result: PaymentResult) => void;
-    /** Called when a payment error occurs. */
-    onError?: (error: FloPayError) => void;
-    /** Called when a payment is declined or the authentication step fails. */
-    onDecline?: (decline: DeclineEvent) => void;
-    /**
-     * **Override**: If provided, the form tokenizes the card and confirms
-     * the payment, but delegates backend submission to the caller.
-     * When omitted, the form calls `processPayment` internally.
-     */
-    onTokenizedBody?: (tokenizedBody: TokenizedBody) => void;
-    /** Layout style for the PaymentElement. */
-    layout?: 'tabs' | 'accordion' | 'auto';
-    /** Label for the submit button. */
-    submitLabel?: string;
-    /** Whether to show an address element. */
-    showAddress?: boolean | 'billing' | 'shipping';
-    /** Additional CSS class for the form wrapper. */
-    className?: string;
-    /** Custom children (e.g. a custom submit button). Overrides the default button. */
-    children?: React.ReactNode;
-    /** First name for billing. */
-    firstName?: string;
-    /** Last name for billing. */
-    lastName?: string;
-    /** Checkout version for A/B tracking. */
-    chv?: string;
-    /** External processing state (used when onTokenizedBody is provided). */
-    isProcessing?: boolean;
-    /** External error message (used when onTokenizedBody is provided). */
-    error?: string | null;
-    /** Called when internal error state changes. */
-    onErrorChange?: (error: string | null) => void;
-}
-/**
- * Drop-in checkout form that handles the full payment lifecycle by default.
- *
- * **Default (self-contained) mode** — just provide config + onComplete:
- * ```tsx
- * <CheckoutForm
- *   sessionId="uuid"
- *   billingApiUrl="https://api.example.com"
- *   email="user@example.com"
- *   userId="user_1"
- *   onComplete={(result) => router.push('/success')}
- * />
- * ```
- *
- * The form handles internally:
- * 1. Validate → tokenize card → create PaymentIntent → confirm (3DS)
- * 2. Submit token to `POST /v1/checkouts/sessions/process`
- * 3. If backend returns `3ds_required` → re-confirm with new client secret
- * 4. Wallet resume after redirect (PayPal, etc.)
- *
- * **Override mode** — provide `onTokenizedBody` to handle backend submission yourself:
- * ```tsx
- * <CheckoutForm
- *   ...
- *   onTokenizedBody={(body) => myCustomProcessPayment(body)}
- * />
- * ```
- */
-declare const CheckoutForm: React.ForwardRefExoticComponent<CheckoutFormProps & React.RefAttributes<CheckoutFormRef>>;
-
 type MaybePromise<T> = T | Promise<T>;
-/** Methods exposed via ref for external 3DS handling. */
-interface SplitCardFormRef {
-    handleNextAction: (clientSecret: string) => Promise<void>;
-}
 /** Props for the `SplitCardForm` component. */
 interface SplitCardFormProps {
     /** The checkout session ID (UUID from billing API). */
@@ -461,26 +358,16 @@ interface SplitCardFormProps {
     lastName?: string;
     /** Checkout version for A/B tracking. */
     chv?: string;
-    /** Label for the submit button. */
-    submitLabel?: string;
     /** Additional CSS class for the form wrapper. */
     className?: string;
-    /** Custom children (overrides default submit button). */
-    children?: React.ReactNode;
     /** External processing state. */
     isProcessing?: boolean;
     /** External error message. */
     error?: string | null;
     /** Called when internal error state changes. */
     onErrorChange?: (error: string | null) => void;
-    /** Callback when the full cardholder name input changes. */
-    onFullNameChange?: (value: string) => void;
-    /** Callback when first name changes (from the name input). */
-    onFirstNameChange?: (value: string) => void;
-    /** Callback when last name changes (from the name input). */
-    onLastNameChange?: (value: string) => void;
-    /**
-     * Show the PayPal payment surface above card fields. Defaults to `true`.
+    /**
+     * Show the PayPal payment surface above the hosted vault card surface. Defaults to `true`.
      * The renderer is chosen from `session.gateways.paypal`: when that gateway
      * is configured, `DirectPayPalButton` (PayPal JS SDK) takes over and Stripe
      * drops `paypal` from its express row to avoid double-rendering; otherwise
@@ -490,7 +377,7 @@ interface SplitCardFormProps {
      */
     showPayPal?: boolean;
     /**
-     * Show the Stripe-rendered checkout (card fields + ExpressCheckoutElement +
+     * Show Stripe-rendered wallets and APMs (ExpressCheckoutElement +
      * PaymentElement). Defaults to `true`. When `false`, every Stripe surface
      * is hidden — only `DirectPayPalButton` can render. Setting both
      * `showStripe={false}` and `showPayPal={false}` (with no PayPal gateway
@@ -536,8 +423,8 @@ interface SplitCardFormProps {
      */
     layout?: 'default' | 'buttons';
     /**
-     * High-level theme bundle that styles the whole checkout (Stripe-side
-     * appearance + FloPay wrapper / submit button / inputs). One of:
+     * High-level theme bundle that styles non-card Stripe Elements, the FloPay
+     * wrapper / AVS inputs, and the hosted vault widget. One of:
      * `'classic'` (historic FloPay look, no bundle applied), `'modern-light'`,
      * `'modern-dark'`, `'bold-light'`, `'bold-dark'`, `'glass-light'`,
      * `'glass-dark'`. Explicit `appearance` / `buttonsStyles` props still
@@ -555,10 +442,10 @@ interface SplitCardFormProps {
     buttonsStyles?: _flopay_shared.ButtonsLayoutStyles;
     /**
      * Appearance from `FloPayProvider` / `FloPayCheckout`. Threaded through so
-     * the React-rendered wrapper, submit button, title, and per-element card
-     * field styling can derive colors from `appearance.variables` when no
-     * explicit `buttonsStyles` is supplied. Bundle consumers (`THEMES[id]`) get
-     * a coherent look without having to forward both halves manually.
+     * the React-rendered wrapper, AVS inputs, title, and hosted vault widget can
+     * derive colors from `appearance.variables` when no explicit `buttonsStyles`
+     * is supplied. Bundle consumers (`THEMES[id]`) get a coherent look without
+     * having to forward both halves manually.
      */
     appearance?: _flopay_shared.FloPayAppearance;
     /** Custom React content rendered inside the card button when `layout="buttons"`. */
@@ -598,7 +485,7 @@ interface SplitCardFormProps {
      * Only applies on the vault card path.
      */
     cardFieldOrder?: _flopay_shared.VaultCardFieldKey[];
-    /** Content rendered above the card form (below the wallet divider). */
+    /** 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';
@@ -652,13 +539,13 @@ interface SplitCardFormProps {
     debug?: boolean;
 }
 /**
- * Split card checkout form matching `checkout/StripeCardForm`:
- * PayPal button → divider → CardNumber → CardExpiry + CardCVC → Full Name → Submit.
+ * Checkout surface combining hosted vault card capture with wallets, APMs,
+ * and PayPal. Card entry is hosted-vault-only.
  *
- * PayPal uses its own Stripe Elements instance (no `paymentMethodCreation`)
- * exactly like checkout does with two separate `<Elements>` wrappers.
+ * Stripe-hosted PayPal uses its own Elements instance; direct PayPal uses the
+ * official PayPal SDK when the session advertises that gateway.
  */
-declare const SplitCardForm: React.ForwardRefExoticComponent<SplitCardFormProps & React.RefAttributes<SplitCardFormRef>>;
+declare function SplitCardForm(props: SplitCardFormProps): React.JSX.Element;
 
 /** Props for {@link VaultCardFields}. */
 interface VaultCardFieldsProps {
@@ -711,8 +598,8 @@ interface VaultCardFieldsProps {
     onValidation?: (message: string | null) => void;
 }
 /**
- * Renders the backend-served vault PCI card widget in place of provider-owned
- * (Stripe) card elements (TeamFloPay/backend#823, Model A). The hosted widget
+ * 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
@@ -724,7 +611,7 @@ declare function VaultCardFields({ capture, html, messageToken, expectedOrigin,
  * Props for the `PayPalButton` component.
  *
  * Must be rendered inside its own `FloPayProvider` with `paymentMethodCreation: undefined`
- * (not 'manual') — PayPal cannot share the same Elements instance as card fields.
+ * (not 'manual') because this PayPal flow needs automatic payment-method creation.
  */
 interface PayPalButtonProps {
     /** The checkout session ID (UUID from billing API). */
@@ -762,13 +649,12 @@ interface PayPalButtonProps {
 /**
  * PayPal button that handles the full PayPal payment flow.
  *
- * **Important**: PayPal requires its own `FloPayProvider` — it cannot share
- * the same Stripe Elements instance as card fields when they use
- * `paymentMethodCreation: 'manual'`. This matches `checkout/StripeCardForm`
- * which renders PayPal in a separate `<Elements>` wrapper.
+ * **Important**: PayPal requires its own `FloPayProvider` with automatic
+ * payment-method creation. Keep it separate from manually created wallet/APM
+ * Elements groups.
  *
  * ```tsx
- * {/* Card fields provider (paymentMethodCreation: 'manual') *\/}
+ * {/* Main checkout provider *\/}
  * <FloPayProvider flopay={flopay} options={{ amount, currency }}>
  *   <SplitCardForm ... />
  * </FloPayProvider>
@@ -812,6 +698,7 @@ interface DirectPayPalBeforeButtonClickResult {
  * 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;
@@ -854,6 +741,10 @@ interface DirectPayPalButtonProps {
     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;
     /**
@@ -868,7 +759,7 @@ interface DirectPayPalButtonProps {
     /**
      * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
      * true) to bind the button to. When set, the button skips its usual
-     * `POST /v1/checkouts/payments/intents` round-trip on click and feeds this
+     * 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
@@ -973,4 +864,4 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
 }
 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;
 
-export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, VaultCardFields, type VaultCardFieldsProps, useCheckout, useElements, useFloPay, usePayPalFloPay };
+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 };