@flopay/js 1.2.7 → 1.3.0

package/dist/index.mjs

@@ -1,8 +1,8 @@
 // src/load.ts
-import { FloPayError as FloPayError5 } from "@flopay/shared";
+import { FloPayError as FloPayError6 } from "@flopay/shared";
 
 // src/stripe-adapter.ts
-import { FloPayError } from "@flopay/shared";
+import { FloPayError, isSetupIntentClientSecret } from "@flopay/shared";
 function toStripeElementType(type) {
   const map = {
     payment: "payment",
@@ -100,18 +100,27 @@ var StripeAdapter = class {
     const nextAppearanceKey = stripeAppearance ? JSON.stringify(stripeAppearance) : null;
     if (!this.elements) {
       let elementsOptions;
+      const deferredAmount = options?.amount ?? 0;
+      const deferredCurrency = (options?.currency ?? "usd").toLowerCase();
+      const paymentMethodCreation = options?.paymentMethodCreation ?? "manual";
       if (options?.clientSecret) {
         elementsOptions = { clientSecret: options.clientSecret };
-      } else {
+      } else if (deferredAmount > 0) {
         elementsOptions = {
           mode: "payment",
-          amount: options?.amount ?? 0,
-          currency: (options?.currency ?? "usd").toLowerCase(),
-          paymentMethodCreation: options?.paymentMethodCreation ?? "manual"
+          amount: deferredAmount,
+          currency: deferredCurrency,
+          paymentMethodCreation
         };
         if (options?.setupFutureUsage) {
           elementsOptions["setupFutureUsage"] = options.setupFutureUsage;
         }
+      } else {
+        elementsOptions = {
+          mode: "setup",
+          currency: deferredCurrency,
+          paymentMethodCreation
+        };
       }
       if (stripeAppearance) {
         elementsOptions["appearance"] = stripeAppearance;
@@ -218,6 +227,27 @@ var StripeAdapter = class {
         error: new FloPayError("Stripe not initialized", "api_error")
       };
     }
+    if (isSetupIntentClientSecret(params.clientSecret)) {
+      const { error: setupError, setupIntent } = await this.stripe.confirmCardSetup(
+        params.clientSecret,
+        { payment_method: params.paymentMethodId }
+      );
+      if (setupError) {
+        return {
+          status: "failed",
+          error: new FloPayError(
+            setupError.message ?? "Payment failed",
+            "api_error",
+            { code: setupError.code, declineCode: setupError.decline_code }
+          )
+        };
+      }
+      return {
+        status: setupIntent?.status ?? "failed",
+        paymentIntentId: setupIntent?.id,
+        paymentMethodId: this.extractPaymentMethodId(setupIntent?.payment_method)
+      };
+    }
     const { error, paymentIntent } = await this.stripe.confirmCardPayment(
       params.clientSecret,
       { payment_method: params.paymentMethodId }
@@ -431,7 +461,7 @@ var StripeAdapter = class {
 };
 
 // src/flopay.ts
-import { FloPayError as FloPayError4, resolveBillingApiUrl } from "@flopay/shared";
+import { FloPayError as FloPayError5, resolveBillingApiUrl } from "@flopay/shared";
 
 // src/elements.ts
 import "@flopay/shared";
@@ -486,6 +516,7 @@ var FloPayElements = class {
 import {
   FloPayError as FloPayError3,
   SDK_VERSION,
+  FLO_SDK_VERSION_HEADER,
   buildProductPayload,
   foldIntoProducts,
   resolveSessionCurrency
@@ -621,9 +652,11 @@ var PaymentAPI = class {
    * Backends that don't yet enforce it ignore the extra header.
    */
   async getCheckoutSession(checkoutSessionId, nonce) {
+    const headers = { [FLO_SDK_VERSION_HEADER]: SDK_VERSION };
+    if (nonce) headers["x-checkout-session-token"] = nonce;
     const response = await fetchWithNetworkRetry(
       `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
-      nonce ? { headers: { "x-checkout-session-token": nonce } } : void 0
+      { headers }
     );
     if (!response.ok) {
       throw await buildApiErrorFromResponse(response, "Failed to get checkout session");
@@ -660,6 +693,43 @@ var PaymentAPI = class {
   clearSessionDisplayData(sessionId) {
     clearSessionDisplayData(sessionId);
   }
+  /**
+   * 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).
+   */
+  async getVaultCapture(checkoutSessionId, nonce) {
+    const headers = { "Content-Type": "application/json" };
+    if (nonce) headers["x-checkout-session-token"] = nonce;
+    const response = await fetchWithNetworkRetry(
+      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}/vault/capture`,
+      { method: "POST", headers }
+    );
+    if (!response.ok) {
+      throw await buildApiErrorFromResponse(response, "Failed to load the secure card form");
+    }
+    const block = await response.json();
+    return this.toVaultBlock(block);
+  }
   /**
    * Fetch and normalize a checkout session.
    *
@@ -669,7 +739,12 @@ var PaymentAPI = class {
    */
   async getUnifiedCheckoutSession(checkoutSessionId, nonce) {
     const res = await this.getCheckoutSession(checkoutSessionId, nonce);
-    return this.normalizeRawSession(res.data);
+    const normalized = this.normalizeRawSession(res.data);
+    const vault = res.vault;
+    if (vault && normalized.data.session) {
+      normalized.data.session.vault = this.toVaultBlock(vault);
+    }
+    return normalized;
   }
   /**
    * Submit a tokenized payment to the billing backend.
@@ -710,6 +785,43 @@ var PaymentAPI = class {
     );
     return this.resolveProcessResponse(response, data.sessionId, { ...options, nonce });
   }
+  /**
+   * 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.
+   */
+  async patchAccountSnapshot(sessionId, nonce, body) {
+    const response = await fetchWithNetworkRetry(
+      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/account`,
+      {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+          "x-checkout-session-token": nonce
+        },
+        body: JSON.stringify(body)
+      }
+    );
+    if (!response.ok) {
+      throw await buildApiErrorFromResponse(response, "Failed to persist account snapshot");
+    }
+  }
   /**
    * Create a PaymentIntent on the backend.
    *
@@ -720,6 +832,13 @@ var PaymentAPI = class {
    * 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.
    */
   async createPaymentIntent(sessionId, email, paymentMethodType, options) {
     const headers = { "Content-Type": "application/json" };
@@ -732,7 +851,7 @@ var PaymentAPI = class {
         body: JSON.stringify({
           sessionId,
           email,
-          paymentMethodType,
+          paymentMethodType: paymentMethodType ?? null,
           isPaypal: options?.isPaypal ?? false
         }),
         signal: options?.signal
@@ -841,7 +960,13 @@ var PaymentAPI = class {
       `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
       {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        // Declare the SDK version so backends at TeamFloPay/backend#823 embed
+        // the hosted vault capture block (`body.vault`) in the response for
+        // SDKs ≥ 1.3.0. Older backends ignore the header.
+        headers: {
+          "Content-Type": "application/json",
+          [FLO_SDK_VERSION_HEADER]: SDK_VERSION
+        },
         body: JSON.stringify(payload)
       }
     );
@@ -859,8 +984,12 @@ var PaymentAPI = class {
     if (body.data && "gateways" in body.data) {
       this.autoCacheDisplayData(body.data.uuid, params);
       const merged = this.mergeCachedDisplayData(body.data);
+      const normalized = this.normalizeRawSession(merged);
+      if (body.vault && normalized.data.session) {
+        normalized.data.session.vault = this.toVaultBlock(body.vault);
+      }
       return {
-        ...this.normalizeRawSession(merged),
+        ...normalized,
         autoProcessingError: body.autoProcessingError,
         autoProcessingAttempted: body.autoProcessingAttempted,
         autoProcessingPending: body.autoProcessingPending
@@ -979,6 +1108,7 @@ var PaymentAPI = class {
       },
       metadata: {},
       checkoutMode: raw.checkoutMode,
+      providerPaymentMethodId: typeof raw.providerPaymentMethodId === "string" ? raw.providerPaymentMethodId : null,
       products: rawProducts.map((p) => ({
         ...p,
         totalAmount: typeof p.totalAmount === "number" ? p.totalAmount : void 0,
@@ -998,6 +1128,19 @@ var PaymentAPI = class {
       tagsData: raw.tagsData
     };
   }
+  /**
+   * 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).
+   */
+  toVaultBlock(raw) {
+    return {
+      html: typeof raw.html === "string" ? raw.html : void 0,
+      url: typeof raw.url === "string" ? raw.url : void 0,
+      messageToken: typeof raw.messageToken === "string" ? raw.messageToken : void 0,
+      expectedOrigin: typeof raw.expectedOrigin === "string" ? raw.expectedOrigin : void 0
+    };
+  }
   toCheckoutSessionStatus(status) {
     if (status === "completed") {
       return "complete";
@@ -1112,6 +1255,378 @@ var PaymentAPI = class {
   }
 };
 
+// src/pci-vault-card-capture.ts
+import { FloPayError as FloPayError4 } from "@flopay/shared";
+var VAULT_MESSAGE_SOURCE = "flopay-vault";
+function addBreadcrumb(message, data) {
+  const sentry = globalThis.Sentry;
+  sentry?.addBreadcrumb?.({ category: "flopay.card-capture", level: "info", message, data });
+}
+function isVaultResultMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record["source"] === VAULT_MESSAGE_SOURCE && (record["type"] === "ready" || record["type"] === "submitting" || record["type"] === "blocked" || record["type"] === "complete" || record["type"] === "decline" || record["type"] === "error" || record["type"] === "action_required");
+}
+function isVaultValidationMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record["source"] === VAULT_MESSAGE_SOURCE && record["type"] === "validation" && Array.isArray(record["messages"]);
+}
+function isVaultResizeMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record["source"] === VAULT_MESSAGE_SOURCE && record["type"] === "resize" && typeof record["height"] === "number" && Number.isFinite(record["height"]);
+}
+var PciVaultCardCapture = class {
+  constructor(config = {}) {
+    this.provider = "pcivault";
+    this.container = null;
+    this.messageHandler = null;
+    /**
+     * 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.
+     */
+    this.actionOverlay = null;
+    /**
+     * 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.
+     */
+    this.threeDsReturnHandler = null;
+    /** Per-session integrity token to require on outcomes (from mount options). */
+    this.messageToken = null;
+    /** Strict origin to require on outcomes, when configured. */
+    this.expectedOrigin = null;
+    /** Latest merchant theme to push into the (cross-origin) widget. */
+    this.theme = null;
+    /** Latest host submit-gate state to push into the widget (block its submit). */
+    this.submitGateBlocked = false;
+    /** Latest card-field order + autofocus directive to push into the widget. */
+    this.cardFieldOrder = null;
+    this.cardAutoFocus = true;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.config = config;
+  }
+  async mount(container, options) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      throw new FloPayError4(
+        "The vault card form is only available in the browser.",
+        "api_error",
+        { code: "card_capture_no_window" }
+      );
+    }
+    if (!options?.html || !options.html.trim()) {
+      throw new FloPayError4(
+        "No vault capture widget HTML was provided to mount the secure card form.",
+        "api_error",
+        { code: "card_capture_no_widget_html" }
+      );
+    }
+    this.container = container;
+    this.messageToken = options.messageToken ?? null;
+    this.expectedOrigin = options.expectedOrigin ?? this.config.expectedOrigin ?? null;
+    this.theme = options.theme ?? null;
+    this.attachMessageListener();
+    this.injectWidget(container, options.html);
+    this.postTheme();
+    this.postSubmitGate();
+    this.postCardFieldOrder();
+    addBreadcrumb("vault widget mounted", { sessionId: this.config.sessionId });
+    this.emit("ready", { sessionId: this.config.sessionId });
+  }
+  on(event, handler) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      this.listeners.get(event)?.delete(handler);
+    };
+  }
+  unmount() {
+    this.hideActionRequiredOverlay();
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+    if (this.container) {
+      this.container.replaceChildren();
+      this.container = null;
+    }
+    this.messageToken = null;
+    this.expectedOrigin = null;
+  }
+  // ── internals ──
+  /**
+   * 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).
+   */
+  injectWidget(container, html) {
+    container.innerHTML = html;
+    const scripts = Array.from(container.querySelectorAll("script"));
+    for (const oldScript of scripts) {
+      const script = document.createElement("script");
+      for (const attr of Array.from(oldScript.attributes)) {
+        script.setAttribute(attr.name, attr.value);
+      }
+      script.text = oldScript.text;
+      oldScript.replaceWith(script);
+    }
+  }
+  attachMessageListener() {
+    if (this.messageHandler) return;
+    const handler = (event) => {
+      if (this.expectedOrigin && event.origin !== this.expectedOrigin) return;
+      const data = event.data;
+      if (isVaultResizeMessage(data)) {
+        if (this.messageToken && data.messageToken !== this.messageToken) return;
+        this.applyHeight(data.height);
+        return;
+      }
+      if (isVaultValidationMessage(data)) {
+        if (this.messageToken && data.messageToken !== this.messageToken) return;
+        const text = data.messages.filter((m) => typeof m === "string" && m.trim()).join(" ");
+        this.emit("validation", { sessionId: this.config.sessionId, message: text || void 0 });
+        return;
+      }
+      if (!isVaultResultMessage(data)) return;
+      if (this.messageToken && data.messageToken !== this.messageToken) return;
+      const boundSession = this.config.sessionId;
+      const incomingSession = typeof data.sessionId === "string" ? data.sessionId : void 0;
+      if (boundSession && incomingSession && incomingSession !== boundSession) {
+        return;
+      }
+      if ((data.type === "complete" || data.type === "decline") && boundSession && incomingSession !== boundSession) {
+        return;
+      }
+      const outcome = {
+        sessionId: data.sessionId ?? this.config.sessionId,
+        intentId: data.intentId,
+        declineReason: data.declineReason,
+        message: data.message,
+        nextActionRedirectUrl: data.nextActionRedirectUrl
+      };
+      addBreadcrumb(`vault widget ${data.type}`, {
+        sessionId: outcome.sessionId,
+        declineReason: outcome.declineReason
+      });
+      if (data.type === "ready") {
+        this.postTheme();
+        this.postSubmitGate();
+        this.postCardFieldOrder();
+      }
+      if (data.type === "action_required" && data.nextActionRedirectUrl) {
+        this.showActionRequiredOverlay(data.nextActionRedirectUrl);
+      }
+      if (data.type === "complete" || data.type === "decline" || data.type === "error" || data.type === "submitting") {
+        this.hideActionRequiredOverlay();
+      }
+      this.emit(data.type, outcome);
+    };
+    this.messageHandler = handler;
+    window.addEventListener("message", handler);
+  }
+  /**
+   * 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) {
+    this.theme = theme;
+    this.postTheme();
+  }
+  /** postMessage the current theme to the widget's (cross-origin) document. */
+  postTheme() {
+    if (!this.theme || !this.container) return;
+    const iframe = this.container.querySelector("iframe");
+    const target = iframe?.contentWindow;
+    if (!target) return;
+    try {
+      target.postMessage({ source: "flopay-vault-host", type: "theme", theme: this.theme }, "*");
+    } catch {
+    }
+  }
+  /**
+   * 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) {
+    this.submitGateBlocked = blocked;
+    this.postSubmitGate();
+  }
+  /** postMessage the current submit-gate state to the widget's document. */
+  postSubmitGate() {
+    if (!this.container) return;
+    const iframe = this.container.querySelector("iframe");
+    const target = iframe?.contentWindow;
+    if (!target) return;
+    try {
+      target.postMessage(
+        { source: "flopay-vault-host", type: "gate", blocked: this.submitGateBlocked },
+        "*"
+      );
+    } catch {
+    }
+  }
+  /**
+   * 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, autoFocus) {
+    this.cardFieldOrder = order;
+    this.cardAutoFocus = autoFocus;
+    this.postCardFieldOrder();
+  }
+  /** postMessage the current field order + autofocus to the widget's document. */
+  postCardFieldOrder() {
+    if (!this.container) return;
+    const iframe = this.container.querySelector("iframe");
+    const target = iframe?.contentWindow;
+    if (!target) return;
+    try {
+      target.postMessage(
+        {
+          source: "flopay-vault-host",
+          type: "fieldOrder",
+          order: this.cardFieldOrder,
+          autoFocus: this.cardAutoFocus
+        },
+        "*"
+      );
+    } catch {
+    }
+  }
+  emit(event, payload) {
+    for (const handler of this.listeners.get(event) ?? []) {
+      handler(payload);
+    }
+  }
+  /**
+   * 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.
+   */
+  showActionRequiredOverlay(challengeUrl) {
+    if (typeof document === "undefined") return;
+    if (this.actionOverlay) {
+      const existingIframe = this.actionOverlay.querySelector("iframe");
+      if (existingIframe instanceof HTMLIFrameElement) {
+        existingIframe.src = challengeUrl;
+      }
+      return;
+    }
+    const backdrop = document.createElement("div");
+    backdrop.setAttribute("data-flopay-action-required", "1");
+    backdrop.style.cssText = [
+      "position:fixed",
+      "inset:0",
+      // Maximum signed 32-bit z-index; the SDK's own processing backdrop sits
+      // well below this so the challenge is visible and interactive.
+      "z-index:2147483647",
+      "background:rgba(15,23,42,0.6)",
+      "display:flex",
+      "align-items:center",
+      "justify-content:center",
+      "padding:16px"
+    ].join(";");
+    const frame = document.createElement("iframe");
+    frame.setAttribute("title", "Card authentication");
+    frame.setAttribute("allow", "payment");
+    frame.style.cssText = [
+      "width:min(100%,460px)",
+      "height:min(100%,640px)",
+      "border:0",
+      "border-radius:12px",
+      "background:#fff",
+      "box-shadow:0 12px 30px rgba(0,0,0,0.35)"
+    ].join(";");
+    frame.src = challengeUrl;
+    backdrop.appendChild(frame);
+    const returnHandler = (event) => {
+      if (event.source !== frame.contentWindow) return;
+      const data = event.data;
+      if (!data || typeof data !== "object") return;
+      const record = data;
+      if (record["source"] !== "flopay-vault-3ds-return") return;
+      this.hideActionRequiredOverlay();
+      this.postActionCompleted(record["status"]);
+    };
+    window.addEventListener("message", returnHandler);
+    this.threeDsReturnHandler = returnHandler;
+    document.body.appendChild(backdrop);
+    this.actionOverlay = backdrop;
+    addBreadcrumb("vault 3ds challenge overlay shown");
+  }
+  /**
+   * 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.
+   */
+  postActionCompleted(status) {
+    if (!this.container) return;
+    const iframe = this.container.querySelector("iframe");
+    const target = iframe?.contentWindow;
+    if (!target) return;
+    try {
+      target.postMessage(
+        {
+          source: "flopay-vault-host",
+          type: "action_completed",
+          status: typeof status === "string" ? status : "unknown"
+        },
+        "*"
+      );
+    } catch {
+    }
+  }
+  hideActionRequiredOverlay() {
+    if (this.threeDsReturnHandler) {
+      window.removeEventListener("message", this.threeDsReturnHandler);
+      this.threeDsReturnHandler = null;
+    }
+    if (!this.actionOverlay) return;
+    this.actionOverlay.parentNode?.removeChild(this.actionOverlay);
+    this.actionOverlay = null;
+    addBreadcrumb("vault 3ds challenge overlay hidden");
+  }
+  /**
+   * 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.
+   */
+  applyHeight(height) {
+    const iframe = this.container?.querySelector("iframe");
+    if (!iframe) return;
+    const clamped = Math.max(0, Math.min(Math.ceil(height), 2e3));
+    iframe.style.height = `${clamped}px`;
+  }
+};
+
 // src/flopay.ts
 var FloPay = class {
   constructor(provider, config) {
@@ -1147,6 +1662,23 @@ var FloPay = class {
   async confirmCardPayment(params) {
     return this.provider.confirmCardPayment(params);
   }
+  /**
+   * 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) {
+    return new PciVaultCardCapture({
+      sessionId: options?.sessionId
+    });
+  }
   /** Confirm a PayPal payment: create intent via billing API → confirm → redirect if needed. */
   async confirmPayPalPayment(params) {
     return this.provider.confirmPayPalPayment(params);
@@ -1170,7 +1702,7 @@ var FloPay = class {
    */
   async retrieveSession(sessionId, billingApiUrl) {
     if (!sessionId) {
-      throw new FloPayError4(
+      throw new FloPayError5(
         "sessionId is required to retrieve a session.",
         "validation_error",
         { param: "sessionId" }
@@ -1180,7 +1712,7 @@ var FloPay = class {
     const api = new PaymentAPI(apiUrl);
     const unified = await api.getUnifiedCheckoutSession(sessionId);
     if (!unified.data.session) {
-      throw new FloPayError4("Session not found", "api_error");
+      throw new FloPayError5("Session not found", "api_error");
     }
     return unified.data.session;
   }
@@ -1193,7 +1725,7 @@ var FloPay = class {
    */
   async retrieveUnifiedSession(sessionId, billingApiUrl) {
     if (!sessionId) {
-      throw new FloPayError4(
+      throw new FloPayError5(
         "sessionId is required.",
         "validation_error",
         { param: "sessionId" }
@@ -1223,7 +1755,7 @@ var FloPay = class {
 var instanceCache = /* @__PURE__ */ new Map();
 async function loadFloPay(publishableKey, options) {
   if (!publishableKey) {
-    throw new FloPayError5(
+    throw new FloPayError6(
       "A publishable key is required to initialize FloPay.",
       "validation_error",
       { param: "publishableKey" }
@@ -1244,7 +1776,7 @@ async function loadFloPay(publishableKey, options) {
 
 // src/create-checkout-session.ts
 import {
-  FloPayError as FloPayError6,
+  FloPayError as FloPayError7,
   SDK_VERSION as SDK_VERSION2,
   buildProductPayload as buildProductPayload2,
   foldIntoProducts as foldIntoProducts2,
@@ -1258,7 +1790,7 @@ function buildCheckoutSessionError(status, payload) {
   const nested = payload?.error;
   const code = readString2(payload?.code) ?? readString2(nested?.code) ?? `http_${status}`;
   const message = readString2(payload?.message) ?? readString2(nested?.message) ?? defaultMessageForCode(code, status);
-  return new FloPayError6(message, "api_error", { code, statusCode: status });
+  return new FloPayError7(message, "api_error", { code, statusCode: status });
 }
 function defaultMessageForCode(code, status) {
   switch (code) {
@@ -1291,7 +1823,7 @@ async function createCheckoutSession(options) {
     utmMetadata
   } = options;
   if (couponCodes.length > MAX_COUPON_CODES) {
-    throw new FloPayError6(
+    throw new FloPayError7(
       `Too many coupon codes \u2014 a checkout session accepts at most ${MAX_COUPON_CODES}.`,
       "validation_error",
       { code: "CouponLimitExceeded", param: "couponCodes" }
@@ -1300,7 +1832,7 @@ async function createCheckoutSession(options) {
   const wireProducts = products ?? foldIntoProducts2(items, subscriptions);
   const sessionCurrency = resolveSessionCurrency2(currency, items, subscriptions, wireProducts);
   if (!sessionCurrency) {
-    throw new FloPayError6(
+    throw new FloPayError7(
       "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
       "validation_error",
       { code: "CurrencyRequired", param: "currency" }
@@ -1365,7 +1897,7 @@ async function createCheckoutSession(options) {
       throw new Error("Checkout session created but no UUID was returned by the billing API");
     }
     if (!nonce) {
-      throw new FloPayError6(
+      throw new FloPayError7(
         "Checkout session created but no `nonce` was returned by the billing API. Upgrade the billing service to TeamFloPay/backend#640 or later.",
         "api_error",
         { code: "MissingCheckoutSessionToken" }
@@ -1432,6 +1964,7 @@ export {
   FloPay,
   FloPayElements,
   PaymentAPI,
+  PciVaultCardCapture,
   StripeAdapter,
   cacheSessionDisplayData,
   clearSessionDisplayData,