@flopay/js 1.2.8 → 1.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _flopay_shared from '@flopay/shared';
-import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingDetails, CheckoutGateways, ProcessPaymentParams, InlineSessionDraft, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
+import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, CardCaptureAdapter, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingDetails, CheckoutGateways, VaultCaptureBlock, ProcessPaymentParams, InlineSessionDraft, CardCaptureProviderId, CardCaptureMountOptions, CardCaptureEventType, CardCaptureOutcomeEvent, VaultCardThemeColors, VaultCardFieldKey, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
 
 /**
  * Manages the creation and lifecycle of payment elements.
@@ -58,6 +58,22 @@ declare class FloPay {
     createPaymentMethod(billingDetails?: _flopay_shared.BillingDetails): Promise<CreatePaymentMethodResult>;
     /** Confirm a card payment with a known client secret and payment method ID. */
     confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    /**
+     * Create a {@link CardCaptureAdapter} for collecting card details through the
+     * backend-rendered hosted vault PCI widget instead of provider-owned (Stripe)
+     * card fields (TeamFloPay/backend#823).
+     *
+     * The returned adapter injects the server-supplied widget HTML (the session's
+     * {@link CheckoutSession.vault} block, or one fetched via
+     * `PaymentAPI.getVaultCapture`) and relays the widget's terminal outcome. The
+     * backend owns tokenization, the PaymentIntent, 3DS, and fulfilment — no
+     * Stripe.js is involved on the card path and PCI-sensitive fields never enter
+     * the SDK runtime.
+     */
+    cardCapture(options?: {
+        /** Checkout session id to bind the capture to (outcome correlation). */
+        sessionId?: string;
+    }): CardCaptureAdapter;
     /** Confirm a PayPal payment: create intent via billing API → confirm → redirect if needed. */
     confirmPayPalPayment(params: {
         billingApiUrl: string;
@@ -254,6 +270,12 @@ interface RawCheckoutSession {
     totalAmount?: number;
     checkoutMode?: 'full' | 'auto' | 'confirm';
     gateways?: CheckoutGateways;
+    /**
+     * Generic downstream card-method id for a card already on file
+     * (TeamFloPay/backend#823) — present for returning customers so the SDK can
+     * skip the vault widget. Absent for first-time buyers.
+     */
+    providerPaymentMethodId?: string | null;
     accountData: {
         userId: string;
         firstName: string;
@@ -320,6 +342,31 @@ declare class PaymentAPI {
      * completes; otherwise the TTL handles cleanup.
      */
     clearSessionDisplayData(sessionId: string): void;
+    /**
+     * Fetch (re-mint) the hosted vault capture widget for a session
+     * (TeamFloPay/backend#823).
+     *
+     * `POST /v1/checkouts/sessions/{id}/vault/capture` returns the SDK-ready
+     * {@link VaultCaptureBlock} (`html` + `url`, plus `messageToken` /
+     * `expectedOrigin` once the backend mints them). The SDK injects `html` as
+     * the card-capture widget. This is the fallback path for sessions that did
+     * not receive the embedded `vault` block on create (e.g. a session loaded by
+     * id via `GET`, or a pre-1.3.0 create); the endpoint is idempotent and reuses
+     * session-cached creds when available.
+     *
+     * Because the endpoint is idempotent, the request is wrapped in
+     * `fetchWithNetworkRetry`: a transient network blip (dropped connection, DNS
+     * hiccup, failed CORS preflight) would otherwise leave the secure card form
+     * unable to load and hard-block checkout.
+     *
+     * The PCIVault submit *secret* the backend may include in the response is
+     * intentionally **not** read or surfaced — it is server-only and never enters
+     * the SDK runtime.
+     *
+     * `nonce` is forwarded as `x-checkout-session-token` (required by post-#640
+     * backends, matched against the session's stored nonce).
+     */
+    getVaultCapture(checkoutSessionId: string, nonce?: string): Promise<VaultCaptureBlock>;
     /**
      * Fetch and normalize a checkout session.
      *
@@ -348,6 +395,44 @@ declare class PaymentAPI {
     processPayment(_userId: string, data: ProcessPaymentParams, options?: {
         pollTimeoutMs?: number;
     }): Promise<Response>;
+    /**
+     * Patch the buyer's account snapshot (email, name, billing address, AVS
+     * intent) onto a checkout session via
+     * `PATCH /v1/checkouts/sessions/{id}/account` (TeamFloPay/backend#823).
+     *
+     * The vault path's hosted form owns the charge end-to-end so the SDK
+     * never calls `/process` on this path; the buyer-typed AVS / billing
+     * address would otherwise be lost. The SDK calls this just before
+     * submitting the vault widget so the downstream listener mints the
+     * Stripe PaymentMethod with the right `billing_details.address` and the
+     * per-attempt + per-PM address snapshots are populated.
+     *
+     * Body shape mirrors the relevant subset of `/process`'s
+     * `ProcessCheckoutBodyDto` — same keys, same validators. The endpoint
+     * is idempotent: empty/undefined fields are not written, addresses are
+     * last-writer-wins, AVS analytics are first-writer-wins.
+     *
+     * Wrapped in `fetchWithNetworkRetry` because a transient blip on this
+     * pre-pay PATCH would silently leave AVS unsent and cause an
+     * AVS-protected charge to decline downstream.
+     */
+    patchAccountSnapshot(sessionId: string, nonce: string, body: {
+        accountData: {
+            userId: string;
+            email: string;
+            firstName?: string | null;
+            lastName?: string | null;
+            addressLine1?: string | null;
+            addressLine2?: string | null;
+            city?: string | null;
+            state?: string | null;
+            zip?: string | null;
+            country?: string | null;
+            gender?: string | null;
+        };
+        avsCheck?: boolean;
+        avsConfig?: Record<string, unknown>;
+    }): Promise<void>;
     /**
      * Create a PaymentIntent on the backend.
      *
@@ -358,8 +443,15 @@ declare class PaymentAPI {
      * session-bound checkout token returned by session creation. Post-#640
      * backends reject this call with a 401 when the header is missing or does
      * not match the session's stored nonce.
+     *
+     * `paymentMethodType` is optional for the vault card-capture flow
+     * (TeamFloPay/backend#823): the frontend starts checkout *without* an upfront
+     * card payment method, so it may be omitted (or `null`). The hosted vault PCI
+     * form captures the card afterwards and the backend attaches the resulting
+     * payment method to the PaymentIntent it returns here. Legacy callers keep
+     * passing the concrete payment method id / type.
      */
-    createPaymentIntent(sessionId: string, email: string, paymentMethodType: string, options?: {
+    createPaymentIntent(sessionId: string, email: string, paymentMethodType?: string | null, options?: {
         signal?: AbortSignal;
         isPaypal?: string;
         nonce?: string;
@@ -411,6 +503,12 @@ declare class PaymentAPI {
     private normalizeRawSession;
     /** Convert raw session to the SDK CheckoutSession shape. */
     private toCheckoutSession;
+    /**
+     * Coerce a raw vault block into a typed {@link VaultCaptureBlock}. The
+     * server-only PCIVault submit `secret` is deliberately dropped so it never
+     * lands on the public session surface (logs / telemetry / client inspection).
+     */
+    private toVaultBlock;
     private toCheckoutSessionStatus;
     private resolveProcessResponse;
     private toCheckoutProcessingPending;
@@ -432,6 +530,132 @@ declare class PaymentAPI {
     private mergeCachedDisplayData;
 }
 
+/** Configuration for a {@link PciVaultCardCapture} instance. */
+interface PciVaultCardCaptureConfig {
+    /** Checkout session id bound to the capture (for outcome correlation + trust). */
+    sessionId?: string;
+    /**
+     * Default strict origin for vault `postMessage` outcomes. Overridden by
+     * {@link CardCaptureMountOptions.expectedOrigin} when that is supplied at
+     * mount. When neither is set the origin gate is skipped (the widget posts
+     * same-window in the Model-A flow).
+     */
+    expectedOrigin?: string;
+}
+/**
+ * {@link CardCaptureAdapter} backed by the backend-rendered PCIVault hosted
+ * widget.
+ *
+ * `mount()` injects the server-supplied widget HTML (re-executing its bundled
+ * `<script>` so the form bootstraps) and subscribes to the widget's
+ * `postMessage` outcome. The backend owns everything else; this adapter never
+ * touches the card data, a payment intent, or 3DS.
+ */
+declare class PciVaultCardCapture implements CardCaptureAdapter {
+    readonly provider: CardCaptureProviderId;
+    private readonly config;
+    private container;
+    private messageHandler;
+    /**
+     * Parent-page-level overlay rendering the provider's verification challenge
+     * (3DS-2 iframe) on `action_required`. Owned by the adapter — not the
+     * widget — so it can sit above the host SDK's processing backdrop, which
+     * would otherwise visually cover an in-widget challenge iframe.
+     */
+    private actionOverlay;
+    /**
+     * Listener that catches the `flopay-vault-3ds-return` postMessage from the
+     * provider's challenge return page. When the SDK owns the challenge iframe
+     * the return page lives inside *that* iframe (not the widget's), so
+     * `window.parent` is the host page — the widget's existing message
+     * listener can't see it. The SDK forwards completion into the widget via
+     * `action_completed` so the widget kicks `/3ds/complete` immediately
+     * instead of waiting on the eventual provider webhook.
+     */
+    private threeDsReturnHandler;
+    /** Per-session integrity token to require on outcomes (from mount options). */
+    private messageToken;
+    /** Strict origin to require on outcomes, when configured. */
+    private expectedOrigin;
+    /** Latest merchant theme to push into the (cross-origin) widget. */
+    private theme;
+    /** Latest host submit-gate state to push into the widget (block its submit). */
+    private submitGateBlocked;
+    /** Latest card-field order + autofocus directive to push into the widget. */
+    private cardFieldOrder;
+    private cardAutoFocus;
+    private readonly listeners;
+    constructor(config?: PciVaultCardCaptureConfig);
+    mount(container: HTMLElement, options: CardCaptureMountOptions): Promise<void>;
+    on(event: CardCaptureEventType, handler: (event: CardCaptureOutcomeEvent) => void): () => void;
+    unmount(): void;
+    /**
+     * Inject the server-rendered widget HTML. `innerHTML` does not execute
+     * embedded `<script>` tags, so each script node is replaced with a freshly
+     * created element that the browser will load and run (this is what boots the
+     * PCIVault form bundle against the `data-flopay-config` container).
+     */
+    private injectWidget;
+    private attachMessageListener;
+    /**
+     * Push merchant theme colors into the hosted widget (live). The host calls
+     * this on a runtime theme switch; the widget applies them to its CSS variables
+     * without a remount. Stores the latest theme so `ready` can re-push it.
+     */
+    applyTheme(theme: VaultCardThemeColors): void;
+    /** postMessage the current theme to the widget's (cross-origin) document. */
+    private postTheme;
+    /**
+     * Gate the widget's submit from the host. When `blocked`, the widget cancels
+     * its next submit and emits `'blocked'` instead of `'submitting'` so the host
+     * can validate merchant-DOM fields (AVS) first. Stored so `ready` re-pushes it.
+     */
+    setSubmitGate(blocked: boolean): void;
+    /** postMessage the current submit-gate state to the widget's document. */
+    private postSubmitGate;
+    /**
+     * Push the card-field order + autofocus directive into the widget (live). The
+     * widget re-sequences its rows (DOM order, so tab order follows) and focuses
+     * its first field unless `autoFocus` is false. Stored so `ready` re-pushes it.
+     */
+    setCardFieldOrder(order: VaultCardFieldKey[] | null, autoFocus: boolean): void;
+    /** postMessage the current field order + autofocus to the widget's document. */
+    private postCardFieldOrder;
+    private emit;
+    /**
+     * Render the provider-hosted verification challenge (e.g. Stripe 3DS-2) in a
+     * full-page overlay at the PARENT page level. The widget's inline-iframe
+     * approach is unusable because the SDK's processing backdrop sits above the
+     * vault iframe, hiding any challenge mounted inside it — by lifting the
+     * iframe to the host page the adapter can give it a z-index that wins.
+     *
+     * The overlay tears down on the next terminal outcome
+     * (`complete`/`decline`/`error`) or when the buyer closes it via the backdrop
+     * close button. Closing manually is a soft abandon — the next `/status` poll
+     * either reveals a real outcome (the challenge completed via the issuer's
+     * own redirect to `/vault/3ds/return`, which posts back into the widget) or
+     * surfaces `requires_action` again so the host can decide what to do.
+     */
+    private showActionRequiredOverlay;
+    /**
+     * Tell the vault widget that the buyer has completed (or abandoned) the
+     * challenge. The widget responds by POSTing `/3ds/complete` — its
+     * sub-300ms sync resolver writes the follow-up attempt row immediately,
+     * so the next `/status` poll resolves to a terminal outcome instead of
+     * waiting for the eventual provider webhook.
+     */
+    private postActionCompleted;
+    private hideActionRequiredOverlay;
+    /**
+     * Size the hosted-widget iframe to the height reported by the form inside it.
+     * Cross-origin iframes don't auto-size to their content, so the widget posts
+     * its measured height and we apply it here (clamped to a sane range). This is
+     * what lets the card form shrink/grow to fit instead of sitting at a fixed
+     * height.
+     */
+    private applyHeight;
+}
+
 /**
  * Creates a checkout session via the billing API and redirects the user
  * to the hosted checkout page.
@@ -473,4 +697,4 @@ declare function createCheckoutSessionWithRetries(options: CreateSessionParams &
     maxRetries?: number;
 }): Promise<CheckoutSessionResult>;
 
-export { FloPay, FloPayElements, PaymentAPI, type SessionDisplayCacheData, type SessionDisplayProduct, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };
+export { FloPay, FloPayElements, PaymentAPI, PciVaultCardCapture, type PciVaultCardCaptureConfig, type SessionDisplayCacheData, type SessionDisplayProduct, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _flopay_shared from '@flopay/shared';
-import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingDetails, CheckoutGateways, ProcessPaymentParams, InlineSessionDraft, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
+import { PaymentProviderAdapter, ElementOptions, ElementType, MountedElement, FloPayError, FloPayConfig, CreatePaymentMethodResult, ConfirmCardPaymentParams, ConfirmCardPaymentResult, CardCaptureAdapter, ConfirmPaymentParams, PaymentResult, CheckoutSession, NormalizedCheckoutSession, BillingDetails, CheckoutGateways, VaultCaptureBlock, ProcessPaymentParams, InlineSessionDraft, CardCaptureProviderId, CardCaptureMountOptions, CardCaptureEventType, CardCaptureOutcomeEvent, VaultCardThemeColors, VaultCardFieldKey, CreateSessionParams, CheckoutSessionResult } from '@flopay/shared';
 
 /**
  * Manages the creation and lifecycle of payment elements.
@@ -58,6 +58,22 @@ declare class FloPay {
     createPaymentMethod(billingDetails?: _flopay_shared.BillingDetails): Promise<CreatePaymentMethodResult>;
     /** Confirm a card payment with a known client secret and payment method ID. */
     confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
+    /**
+     * Create a {@link CardCaptureAdapter} for collecting card details through the
+     * backend-rendered hosted vault PCI widget instead of provider-owned (Stripe)
+     * card fields (TeamFloPay/backend#823).
+     *
+     * The returned adapter injects the server-supplied widget HTML (the session's
+     * {@link CheckoutSession.vault} block, or one fetched via
+     * `PaymentAPI.getVaultCapture`) and relays the widget's terminal outcome. The
+     * backend owns tokenization, the PaymentIntent, 3DS, and fulfilment — no
+     * Stripe.js is involved on the card path and PCI-sensitive fields never enter
+     * the SDK runtime.
+     */
+    cardCapture(options?: {
+        /** Checkout session id to bind the capture to (outcome correlation). */
+        sessionId?: string;
+    }): CardCaptureAdapter;
     /** Confirm a PayPal payment: create intent via billing API → confirm → redirect if needed. */
     confirmPayPalPayment(params: {
         billingApiUrl: string;
@@ -254,6 +270,12 @@ interface RawCheckoutSession {
     totalAmount?: number;
     checkoutMode?: 'full' | 'auto' | 'confirm';
     gateways?: CheckoutGateways;
+    /**
+     * Generic downstream card-method id for a card already on file
+     * (TeamFloPay/backend#823) — present for returning customers so the SDK can
+     * skip the vault widget. Absent for first-time buyers.
+     */
+    providerPaymentMethodId?: string | null;
     accountData: {
         userId: string;
         firstName: string;
@@ -320,6 +342,31 @@ declare class PaymentAPI {
      * completes; otherwise the TTL handles cleanup.
      */
     clearSessionDisplayData(sessionId: string): void;
+    /**
+     * Fetch (re-mint) the hosted vault capture widget for a session
+     * (TeamFloPay/backend#823).
+     *
+     * `POST /v1/checkouts/sessions/{id}/vault/capture` returns the SDK-ready
+     * {@link VaultCaptureBlock} (`html` + `url`, plus `messageToken` /
+     * `expectedOrigin` once the backend mints them). The SDK injects `html` as
+     * the card-capture widget. This is the fallback path for sessions that did
+     * not receive the embedded `vault` block on create (e.g. a session loaded by
+     * id via `GET`, or a pre-1.3.0 create); the endpoint is idempotent and reuses
+     * session-cached creds when available.
+     *
+     * Because the endpoint is idempotent, the request is wrapped in
+     * `fetchWithNetworkRetry`: a transient network blip (dropped connection, DNS
+     * hiccup, failed CORS preflight) would otherwise leave the secure card form
+     * unable to load and hard-block checkout.
+     *
+     * The PCIVault submit *secret* the backend may include in the response is
+     * intentionally **not** read or surfaced — it is server-only and never enters
+     * the SDK runtime.
+     *
+     * `nonce` is forwarded as `x-checkout-session-token` (required by post-#640
+     * backends, matched against the session's stored nonce).
+     */
+    getVaultCapture(checkoutSessionId: string, nonce?: string): Promise<VaultCaptureBlock>;
     /**
      * Fetch and normalize a checkout session.
      *
@@ -348,6 +395,44 @@ declare class PaymentAPI {
     processPayment(_userId: string, data: ProcessPaymentParams, options?: {
         pollTimeoutMs?: number;
     }): Promise<Response>;
+    /**
+     * Patch the buyer's account snapshot (email, name, billing address, AVS
+     * intent) onto a checkout session via
+     * `PATCH /v1/checkouts/sessions/{id}/account` (TeamFloPay/backend#823).
+     *
+     * The vault path's hosted form owns the charge end-to-end so the SDK
+     * never calls `/process` on this path; the buyer-typed AVS / billing
+     * address would otherwise be lost. The SDK calls this just before
+     * submitting the vault widget so the downstream listener mints the
+     * Stripe PaymentMethod with the right `billing_details.address` and the
+     * per-attempt + per-PM address snapshots are populated.
+     *
+     * Body shape mirrors the relevant subset of `/process`'s
+     * `ProcessCheckoutBodyDto` — same keys, same validators. The endpoint
+     * is idempotent: empty/undefined fields are not written, addresses are
+     * last-writer-wins, AVS analytics are first-writer-wins.
+     *
+     * Wrapped in `fetchWithNetworkRetry` because a transient blip on this
+     * pre-pay PATCH would silently leave AVS unsent and cause an
+     * AVS-protected charge to decline downstream.
+     */
+    patchAccountSnapshot(sessionId: string, nonce: string, body: {
+        accountData: {
+            userId: string;
+            email: string;
+            firstName?: string | null;
+            lastName?: string | null;
+            addressLine1?: string | null;
+            addressLine2?: string | null;
+            city?: string | null;
+            state?: string | null;
+            zip?: string | null;
+            country?: string | null;
+            gender?: string | null;
+        };
+        avsCheck?: boolean;
+        avsConfig?: Record<string, unknown>;
+    }): Promise<void>;
     /**
      * Create a PaymentIntent on the backend.
      *
@@ -358,8 +443,15 @@ declare class PaymentAPI {
      * session-bound checkout token returned by session creation. Post-#640
      * backends reject this call with a 401 when the header is missing or does
      * not match the session's stored nonce.
+     *
+     * `paymentMethodType` is optional for the vault card-capture flow
+     * (TeamFloPay/backend#823): the frontend starts checkout *without* an upfront
+     * card payment method, so it may be omitted (or `null`). The hosted vault PCI
+     * form captures the card afterwards and the backend attaches the resulting
+     * payment method to the PaymentIntent it returns here. Legacy callers keep
+     * passing the concrete payment method id / type.
      */
-    createPaymentIntent(sessionId: string, email: string, paymentMethodType: string, options?: {
+    createPaymentIntent(sessionId: string, email: string, paymentMethodType?: string | null, options?: {
         signal?: AbortSignal;
         isPaypal?: string;
         nonce?: string;
@@ -411,6 +503,12 @@ declare class PaymentAPI {
     private normalizeRawSession;
     /** Convert raw session to the SDK CheckoutSession shape. */
     private toCheckoutSession;
+    /**
+     * Coerce a raw vault block into a typed {@link VaultCaptureBlock}. The
+     * server-only PCIVault submit `secret` is deliberately dropped so it never
+     * lands on the public session surface (logs / telemetry / client inspection).
+     */
+    private toVaultBlock;
     private toCheckoutSessionStatus;
     private resolveProcessResponse;
     private toCheckoutProcessingPending;
@@ -432,6 +530,132 @@ declare class PaymentAPI {
     private mergeCachedDisplayData;
 }
 
+/** Configuration for a {@link PciVaultCardCapture} instance. */
+interface PciVaultCardCaptureConfig {
+    /** Checkout session id bound to the capture (for outcome correlation + trust). */
+    sessionId?: string;
+    /**
+     * Default strict origin for vault `postMessage` outcomes. Overridden by
+     * {@link CardCaptureMountOptions.expectedOrigin} when that is supplied at
+     * mount. When neither is set the origin gate is skipped (the widget posts
+     * same-window in the Model-A flow).
+     */
+    expectedOrigin?: string;
+}
+/**
+ * {@link CardCaptureAdapter} backed by the backend-rendered PCIVault hosted
+ * widget.
+ *
+ * `mount()` injects the server-supplied widget HTML (re-executing its bundled
+ * `<script>` so the form bootstraps) and subscribes to the widget's
+ * `postMessage` outcome. The backend owns everything else; this adapter never
+ * touches the card data, a payment intent, or 3DS.
+ */
+declare class PciVaultCardCapture implements CardCaptureAdapter {
+    readonly provider: CardCaptureProviderId;
+    private readonly config;
+    private container;
+    private messageHandler;
+    /**
+     * Parent-page-level overlay rendering the provider's verification challenge
+     * (3DS-2 iframe) on `action_required`. Owned by the adapter — not the
+     * widget — so it can sit above the host SDK's processing backdrop, which
+     * would otherwise visually cover an in-widget challenge iframe.
+     */
+    private actionOverlay;
+    /**
+     * Listener that catches the `flopay-vault-3ds-return` postMessage from the
+     * provider's challenge return page. When the SDK owns the challenge iframe
+     * the return page lives inside *that* iframe (not the widget's), so
+     * `window.parent` is the host page — the widget's existing message
+     * listener can't see it. The SDK forwards completion into the widget via
+     * `action_completed` so the widget kicks `/3ds/complete` immediately
+     * instead of waiting on the eventual provider webhook.
+     */
+    private threeDsReturnHandler;
+    /** Per-session integrity token to require on outcomes (from mount options). */
+    private messageToken;
+    /** Strict origin to require on outcomes, when configured. */
+    private expectedOrigin;
+    /** Latest merchant theme to push into the (cross-origin) widget. */
+    private theme;
+    /** Latest host submit-gate state to push into the widget (block its submit). */
+    private submitGateBlocked;
+    /** Latest card-field order + autofocus directive to push into the widget. */
+    private cardFieldOrder;
+    private cardAutoFocus;
+    private readonly listeners;
+    constructor(config?: PciVaultCardCaptureConfig);
+    mount(container: HTMLElement, options: CardCaptureMountOptions): Promise<void>;
+    on(event: CardCaptureEventType, handler: (event: CardCaptureOutcomeEvent) => void): () => void;
+    unmount(): void;
+    /**
+     * Inject the server-rendered widget HTML. `innerHTML` does not execute
+     * embedded `<script>` tags, so each script node is replaced with a freshly
+     * created element that the browser will load and run (this is what boots the
+     * PCIVault form bundle against the `data-flopay-config` container).
+     */
+    private injectWidget;
+    private attachMessageListener;
+    /**
+     * Push merchant theme colors into the hosted widget (live). The host calls
+     * this on a runtime theme switch; the widget applies them to its CSS variables
+     * without a remount. Stores the latest theme so `ready` can re-push it.
+     */
+    applyTheme(theme: VaultCardThemeColors): void;
+    /** postMessage the current theme to the widget's (cross-origin) document. */
+    private postTheme;
+    /**
+     * Gate the widget's submit from the host. When `blocked`, the widget cancels
+     * its next submit and emits `'blocked'` instead of `'submitting'` so the host
+     * can validate merchant-DOM fields (AVS) first. Stored so `ready` re-pushes it.
+     */
+    setSubmitGate(blocked: boolean): void;
+    /** postMessage the current submit-gate state to the widget's document. */
+    private postSubmitGate;
+    /**
+     * Push the card-field order + autofocus directive into the widget (live). The
+     * widget re-sequences its rows (DOM order, so tab order follows) and focuses
+     * its first field unless `autoFocus` is false. Stored so `ready` re-pushes it.
+     */
+    setCardFieldOrder(order: VaultCardFieldKey[] | null, autoFocus: boolean): void;
+    /** postMessage the current field order + autofocus to the widget's document. */
+    private postCardFieldOrder;
+    private emit;
+    /**
+     * Render the provider-hosted verification challenge (e.g. Stripe 3DS-2) in a
+     * full-page overlay at the PARENT page level. The widget's inline-iframe
+     * approach is unusable because the SDK's processing backdrop sits above the
+     * vault iframe, hiding any challenge mounted inside it — by lifting the
+     * iframe to the host page the adapter can give it a z-index that wins.
+     *
+     * The overlay tears down on the next terminal outcome
+     * (`complete`/`decline`/`error`) or when the buyer closes it via the backdrop
+     * close button. Closing manually is a soft abandon — the next `/status` poll
+     * either reveals a real outcome (the challenge completed via the issuer's
+     * own redirect to `/vault/3ds/return`, which posts back into the widget) or
+     * surfaces `requires_action` again so the host can decide what to do.
+     */
+    private showActionRequiredOverlay;
+    /**
+     * Tell the vault widget that the buyer has completed (or abandoned) the
+     * challenge. The widget responds by POSTing `/3ds/complete` — its
+     * sub-300ms sync resolver writes the follow-up attempt row immediately,
+     * so the next `/status` poll resolves to a terminal outcome instead of
+     * waiting for the eventual provider webhook.
+     */
+    private postActionCompleted;
+    private hideActionRequiredOverlay;
+    /**
+     * Size the hosted-widget iframe to the height reported by the form inside it.
+     * Cross-origin iframes don't auto-size to their content, so the widget posts
+     * its measured height and we apply it here (clamped to a sane range). This is
+     * what lets the card form shrink/grow to fit instead of sitting at a fixed
+     * height.
+     */
+    private applyHeight;
+}
+
 /**
  * Creates a checkout session via the billing API and redirects the user
  * to the hosted checkout page.
@@ -473,4 +697,4 @@ declare function createCheckoutSessionWithRetries(options: CreateSessionParams &
     maxRetries?: number;
 }): Promise<CheckoutSessionResult>;
 
-export { FloPay, FloPayElements, PaymentAPI, type SessionDisplayCacheData, type SessionDisplayProduct, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };
+export { FloPay, FloPayElements, PaymentAPI, PciVaultCardCapture, type PciVaultCardCaptureConfig, type SessionDisplayCacheData, type SessionDisplayProduct, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };