@flopay/js 1.4.1 → 1.4.2

package/dist/index.mjs

@@ -3,2185 +3,2199 @@ import { FloPayError as FloPayError6, resolveBillingApiUrl as resolveBillingApiU
 
 // src/stripe-adapter.ts
 import { loadStripe } from "@stripe/stripe-js";
-import { FloPayError, isSetupIntentClientSecret } from "@flopay/shared";
+import { FloPayError as FloPayError2, isSetupIntentClientSecret } from "@flopay/shared";
 
-// src/card-three-ds.ts
-var CARD_THREE_DS_ATTEMPT_TTL_MS = 15 * 6e4;
-var MAX_CARD_THREE_DS_ATTEMPTS = 32;
+// src/payment-api.ts
+import {
+  FloPayError,
+  SDK_VERSION,
+  FLO_SDK_VERSION_HEADER,
+  IDEMPOTENCY_KEY_HEADER,
+  IDEMPOTENCY_IN_PROGRESS_CODE,
+  buildProductPayload,
+  foldIntoProducts,
+  isUuidV4,
+  randomUuidV4,
+  resolveIdempotencyKey,
+  resolveSessionCurrency
+} from "@flopay/shared";
 
-// src/stripe-adapter.ts
-function toStripeElementType(type) {
-  const map = {
-    payment: "payment",
-    card: "card",
-    cardNumber: "cardNumber",
-    cardExpiry: "cardExpiry",
-    cardCvc: "cardCvc",
-    address: "address"
-  };
-  return map[type];
+// src/api-error.ts
+function readErrorString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
 }
-function toStripeAppearanceTheme(theme) {
-  switch (theme) {
-    case "night":
-      return "night";
-    case "flat":
-      return "flat";
-    // 'default', 'none', undefined, or any unexpected value → Stripe's baseline.
-    default:
-      return "stripe";
+function readErrorMessage(value) {
+  if (typeof value === "string") return value.trim() ? value : void 0;
+  if (Array.isArray(value)) {
+    const joined = value.filter((entry) => typeof entry === "string" && entry.trim().length > 0).join("; ");
+    return joined || void 0;
   }
+  return void 0;
 }
-function cardThreeDsNow() {
-  return globalThis.performance?.now() ?? Date.now();
-}
-function wrapStripeElement(stripeElement) {
-  const el = stripeElement;
-  return {
-    mount(container) {
-      el.mount(container);
-    },
-    unmount() {
-      el.unmount();
-    },
-    update(options) {
-      el.update(options);
-    },
-    on(event, handler) {
-      el["on"]?.(event, handler);
-    },
-    off(event, handler) {
-      el["off"]?.(event, handler);
-    },
-    destroy() {
-      el.destroy();
-    }
-  };
-}
-function toStripeBillingDetails(billing) {
-  return {
-    billing_details: {
-      ...billing.email ? { email: billing.email } : {},
-      ...billing.name ? { name: billing.name } : {},
-      ...billing.address ? {
-        address: {
-          ...billing.address.country ? { country: billing.address.country } : {},
-          ...billing.address.postal_code ? { postal_code: billing.address.postal_code } : {},
-          ...billing.address.city ? { city: billing.address.city } : {},
-          ...billing.address.line1 ? { line1: billing.address.line1 } : {},
-          ...billing.address.line2 ? { line2: billing.address.line2 } : {},
-          ...billing.address.state ? { state: billing.address.state } : {}
-        }
-      } : {}
-    }
-  };
+
+// src/session-display-cache.ts
+var STORAGE_KEY_PREFIX = "flopay_session_display:";
+var DEFAULT_TTL_MS = 60 * 60 * 1e3;
+var memoryStore = /* @__PURE__ */ new Map();
+function storageKey(sessionId) {
+  return `${STORAGE_KEY_PREFIX}${sessionId}`;
 }
-var StripeAdapter = class {
-  constructor() {
-    this.name = "stripe";
-    this.stripe = null;
-    this.elements = null;
-    this.pendingCardThreeDsAttempts = /* @__PURE__ */ new Map();
-    this.cardThreeDsAttemptSequence = 0;
-    // Serialized appearance currently applied to `this.elements`. Used to detect
-    // when consumers swap themes mid-session so we can live-update the Stripe
-    // Elements group instead of returning a stale-styled cache. `null` while no
-    // elements group exists.
-    this.appliedAppearanceKey = null;
+function getSessionStorage() {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
   }
-  async initialize(config) {
-    if (typeof window === "undefined") {
+}
+function cacheSessionDisplayData(sessionId, data, options) {
+  if (!sessionId) return;
+  const ttl = options?.ttlMs ?? DEFAULT_TTL_MS;
+  const entry = { data, expiresAt: Date.now() + ttl };
+  const storage = getSessionStorage();
+  if (storage) {
+    try {
+      storage.setItem(storageKey(sessionId), JSON.stringify(entry));
       return;
+    } catch {
     }
-    const stripe = await loadStripe(config.publishableKey, {
-      locale: config.locale ?? "auto"
-    });
-    if (!stripe) {
-      throw new FloPayError(
-        "Failed to initialize Stripe. Check your publishable key.",
-        "authentication_error"
-      );
-    }
-    this.stripe = stripe;
   }
-  /** Lazily creates the Stripe Elements group for the given options. */
-  getElements(options) {
-    if (!this.stripe) {
-      throw new FloPayError(
-        "StripeAdapter not initialized. Call initialize() first.",
-        "api_error"
-      );
-    }
-    const stripeAppearance = options?.appearance ? {
-      theme: toStripeAppearanceTheme(options.appearance.theme),
-      variables: options.appearance.variables,
-      rules: options.appearance.rules
-    } : void 0;
-    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 if (deferredAmount > 0) {
-        elementsOptions = {
-          mode: "payment",
-          amount: deferredAmount,
-          currency: deferredCurrency,
-          paymentMethodCreation
-        };
-        if (options?.setupFutureUsage) {
-          elementsOptions["setupFutureUsage"] = options.setupFutureUsage;
+  memoryStore.set(sessionId, entry);
+}
+function getSessionDisplayData(sessionId) {
+  if (!sessionId) return null;
+  const storage = getSessionStorage();
+  if (storage) {
+    try {
+      const raw = storage.getItem(storageKey(sessionId));
+      if (raw) {
+        const entry = JSON.parse(raw);
+        if (entry && typeof entry.expiresAt === "number" && entry.expiresAt > Date.now()) {
+          return entry.data;
         }
-      } else {
-        elementsOptions = {
-          mode: "setup",
-          currency: deferredCurrency,
-          paymentMethodCreation
-        };
-      }
-      if (stripeAppearance) {
-        elementsOptions["appearance"] = stripeAppearance;
+        storage.removeItem(storageKey(sessionId));
       }
-      this.elements = this.stripe.elements(elementsOptions);
-      this.appliedAppearanceKey = nextAppearanceKey;
-    } else if (nextAppearanceKey !== this.appliedAppearanceKey) {
-      this.elements.update({
-        appearance: stripeAppearance ?? {}
-      });
-      this.appliedAppearanceKey = nextAppearanceKey;
-    }
-    return this.elements;
-  }
-  async createElement(type, options) {
-    const elements = this.getElements(options);
-    const stripeType = toStripeElementType(type);
-    const elementOptions = {};
-    if (options.layout) {
-      elementOptions["layout"] = options.layout;
-    }
-    if (options.defaultValues) {
-      elementOptions["defaultValues"] = options.defaultValues;
-    }
-    if (options.readOnly) {
-      elementOptions["readOnly"] = options.readOnly;
-    }
-    if (options.mode) {
-      elementOptions["mode"] = options.mode;
-    }
-    if (options.style) {
-      elementOptions["style"] = options.style;
+    } catch {
     }
-    const stripeElement = elements.create(stripeType, elementOptions);
-    return wrapStripeElement(stripeElement);
-  }
-  getElement(type) {
-    if (!this.elements) return null;
-    const stripeType = toStripeElementType(type);
-    const existing = this.elements.getElement(stripeType);
-    if (!existing) return null;
-    return wrapStripeElement(existing);
   }
-  async submitElements() {
-    if (!this.stripe || !this.elements) {
-      return { error: new FloPayError("Stripe not initialized", "api_error") };
-    }
-    const { error } = await this.elements.submit();
-    if (error) {
-      return {
-        error: new FloPayError(error.message ?? "Validation failed", "validation_error")
-      };
+  const memEntry = memoryStore.get(sessionId);
+  if (memEntry) {
+    if (memEntry.expiresAt > Date.now()) {
+      return memEntry.data;
     }
-    return {};
+    memoryStore.delete(sessionId);
   }
-  async createPaymentMethod(billingDetails) {
-    if (!this.stripe || !this.elements) {
-      return {
-        paymentMethodId: null,
-        error: new FloPayError("Stripe not initialized", "api_error")
-      };
-    }
-    const cardNumberEl = this.elements.getElement("cardNumber");
-    const stripeBilling = billingDetails ? toStripeBillingDetails(billingDetails) : {};
-    const { error, paymentMethod } = cardNumberEl ? await this.stripe.createPaymentMethod({
-      type: "card",
-      card: cardNumberEl,
-      ...stripeBilling
-    }) : await this.stripe.createPaymentMethod({
-      elements: this.elements,
-      ...stripeBilling
-    });
-    if (error) {
-      return {
-        paymentMethodId: null,
-        error: new FloPayError(
-          error.message ?? "Failed to create payment method",
-          "api_error",
-          { code: error.code }
-        )
-      };
+  return null;
+}
+function clearSessionDisplayData(sessionId) {
+  if (!sessionId) return;
+  memoryStore.delete(sessionId);
+  const storage = getSessionStorage();
+  if (storage) {
+    try {
+      storage.removeItem(storageKey(sessionId));
+    } catch {
     }
-    return { paymentMethodId: paymentMethod.id };
   }
-  async confirmCardPayment(params) {
-    if (!this.stripe) {
-      return {
-        status: "failed",
-        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 this.withCardThreeDsLifecycle(params, {
-          status: "failed",
-          error: new FloPayError(
-            setupError.message ?? "Payment failed",
-            "api_error",
-            { code: setupError.code, declineCode: setupError.decline_code }
-          )
-        });
-      }
-      return this.withCardThreeDsLifecycle(params, {
-        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 }
-    );
-    if (error) {
-      return this.withCardThreeDsLifecycle(params, {
-        status: "failed",
-        error: new FloPayError(
-          error.message ?? "Payment failed",
-          "api_error",
-          { code: error.code, declineCode: error.decline_code }
-        )
-      });
-    }
-    return this.withCardThreeDsLifecycle(params, {
-      status: paymentIntent?.status ?? "failed",
-      paymentIntentId: paymentIntent?.id,
-      paymentMethodId: this.extractPaymentMethodId(paymentIntent?.payment_method)
-    });
-  }
-  /**
-   * Bind provider-observed 3DS milestones to the exact confirmation context.
-   * The sensitive client secret/payment method pair stays only in this private,
-   * in-memory key; callers and telemetry receive an unrelated opaque id.
-   */
-  withCardThreeDsLifecycle(params, result) {
-    const contextKey = `${params.clientSecret}\0${params.paymentMethodId}`;
-    const now = cardThreeDsNow();
-    this.pruneExpiredCardThreeDsAttempts(now);
-    if (result.status === "requires_action") {
-      let attempt2 = this.pendingCardThreeDsAttempts.get(contextKey);
-      if (!attempt2) {
-        while (this.pendingCardThreeDsAttempts.size >= MAX_CARD_THREE_DS_ATTEMPTS) {
-          const oldestContextKey = this.pendingCardThreeDsAttempts.keys().next().value;
-          if (oldestContextKey === void 0) break;
-          this.pendingCardThreeDsAttempts.delete(oldestContextKey);
-        }
-        attempt2 = {
-          attemptId: `card_3ds_${this.cardThreeDsAttemptSequence++}`,
-          startedAt: now
-        };
-        this.pendingCardThreeDsAttempts.set(contextKey, attempt2);
+}
+
+// src/telemetry-reporter.ts
+import {
+  buildTelemetryErrorEvent,
+  buildTelemetryLogEvent,
+  buildTelemetryPerformanceEvent,
+  buildTelemetryTerminalEvent,
+  serializeTelemetryBatch,
+  TELEMETRY_MAX_BATCH_BYTES
+} from "@flopay/shared";
+var TELEMETRY_PATH = "/v1/sdk-telemetry/events";
+var MAX_BATCH_SIZE = 16;
+var MAX_QUEUE_SIZE = 64;
+var UPLOAD_TIMEOUT_MS = 1500;
+var ERROR_DEDUPLICATION_WINDOW_MS = 1e3;
+var MAX_REPORTED_FAILURES = 64;
+var DEDUPLICATION_EVENT_ID = "00000000-0000-4000-8000-000000000000";
+var EVENT_BUDGETS = {
+  technical_error: 8,
+  lifecycle: 32,
+  expected_outcome: 32,
+  performance: 24
+};
+function createUuidV4() {
+  try {
+    return globalThis.crypto.randomUUID();
+  } catch {
+    const bytes = new Uint8Array(16);
+    try {
+      globalThis.crypto.getRandomValues(bytes);
+    } catch {
+      for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Math.floor(Math.random() * 256);
       }
-      return { ...result, threeDs: { attemptId: attempt2.attemptId, status: "handoff" } };
     }
-    const attempt = this.pendingCardThreeDsAttempts.get(contextKey);
-    if (!attempt) return result;
-    this.pendingCardThreeDsAttempts.delete(contextKey);
-    return {
-      ...result,
-      threeDs: {
-        attemptId: attempt.attemptId,
-        status: result.error || result.status === "failed" ? "failed" : "returned"
-      }
-    };
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
   }
-  pruneExpiredCardThreeDsAttempts(now) {
-    for (const [contextKey, attempt] of this.pendingCardThreeDsAttempts) {
-      if (now - attempt.startedAt >= CARD_THREE_DS_ATTEMPT_TTL_MS) {
-        this.pendingCardThreeDsAttempts.delete(contextKey);
-      }
-    }
+}
+function bodyByteLength(body) {
+  try {
+    return new TextEncoder().encode(body).byteLength;
+  } catch {
+    return body.length;
   }
-  async confirmPayment(params) {
-    if (!this.stripe || !this.elements) {
-      throw new FloPayError(
-        "StripeAdapter not initialized or no elements created.",
-        "api_error"
-      );
-    }
-    const billing = params.billingDetails;
-    const paymentMethodData = billing ? toStripeBillingDetails(billing) : void 0;
-    const { error, paymentIntent } = await this.stripe.confirmPayment({
-      elements: this.elements,
-      clientSecret: params.clientSecret,
-      confirmParams: {
-        return_url: params.returnUrl ?? window.location.href,
-        ...paymentMethodData ? { payment_method_data: paymentMethodData } : {}
-      },
-      redirect: "if_required"
-    });
-    if (error) {
-      return {
-        status: "failed",
-        error: new FloPayError(
-          error.message ?? "Payment failed",
-          "api_error",
-          {
-            code: error.code,
-            declineCode: error.decline_code
-          }
-        )
-      };
-    }
-    if (!paymentIntent) {
-      return { status: "failed", error: new FloPayError("No payment intent returned", "api_error") };
-    }
-    const statusMap = {
-      succeeded: "succeeded",
-      processing: "processing",
-      requires_action: "requires_action",
-      requires_payment_method: "failed",
-      canceled: "failed"
+}
+function failureDeduplicationKey(event) {
+  return JSON.stringify([
+    event.code,
+    event.stage,
+    event.provider,
+    event.attempt,
+    event.statusClass,
+    event.requestCategory,
+    event.paymentMethodCategory,
+    event.checkoutMode,
+    event.layout
+  ]);
+}
+function telemetryNow() {
+  return globalThis.performance?.now() ?? 0;
+}
+var TelemetryReporter = class {
+  constructor(options) {
+    this.ingestionDisabled = false;
+    this.queue = [];
+    this.sequence = 0;
+    this.flushTimer = null;
+    this.flushInFlight = null;
+    this.reportedFailures = /* @__PURE__ */ new Map();
+    this.checkoutContext = {};
+    this.checkoutStartedAt = null;
+    this.destroyed = false;
+    this.pageExitHandler = () => {
+      this.drainQueue();
     };
-    return {
-      status: statusMap[paymentIntent.status] ?? "failed",
-      paymentIntentId: paymentIntent.id,
-      paymentMethodId: this.extractPaymentMethodId(paymentIntent.payment_method)
+    this.visibilityHandler = () => {
+      if (document.visibilityState === "hidden") void this.flush();
     };
+    this.eventCounts = {
+      technical_error: 0,
+      lifecycle: 0,
+      expected_outcome: 0,
+      performance: 0
+    };
+    this.endpoint = `${options.billingApiUrl.replace(/\/+$/, "")}${TELEMETRY_PATH}`;
+    this.sdkPackage = options.sdkPackage ?? "@flopay/js";
+    this.sdkVersion = options.sdkVersion;
+    this.correlationId = createUuidV4();
+    this.merchantEnabled = options.enabled !== false;
+    this.clock = options.clock ?? telemetryNow;
+    this.browserTransportAvailable = typeof window !== "undefined" && typeof document !== "undefined";
+    if (this.browserTransportAvailable) {
+      window.addEventListener("pagehide", this.pageExitHandler);
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
   }
-  extractPaymentMethodId(paymentMethod) {
-    if (typeof paymentMethod === "string" && paymentMethod.startsWith("pm_")) {
-      return paymentMethod;
+  log(input) {
+    if (!this.canCollect()) return;
+    this.enqueue(buildTelemetryLogEvent({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+  }
+  error(input) {
+    if (!this.canCollect()) return;
+    const normalizedFailure = buildTelemetryErrorEvent({
+      ...this.checkoutContext,
+      ...input,
+      eventId: DEDUPLICATION_EVENT_ID,
+      sequence: 0
+    });
+    const deduplicationKey = failureDeduplicationKey(normalizedFailure);
+    const now = this.now();
+    this.pruneReportedFailures(now);
+    const previouslyReportedAt = this.reportedFailures.get(deduplicationKey);
+    if (previouslyReportedAt !== void 0 && now >= previouslyReportedAt && now - previouslyReportedAt < ERROR_DEDUPLICATION_WINDOW_MS) {
+      this.log({
+        name: "operation.deduplicated",
+        stage: input.stage,
+        provider: input.provider,
+        paymentMethodCategory: input.paymentMethodCategory,
+        attempt: input.attempt
+      });
+      return;
     }
-    if (paymentMethod && typeof paymentMethod === "object" && typeof paymentMethod.id === "string") {
-      return paymentMethod.id;
+    this.rememberReportedFailure(deduplicationKey, now);
+    this.enqueue(buildTelemetryErrorEvent({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+  }
+  performance(input) {
+    if (!this.canCollect()) return;
+    this.enqueue(buildTelemetryPerformanceEvent({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+  }
+  terminal(input) {
+    if (!this.canCollect()) return;
+    this.enqueue(buildTelemetryTerminalEvent({
+      ...this.checkoutContext,
+      ...input,
+      eventId: createUuidV4(),
+      sequence: this.sequence++
+    }));
+    if (input.outcome !== "action_required" && this.checkoutStartedAt !== null) {
+      const checkoutStartedAt = this.checkoutStartedAt;
+      this.checkoutStartedAt = null;
+      this.performance({
+        stage: "total_journey",
+        durationMs: Math.max(0, this.now() - checkoutStartedAt),
+        durationMode: "total",
+        provider: input.provider,
+        paymentMethodCategory: input.paymentMethodCategory
+      });
     }
-    return void 0;
   }
-  async confirmPayPalPayment(params) {
-    if (!this.stripe) {
-      return { status: "failed", error: new FloPayError("Stripe not initialized", "api_error") };
+  /** @internal Read the reporter's monotonic clock without Resource Timing. */
+  now() {
+    try {
+      return this.clock();
+    } catch {
+      return telemetryNow();
     }
-    const baseUrl = params.billingApiUrl.replace(/\/+$/, "");
-    if (this.elements) {
-      const { error: submitError } = await this.elements.submit();
-      if (submitError) {
-        return {
-          status: "failed",
-          error: new FloPayError(
-            submitError.message ?? "PayPal payment failed",
-            "validation_error",
-            { code: submitError.code }
-          )
-        };
+  }
+  pruneReportedFailures(now) {
+    for (const [key, reportedAt] of this.reportedFailures) {
+      if (now < reportedAt || now - reportedAt >= ERROR_DEDUPLICATION_WINDOW_MS) {
+        this.reportedFailures.delete(key);
       }
     }
-    const intentHeaders = { "Content-Type": "application/json" };
-    if (params.nonce) intentHeaders["x-checkout-session-token"] = params.nonce;
-    const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
-      method: "POST",
-      headers: intentHeaders,
-      body: JSON.stringify({
-        sessionId: params.sessionId,
-        email: params.email,
-        paymentMethodType: "paypal",
-        isPaypal: "true"
-      })
-    });
-    if (!intentResponse.ok) {
-      return { status: "failed", error: new FloPayError("Failed to create PayPal payment intent", "api_error") };
-    }
-    const intentJson = await intentResponse.json();
-    const intentClientSecret = intentJson.data?.id;
-    if (!intentClientSecret) {
-      return { status: "failed", error: new FloPayError("No client_secret in response", "api_error") };
+  }
+  rememberReportedFailure(key, reportedAt) {
+    while (this.reportedFailures.size >= MAX_REPORTED_FAILURES) {
+      const oldest = this.reportedFailures.keys().next();
+      if (oldest.done) break;
+      this.reportedFailures.delete(oldest.value);
     }
-    const { error } = await this.stripe.confirmPayment({
-      clientSecret: intentClientSecret,
-      elements: this.elements ?? void 0,
-      confirmParams: { return_url: params.returnUrl }
-    });
-    if (error) {
-      return {
-        status: "failed",
-        error: new FloPayError(error.message ?? "PayPal payment failed", "api_error", { code: error.code })
-      };
-    }
-    return {
-      status: "processing"
-    };
+    this.reportedFailures.set(key, reportedAt);
   }
-  async resumePayPalPayment() {
-    if (!this.stripe || typeof window === "undefined") return null;
-    const params = new URLSearchParams(window.location.search);
-    const paymentIntentId = params.get("payment_intent");
-    const clientSecret = params.get("payment_intent_client_secret");
-    const redirectStatus = params.get("redirect_status");
-    if (!paymentIntentId || !clientSecret) return null;
-    if (redirectStatus === "failed") {
-      return {
-        status: "failed",
-        error: new FloPayError("PayPal payment was declined. Please try again.", "api_error")
-      };
-    }
-    const { paymentIntent, error } = await this.stripe.retrievePaymentIntent(clientSecret);
-    if (error) {
-      return {
-        status: "failed",
-        error: new FloPayError(error.message ?? "Failed to retrieve PayPal payment", "api_error")
-      };
-    }
-    if (paymentIntent && (paymentIntent.status === "requires_capture" || paymentIntent.status === "succeeded")) {
-      const pmId = typeof paymentIntent.payment_method === "string" ? paymentIntent.payment_method : paymentIntent.payment_method?.id;
-      const url = new URL(window.location.href);
-      url.searchParams.delete("payment_intent");
-      url.searchParams.delete("payment_intent_client_secret");
-      url.searchParams.delete("redirect_status");
-      window.history.replaceState({}, "", url.toString());
-      return {
-        status: paymentIntent.status,
-        paymentIntentId: paymentIntent.id,
-        paymentMethodId: pmId
-      };
-    }
-    return {
-      status: "failed",
-      error: new FloPayError("PayPal payment was not completed. Please try again.", "api_error")
+  /** @internal Add closed checkout dimensions to subsequent SDK events. */
+  setCheckoutContext(context) {
+    this.checkoutContext = {
+      checkoutMode: context.checkoutMode,
+      layout: context.layout
     };
   }
-  getRawProvider() {
-    return this.stripe;
-  }
-  createPayPalElements(options) {
-    if (!this.stripe) return null;
-    const elementsOptions = {
-      mode: "payment",
-      amount: options.amount ?? 0,
-      currency: (options.currency ?? "usd").toLowerCase(),
-      captureMethod: "manual"
+  /** @internal Start a fresh checkout budget, dedupe window, and total span. */
+  beginCheckout(context = {}) {
+    if (!this.canCollect()) return 0;
+    this.drainQueue();
+    this.setCheckoutContext(context);
+    this.sequence = 0;
+    this.reportedFailures.clear();
+    this.eventCounts = {
+      technical_error: 0,
+      lifecycle: 0,
+      expected_outcome: 0,
+      performance: 0
     };
-    if (options.setupFutureUsage) {
-      elementsOptions["setupFutureUsage"] = options.setupFutureUsage;
-    }
-    if (options.appearance) {
-      elementsOptions["appearance"] = {
-        theme: toStripeAppearanceTheme(options.appearance.theme),
-        variables: options.appearance.variables,
-        rules: options.appearance.rules
-      };
+    this.checkoutStartedAt = this.now();
+    return this.checkoutStartedAt;
+  }
+  enqueue(event) {
+    if (!this.canCollect()) return;
+    if (this.queue.length >= MAX_QUEUE_SIZE || this.eventCounts[event.class] >= EVENT_BUDGETS[event.class]) return;
+    this.eventCounts[event.class] += 1;
+    this.queue.push(event);
+    if (this.queue.length >= MAX_BATCH_SIZE) {
+      void this.flush();
+      return;
     }
-    return this.stripe.elements(elementsOptions);
+    this.scheduleFlush();
+  }
+  canCollect() {
+    return this.browserTransportAvailable && this.merchantEnabled && !this.ingestionDisabled && !this.destroyed;
+  }
+  /** Flush one bounded batch. Failures are intentionally dropped. */
+  async flush() {
+    if (this.flushInFlight) return this.flushInFlight;
+    if (!this.browserTransportAvailable || this.destroyed || this.ingestionDisabled || this.queue.length === 0) return;
+    this.clearFlushTimer();
+    const events = this.queue.splice(0, MAX_BATCH_SIZE);
+    this.flushInFlight = this.sendBatch(events).finally(() => {
+      this.flushInFlight = null;
+      if (this.queue.length > 0) this.scheduleFlush();
+    });
+    return this.flushInFlight;
   }
+  /** Flush pending work and detach browser lifecycle listeners. */
   destroy() {
-    this.pendingCardThreeDsAttempts.clear();
-    this.elements = null;
-    this.appliedAppearanceKey = null;
-    this.stripe = null;
+    if (this.destroyed) return;
+    this.drainQueue();
+    this.destroyed = true;
+    this.clearFlushTimer();
+    if (this.browserTransportAvailable) {
+      window.removeEventListener("pagehide", this.pageExitHandler);
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+    }
+    this.queue.splice(0);
+    this.reportedFailures.clear();
   }
-};
-
-// src/flopay.ts
-import { FloPayError as FloPayError5, resolveBillingApiUrl as resolveBillingApiUrl2, SDK_VERSION as SDK_VERSION3 } from "@flopay/shared";
-
-// src/elements.ts
-import "@flopay/shared";
-var FloPayElements = class {
-  constructor(provider, options) {
-    this.elementMap = /* @__PURE__ */ new Map();
-    this.provider = provider;
-    this.baseOptions = options ?? {};
+  /** Permanently honor a merchant opt-out and discard queued events. */
+  disable() {
+    this.merchantEnabled = false;
+    this.queue.splice(0);
+    this.reportedFailures.clear();
+    this.clearFlushTimer();
   }
-  /**
-   * Creates a new element of the given type.
-   * If an element of that type already exists, it is destroyed first.
-   */
-  async create(type, options) {
-    const providerExisting = this.provider.getElement(type);
-    if (providerExisting) {
-      this.elementMap.set(type, providerExisting);
-      return providerExisting;
+  /** Start every bounded keepalive request synchronously before page teardown. */
+  drainQueue() {
+    if (!this.browserTransportAvailable || this.destroyed || this.ingestionDisabled || this.queue.length === 0) return;
+    this.clearFlushTimer();
+    while (this.queue.length > 0) {
+      const events = this.queue.splice(0, MAX_BATCH_SIZE);
+      void this.sendBatch(events);
     }
-    const existing = this.elementMap.get(type);
-    if (existing) {
-      existing.destroy();
+  }
+  async sendBatch(events) {
+    if (!this.browserTransportAvailable || this.ingestionDisabled) return;
+    const body = serializeTelemetryBatch(events, {
+      correlationId: this.correlationId,
+      sdkPackage: this.sdkPackage,
+      sdkVersion: this.sdkVersion,
+      batchId: createUuidV4()
+    });
+    if (bodyByteLength(body) > TELEMETRY_MAX_BATCH_BYTES) return;
+    const controller = typeof AbortController === "undefined" ? null : new AbortController();
+    let timeout = null;
+    try {
+      const request = fetch(this.endpoint, {
+        method: "POST",
+        headers: { "content-type": "text/plain;charset=UTF-8" },
+        body,
+        credentials: "omit",
+        keepalive: true,
+        referrerPolicy: "no-referrer",
+        signal: controller?.signal
+      }).then(async (response) => {
+        if (response.status !== 202) return null;
+        const payload = await response.json().catch(() => null);
+        return payload?.status === "disabled" ? "disabled" : null;
+      }).catch(() => null);
+      const expired = new Promise((resolve) => {
+        timeout = setTimeout(() => {
+          controller?.abort();
+          resolve(null);
+        }, UPLOAD_TIMEOUT_MS);
+      });
+      const status = await Promise.race([request, expired]);
+      if (status === "disabled") this.disableFromIngestion();
+    } catch {
+    } finally {
+      if (timeout) clearTimeout(timeout);
     }
-    const merged = { ...this.baseOptions, ...options };
-    const element = await this.provider.createElement(type, merged);
-    this.elementMap.set(type, element);
-    return element;
   }
-  /** Returns a previously created element, or `null`. */
-  getElement(type) {
-    return this.elementMap.get(type) ?? null;
+  disableFromIngestion() {
+    this.ingestionDisabled = true;
+    this.queue.splice(0);
+    this.reportedFailures.clear();
+    this.clearFlushTimer();
   }
-  /**
-   * Submits all mounted elements for validation.
-   *
-   * Returns an object with an optional error if validation fails.
-   * This does NOT confirm the payment — call `floPay.confirmPayment()` for that.
-   */
-  async submit() {
-    return {};
+  scheduleFlush() {
+    if (this.flushTimer || this.destroyed || this.ingestionDisabled) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flush();
+    }, 0);
   }
-  /** Destroys all created elements and clears the internal map. */
-  destroy() {
-    for (const element of this.elementMap.values()) {
-      element.destroy();
-    }
-    this.elementMap.clear();
+  clearFlushTimer() {
+    if (!this.flushTimer) return;
+    clearTimeout(this.flushTimer);
+    this.flushTimer = null;
   }
 };
+var TELEMETRY_REPORTER_FACTORY = /* @__PURE__ */ Symbol.for("@flopay/js.telemetry.reporter-factory.v1");
+var telemetryGlobal = globalThis;
+if (telemetryGlobal[TELEMETRY_REPORTER_FACTORY] === void 0) {
+  Object.defineProperty(telemetryGlobal, TELEMETRY_REPORTER_FACTORY, {
+    configurable: true,
+    enumerable: false,
+    writable: false,
+    value: (options) => new TelemetryReporter(options)
+  });
+}
 
 // src/payment-api.ts
-import {
-  FloPayError as FloPayError3,
-  SDK_VERSION,
-  FLO_SDK_VERSION_HEADER,
-  IDEMPOTENCY_KEY_HEADER,
-  IDEMPOTENCY_IN_PROGRESS_CODE,
-  buildProductPayload,
-  foldIntoProducts,
-  resolveIdempotencyKey,
-  resolveSessionCurrency
-} from "@flopay/shared";
-
-// src/api-error.ts
-function readErrorString(value) {
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
-function readErrorMessage(value) {
-  if (typeof value === "string") return value.trim() ? value : void 0;
-  if (Array.isArray(value)) {
-    const joined = value.filter((entry) => typeof entry === "string" && entry.trim().length > 0).join("; ");
-    return joined || void 0;
-  }
-  return void 0;
+var DEFAULT_PROCESSING_RETRY_AFTER_MS = 1e3;
+var MIN_PROCESSING_RETRY_AFTER_MS = 500;
+var DEFAULT_PROCESSING_TIMEOUT_MS = 15e3;
+var MAX_PROCESSING_RETRY_AFTER_MS = 3e3;
+var DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS = 1e4;
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
 }
-
-// src/session-display-cache.ts
-var STORAGE_KEY_PREFIX = "flopay_session_display:";
-var DEFAULT_TTL_MS = 60 * 60 * 1e3;
-var memoryStore = /* @__PURE__ */ new Map();
-function storageKey(sessionId) {
-  return `${STORAGE_KEY_PREFIX}${sessionId}`;
+function telemetryStatusClass(status) {
+  if (status === void 0) return "network_error";
+  const statusClass = `${Math.floor(status / 100)}xx`;
+  return statusClass === "2xx" || statusClass === "3xx" || statusClass === "4xx" || statusClass === "5xx" ? statusClass : "unknown";
 }
-function getSessionStorage() {
-  if (typeof window === "undefined") return null;
-  try {
-    return window.sessionStorage;
-  } catch {
-    return null;
+function telemetryFailure(error, fallbackCode) {
+  if (error instanceof Error && (error.name === "AbortError" || error instanceof FloPayError && error.code === "checkout_processing_timeout")) {
+    return { errorCode: "REQUEST_TIMEOUT", statusClass: "timeout" };
   }
-}
-function cacheSessionDisplayData(sessionId, data, options) {
-  if (!sessionId) return;
-  const ttl = options?.ttlMs ?? DEFAULT_TTL_MS;
-  const entry = { data, expiresAt: Date.now() + ttl };
-  const storage = getSessionStorage();
-  if (storage) {
-    try {
-      storage.setItem(storageKey(sessionId), JSON.stringify(entry));
-      return;
-    } catch {
-    }
+  if (error instanceof TypeError) {
+    return { errorCode: "NETWORK_REQUEST_FAILED", statusClass: "network_error" };
   }
-  memoryStore.set(sessionId, entry);
+  return {
+    errorCode: fallbackCode,
+    statusClass: telemetryStatusClass(
+      error instanceof FloPayError ? error.statusCode : void 0
+    )
+  };
 }
-function getSessionDisplayData(sessionId) {
-  if (!sessionId) return null;
-  const storage = getSessionStorage();
-  if (storage) {
+function readString(payload, key) {
+  return readErrorString(payload?.[key]);
+}
+function readMessage(payload, key) {
+  return readErrorMessage(payload?.[key]);
+}
+function readNumber(payload, key) {
+  const value = payload?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createCheckoutProcessingTimeoutError() {
+  return new FloPayError(
+    "Checkout is still processing. Please try again shortly.",
+    "api_error",
+    { code: "checkout_processing_timeout" }
+  );
+}
+async function buildApiErrorFromResponse(response, fallbackMessage) {
+  const payload = await response.json().catch(() => null);
+  const nestedError = isRecord(payload?.error) ? payload.error : null;
+  const message = readMessage(payload, "message") ?? readMessage(nestedError, "message") ?? fallbackMessage;
+  const code = readString(payload, "code") ?? readString(payload, "gatewayErrorCode") ?? readString(nestedError, "code") ?? `http_${response.status}`;
+  return new FloPayError(message, "api_error", {
+    code,
+    statusCode: response.status
+  });
+}
+var NETWORK_RETRY_ATTEMPTS = 2;
+var IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS = 2;
+async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEMPTS, onRetry) {
+  let lastErr;
+  for (let attempt = 0; ; attempt++) {
     try {
-      const raw = storage.getItem(storageKey(sessionId));
-      if (raw) {
-        const entry = JSON.parse(raw);
-        if (entry && typeof entry.expiresAt === "number" && entry.expiresAt > Date.now()) {
-          return entry.data;
-        }
-        storage.removeItem(storageKey(sessionId));
+      return await fetch(input, init);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") throw err;
+      lastErr = err;
+      if (attempt >= attempts) throw lastErr;
+      try {
+        onRetry?.(attempt + 1);
+      } catch {
       }
-    } catch {
-    }
-  }
-  const memEntry = memoryStore.get(sessionId);
-  if (memEntry) {
-    if (memEntry.expiresAt > Date.now()) {
-      return memEntry.data;
+      await delay(150 * 2 ** attempt);
     }
-    memoryStore.delete(sessionId);
   }
-  return null;
 }
-function clearSessionDisplayData(sessionId) {
-  if (!sessionId) return;
-  memoryStore.delete(sessionId);
-  const storage = getSessionStorage();
-  if (storage) {
-    try {
-      storage.removeItem(storageKey(sessionId));
-    } catch {
-    }
-  }
+function isPaymentApiTelemetryHooks(value) {
+  return "now" in value || "onFirstByte" in value || "onSessionCreateFailure" in value || "onRetry" in value;
 }
-
-// src/telemetry-reporter.ts
-import {
-  buildTelemetryErrorEvent,
-  buildTelemetryLogEvent,
-  buildTelemetryPerformanceEvent,
-  buildTelemetryTerminalEvent,
-  serializeTelemetryBatch,
-  TELEMETRY_MAX_BATCH_BYTES
-} from "@flopay/shared";
-var TELEMETRY_PATH = "/v1/sdk-telemetry/events";
-var MAX_BATCH_SIZE = 16;
-var MAX_QUEUE_SIZE = 64;
-var UPLOAD_TIMEOUT_MS = 1500;
-var ERROR_DEDUPLICATION_WINDOW_MS = 1e3;
-var MAX_REPORTED_FAILURES = 64;
-var DEDUPLICATION_EVENT_ID = "00000000-0000-4000-8000-000000000000";
-var EVENT_BUDGETS = {
-  technical_error: 8,
-  lifecycle: 32,
-  expected_outcome: 32,
-  performance: 24
-};
-function createUuidV4() {
-  try {
-    return globalThis.crypto.randomUUID();
-  } catch {
-    const bytes = new Uint8Array(16);
+var PaymentAPI = class {
+  constructor(billingApiUrl, telemetryOptionsOrHooks = {}) {
+    this.baseUrl = billingApiUrl.replace(/\/+$/, "");
+    const hasInternalHooks = isPaymentApiTelemetryHooks(telemetryOptionsOrHooks);
+    this.telemetryHooks = hasInternalHooks ? telemetryOptionsOrHooks : void 0;
+    this.directTelemetry = hasInternalHooks || telemetryOptionsOrHooks.telemetry === false ? void 0 : new TelemetryReporter({
+      billingApiUrl: this.baseUrl,
+      sdkVersion: SDK_VERSION
+    });
+  }
+  /** Dispose the reporter owned by direct public usage. Internal hooks are never disposed here. */
+  destroy() {
+    this.directTelemetry?.destroy();
+  }
+  reportDirectFailure(error, fallbackCode, stage, requestCategory, paymentMethodCategory = "unknown") {
+    const failure = telemetryFailure(error, fallbackCode);
+    this.directTelemetry?.error({
+      ...failure,
+      stage,
+      requestCategory,
+      paymentMethodCategory
+    });
+  }
+  telemetryTimestamp() {
     try {
-      globalThis.crypto.getRandomValues(bytes);
+      return this.telemetryHooks?.now?.() ?? this.directTelemetry?.now() ?? telemetryNow();
     } catch {
-      for (let index = 0; index < bytes.length; index += 1) {
-        bytes[index] = Math.floor(Math.random() * 256);
-      }
+      return telemetryNow();
     }
-    bytes[6] = bytes[6] & 15 | 64;
-    bytes[8] = bytes[8] & 63 | 128;
-    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
   }
-}
-function bodyByteLength(body) {
-  try {
-    return new TextEncoder().encode(body).byteLength;
-  } catch {
-    return body.length;
+  beginDirectTelemetryCheckout(checkoutSessionId) {
+    if (!this.directTelemetry || this.directTelemetryCheckoutId === checkoutSessionId) return;
+    this.directTelemetryCheckoutId = checkoutSessionId;
+    this.directTelemetry.beginCheckout();
   }
-}
-function failureDeduplicationKey(event) {
-  return JSON.stringify([
-    event.code,
-    event.stage,
-    event.provider,
-    event.attempt,
-    event.statusClass,
-    event.requestCategory,
-    event.paymentMethodCategory,
-    event.checkoutMode,
-    event.layout
-  ]);
-}
-function telemetryNow() {
-  return globalThis.performance?.now() ?? 0;
-}
-var TelemetryReporter = class {
-  constructor(options) {
-    this.ingestionDisabled = false;
-    this.queue = [];
-    this.sequence = 0;
-    this.flushTimer = null;
-    this.flushInFlight = null;
-    this.reportedFailures = /* @__PURE__ */ new Map();
-    this.checkoutContext = {};
-    this.checkoutStartedAt = null;
-    this.destroyed = false;
-    this.pageExitHandler = () => {
-      this.drainQueue();
-    };
-    this.visibilityHandler = () => {
-      if (document.visibilityState === "hidden") void this.flush();
-    };
-    this.eventCounts = {
-      technical_error: 0,
-      lifecycle: 0,
-      expected_outcome: 0,
-      performance: 0
-    };
-    this.endpoint = `${options.billingApiUrl.replace(/\/+$/, "")}${TELEMETRY_PATH}`;
-    this.sdkPackage = options.sdkPackage ?? "@flopay/js";
-    this.sdkVersion = options.sdkVersion;
-    this.correlationId = createUuidV4();
-    this.merchantEnabled = options.enabled !== false;
-    this.clock = options.clock ?? telemetryNow;
-    this.browserTransportAvailable = typeof window !== "undefined" && typeof document !== "undefined";
-    if (this.browserTransportAvailable) {
-      window.addEventListener("pagehide", this.pageExitHandler);
-      document.addEventListener("visibilitychange", this.visibilityHandler);
-    }
+  beginDirectTelemetryOperation() {
+    if (!this.directTelemetry) return;
+    this.directTelemetryCheckoutId = void 0;
+    this.directTelemetry.beginCheckout();
   }
-  log(input) {
-    if (!this.canCollect()) return;
-    this.enqueue(buildTelemetryLogEvent({
-      ...this.checkoutContext,
-      ...input,
-      eventId: createUuidV4(),
-      sequence: this.sequence++
-    }));
+  adoptDirectTelemetryCheckout(checkoutSessionId) {
+    if (checkoutSessionId) this.directTelemetryCheckoutId = checkoutSessionId;
   }
-  error(input) {
-    if (!this.canCollect()) return;
-    const normalizedFailure = buildTelemetryErrorEvent({
-      ...this.checkoutContext,
-      ...input,
-      eventId: DEDUPLICATION_EVENT_ID,
-      sequence: 0
+  /**
+   * Fetch a raw checkout session by ID.
+   *
+   * `nonce` is the session-bound checkout token returned when the session
+   * was created. When supplied it is sent as the `x-checkout-session-token`
+   * header that post-#640 backends match against `checkout_session.nonce`
+   * before returning the row — the UUID alone is no longer sufficient.
+   * Backends that don't yet enforce it ignore the extra header.
+   */
+  async getCheckoutSession(checkoutSessionId, nonce) {
+    this.beginDirectTelemetryCheckout(checkoutSessionId);
+    const requestStarted = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "session.read.started",
+      stage: "session_read",
+      requestCategory: "session_read"
     });
-    const deduplicationKey = failureDeduplicationKey(normalizedFailure);
-    const now = this.now();
-    this.pruneReportedFailures(now);
-    const previouslyReportedAt = this.reportedFailures.get(deduplicationKey);
-    if (previouslyReportedAt !== void 0 && now >= previouslyReportedAt && now - previouslyReportedAt < ERROR_DEDUPLICATION_WINDOW_MS) {
-      this.log({
-        name: "operation.deduplicated",
-        stage: input.stage,
-        provider: input.provider,
-        paymentMethodCategory: input.paymentMethodCategory,
-        attempt: input.attempt
+    const headers = { [FLO_SDK_VERSION_HEADER]: SDK_VERSION };
+    if (nonce) headers["x-checkout-session-token"] = nonce;
+    try {
+      const response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
+        { headers },
+        NETWORK_RETRY_ATTEMPTS,
+        (attempt) => {
+          this.telemetryHooks?.onRetry?.("session_read", attempt);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "session_read",
+            requestCategory: "session_read",
+            attempt
+          });
+        }
+      );
+      const firstByteDuration = Math.max(0, this.telemetryTimestamp() - requestStarted);
+      try {
+        this.telemetryHooks?.onFirstByte?.(firstByteDuration);
+      } catch {
+      }
+      const statusClass = `${Math.floor(response.status / 100)}xx`;
+      this.directTelemetry?.log({
+        name: "session.request.first_byte",
+        stage: "session_first_byte",
+        requestCategory: "session_read",
+        statusClass
       });
-      return;
+      this.directTelemetry?.performance({
+        stage: "session_first_byte",
+        durationMs: firstByteDuration,
+        durationMode: "machine",
+        requestCategory: "session_read",
+        statusClass
+      });
+      if (!response.ok) {
+        throw await buildApiErrorFromResponse(response, "Failed to get checkout session");
+      }
+      const body = await response.json();
+      this.directTelemetry?.log({
+        name: "session.request.completed",
+        stage: "session_complete",
+        requestCategory: "session_read",
+        statusClass
+      });
+      this.directTelemetry?.performance({
+        stage: "session_complete",
+        durationMs: Math.max(0, this.telemetryTimestamp() - requestStarted),
+        durationMode: "machine",
+        requestCategory: "session_read",
+        statusClass
+      });
+      return { ...body, data: this.mergeCachedDisplayData(body.data) };
+    } catch (error) {
+      const statusCode = error instanceof FloPayError ? error.statusCode : void 0;
+      this.directTelemetry?.error({
+        errorCode: error instanceof FloPayError && error.code === "checkout_processing_timeout" ? "REQUEST_TIMEOUT" : "NETWORK_REQUEST_FAILED",
+        stage: "session_read",
+        requestCategory: "session_read",
+        statusClass: statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
+      });
+      throw error;
     }
-    this.rememberReportedFailure(deduplicationKey, now);
-    this.enqueue(buildTelemetryErrorEvent({
-      ...this.checkoutContext,
-      ...input,
-      eventId: createUuidV4(),
-      sequence: this.sequence++
-    }));
   }
-  performance(input) {
-    if (!this.canCollect()) return;
-    this.enqueue(buildTelemetryPerformanceEvent({
-      ...this.checkoutContext,
-      ...input,
-      eventId: createUuidV4(),
-      sequence: this.sequence++
-    }));
+  /**
+   * Stash display-only data for a session so subsequent fetches can fill in
+   * fields the backend no longer persists (`overrideAmount`, `totalAmount`,
+   * `providerItemName`, `providerPlanName`).
+   *
+   * Backed by `sessionStorage` in the browser, with an in-memory fallback in
+   * Node/SSR contexts. Default TTL: 1 hour.
+   *
+   * Server-returned values always win — cached values fill in only where the
+   * server returned `null` / `undefined`.
+   *
+   * @example
+   * ```ts
+   * paymentAPI.cacheSessionDisplayData(sessionId, {
+   *   currency: 'USD',
+   *   items: [{ code: 'pro_plan', overrideAmount: 24.99, providerItemName: 'Pro' }],
+   * });
+   * ```
+   */
+  cacheSessionDisplayData(sessionId, data, options) {
+    cacheSessionDisplayData(sessionId, data, options);
   }
-  terminal(input) {
-    if (!this.canCollect()) return;
-    this.enqueue(buildTelemetryTerminalEvent({
-      ...this.checkoutContext,
-      ...input,
-      eventId: createUuidV4(),
-      sequence: this.sequence++
-    }));
-    if (input.outcome !== "action_required" && this.checkoutStartedAt !== null) {
-      const checkoutStartedAt = this.checkoutStartedAt;
-      this.checkoutStartedAt = null;
-      this.performance({
-        stage: "total_journey",
-        durationMs: Math.max(0, this.now() - checkoutStartedAt),
-        durationMode: "total",
-        provider: input.provider,
-        paymentMethodCategory: input.paymentMethodCategory
-      });
-    }
+  /**
+   * Drop any cached display data for a session. Call after the payment
+   * completes; otherwise the TTL handles cleanup.
+   */
+  clearSessionDisplayData(sessionId) {
+    clearSessionDisplayData(sessionId);
   }
-  /** @internal Read the reporter's monotonic clock without Resource Timing. */
-  now() {
+  /**
+   * 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) {
+    this.beginDirectTelemetryCheckout(checkoutSessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "vault.capture.requested",
+      stage: "vault_request",
+      requestCategory: "vault_capture",
+      paymentMethodCategory: "card"
+    });
+    const headers = { "Content-Type": "application/json" };
+    if (nonce) headers["x-checkout-session-token"] = nonce;
     try {
-      return this.clock();
-    } catch {
-      return telemetryNow();
+      const response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}/vault/capture`,
+        { method: "POST", headers },
+        NETWORK_RETRY_ATTEMPTS,
+        (attempt) => {
+          this.telemetryHooks?.onRetry?.("vault_capture", attempt);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "vault_request",
+            requestCategory: "vault_capture",
+            paymentMethodCategory: "card",
+            attempt
+          });
+        }
+      );
+      if (!response.ok) {
+        throw await buildApiErrorFromResponse(response, "Failed to load the secure card form");
+      }
+      const block = await response.json();
+      this.directTelemetry?.performance({
+        stage: "vault_request",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "vault_capture",
+        paymentMethodCategory: "card",
+        statusClass: "2xx"
+      });
+      return this.toVaultBlock(block);
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "VAULT_LOAD_FAILED",
+        "vault_request",
+        "vault_capture",
+        "card"
+      );
+      throw error;
     }
   }
-  pruneReportedFailures(now) {
-    for (const [key, reportedAt] of this.reportedFailures) {
-      if (now < reportedAt || now - reportedAt >= ERROR_DEDUPLICATION_WINDOW_MS) {
-        this.reportedFailures.delete(key);
-      }
+  /**
+   * Fetch and normalize a checkout session.
+   *
+   * Reads the backend's `gateways` map to enumerate provider-specific data,
+   * then wraps the session in a `NormalizedCheckoutSession` for provider-
+   * agnostic consumption.
+   */
+  async getUnifiedCheckoutSession(checkoutSessionId, nonce) {
+    const res = await this.getCheckoutSession(checkoutSessionId, nonce);
+    const normalized = this.normalizeRawSession(res.data);
+    const vault = res.vault;
+    if (vault && normalized.data.session) {
+      normalized.data.session.vault = this.toVaultBlock(vault);
     }
+    return normalized;
   }
-  rememberReportedFailure(key, reportedAt) {
-    while (this.reportedFailures.size >= MAX_REPORTED_FAILURES) {
-      const oldest = this.reportedFailures.keys().next();
-      if (oldest.done) break;
-      this.reportedFailures.delete(oldest.value);
-    }
-    this.reportedFailures.set(key, reportedAt);
-  }
-  /** @internal Add closed checkout dimensions to subsequent SDK events. */
-  setCheckoutContext(context) {
-    this.checkoutContext = {
-      checkoutMode: context.checkoutMode,
-      layout: context.layout
-    };
-  }
-  /** @internal Start a fresh checkout budget, dedupe window, and total span. */
-  beginCheckout(context = {}) {
-    if (!this.canCollect()) return 0;
-    this.drainQueue();
-    this.setCheckoutContext(context);
-    this.sequence = 0;
-    this.reportedFailures.clear();
-    this.eventCounts = {
-      technical_error: 0,
-      lifecycle: 0,
-      expected_outcome: 0,
-      performance: 0
-    };
-    this.checkoutStartedAt = this.now();
-    return this.checkoutStartedAt;
-  }
-  enqueue(event) {
-    if (!this.canCollect()) return;
-    if (this.queue.length >= MAX_QUEUE_SIZE || this.eventCounts[event.class] >= EVENT_BUDGETS[event.class]) return;
-    this.eventCounts[event.class] += 1;
-    this.queue.push(event);
-    if (this.queue.length >= MAX_BATCH_SIZE) {
-      void this.flush();
-      return;
-    }
-    this.scheduleFlush();
-  }
-  canCollect() {
-    return this.browserTransportAvailable && this.merchantEnabled && !this.ingestionDisabled && !this.destroyed;
-  }
-  /** Flush one bounded batch. Failures are intentionally dropped. */
-  async flush() {
-    if (this.flushInFlight) return this.flushInFlight;
-    if (!this.browserTransportAvailable || this.destroyed || this.ingestionDisabled || this.queue.length === 0) return;
-    this.clearFlushTimer();
-    const events = this.queue.splice(0, MAX_BATCH_SIZE);
-    this.flushInFlight = this.sendBatch(events).finally(() => {
-      this.flushInFlight = null;
-      if (this.queue.length > 0) this.scheduleFlush();
-    });
-    return this.flushInFlight;
-  }
-  /** Flush pending work and detach browser lifecycle listeners. */
-  destroy() {
-    if (this.destroyed) return;
-    this.drainQueue();
-    this.destroyed = true;
-    this.clearFlushTimer();
-    if (this.browserTransportAvailable) {
-      window.removeEventListener("pagehide", this.pageExitHandler);
-      document.removeEventListener("visibilitychange", this.visibilityHandler);
-    }
-    this.queue.splice(0);
-    this.reportedFailures.clear();
-  }
-  /** Permanently honor a merchant opt-out and discard queued events. */
-  disable() {
-    this.merchantEnabled = false;
-    this.queue.splice(0);
-    this.reportedFailures.clear();
-    this.clearFlushTimer();
-  }
-  /** Start every bounded keepalive request synchronously before page teardown. */
-  drainQueue() {
-    if (!this.browserTransportAvailable || this.destroyed || this.ingestionDisabled || this.queue.length === 0) return;
-    this.clearFlushTimer();
-    while (this.queue.length > 0) {
-      const events = this.queue.splice(0, MAX_BATCH_SIZE);
-      void this.sendBatch(events);
-    }
-  }
-  async sendBatch(events) {
-    if (!this.browserTransportAvailable || this.ingestionDisabled) return;
-    const body = serializeTelemetryBatch(events, {
-      correlationId: this.correlationId,
-      sdkPackage: this.sdkPackage,
-      sdkVersion: this.sdkVersion,
-      batchId: createUuidV4()
-    });
-    if (bodyByteLength(body) > TELEMETRY_MAX_BATCH_BYTES) return;
-    const controller = typeof AbortController === "undefined" ? null : new AbortController();
-    let timeout = null;
-    try {
-      const request = fetch(this.endpoint, {
-        method: "POST",
-        headers: { "content-type": "text/plain;charset=UTF-8" },
-        body,
-        credentials: "omit",
-        keepalive: true,
-        referrerPolicy: "no-referrer",
-        signal: controller?.signal
-      }).then(async (response) => {
-        if (response.status !== 202) return null;
-        const payload = await response.json().catch(() => null);
-        return payload?.status === "disabled" ? "disabled" : null;
-      }).catch(() => null);
-      const expired = new Promise((resolve) => {
-        timeout = setTimeout(() => {
-          controller?.abort();
-          resolve(null);
-        }, UPLOAD_TIMEOUT_MS);
+  /**
+   * Submit a tokenized payment to the billing backend.
+   *
+   * The backend will either succeed, return `type: '3ds_required'`
+   * (with a `threeDSecureToken`), or return `type: 'paypal_redirect_required'`.
+   *
+   * Hits the session-scoped route `POST /v1/checkouts/sessions/:id/process`
+   * and forwards `data.nonce` as `x-checkout-session-token`. Backend
+   * `TeamFloPay/backend#640` rejects callers without a matching nonce with a
+   * 401 — this method throws synchronously when `data.nonce` is missing so the
+   * problem surfaces before the network round trip.
+   *
+   * @param userId Vestigial — backend's GatewayInterceptor routes via session,
+   *   not headers, so this value is no longer sent on the wire. Kept in the
+   *   signature for back-compat with existing callers; will be removed in a
+   *   future major version.
+   */
+  async processPayment(_userId, data, options) {
+    this.beginDirectTelemetryCheckout(data.sessionId);
+    if (!data.nonce) {
+      this.directTelemetry?.terminal({
+        outcome: "validation_rejected",
+        stage: "processing",
+        requestCategory: "process_payment"
       });
-      const status = await Promise.race([request, expired]);
-      if (status === "disabled") this.disableFromIngestion();
-    } catch {
-    } finally {
-      if (timeout) clearTimeout(timeout);
-    }
-  }
-  disableFromIngestion() {
-    this.ingestionDisabled = true;
-    this.queue.splice(0);
-    this.reportedFailures.clear();
-    this.clearFlushTimer();
-  }
-  scheduleFlush() {
-    if (this.flushTimer || this.destroyed || this.ingestionDisabled) return;
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = null;
-      void this.flush();
-    }, 0);
-  }
-  clearFlushTimer() {
-    if (!this.flushTimer) return;
-    clearTimeout(this.flushTimer);
-    this.flushTimer = null;
-  }
-};
-var TELEMETRY_REPORTER_FACTORY = /* @__PURE__ */ Symbol.for("@flopay/js.telemetry.reporter-factory.v1");
-var telemetryGlobal = globalThis;
-if (telemetryGlobal[TELEMETRY_REPORTER_FACTORY] === void 0) {
-  Object.defineProperty(telemetryGlobal, TELEMETRY_REPORTER_FACTORY, {
-    configurable: true,
-    enumerable: false,
-    writable: false,
-    value: (options) => new TelemetryReporter(options)
-  });
-}
-
-// src/payment-api.ts
-var DEFAULT_PROCESSING_RETRY_AFTER_MS = 1e3;
-var MIN_PROCESSING_RETRY_AFTER_MS = 500;
-var DEFAULT_PROCESSING_TIMEOUT_MS = 15e3;
-var MAX_PROCESSING_RETRY_AFTER_MS = 3e3;
-var DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS = 1e4;
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-function telemetryStatusClass(status) {
-  if (status === void 0) return "network_error";
-  const statusClass = `${Math.floor(status / 100)}xx`;
-  return statusClass === "2xx" || statusClass === "3xx" || statusClass === "4xx" || statusClass === "5xx" ? statusClass : "unknown";
-}
-function telemetryFailure(error, fallbackCode) {
-  if (error instanceof Error && (error.name === "AbortError" || error instanceof FloPayError3 && error.code === "checkout_processing_timeout")) {
-    return { errorCode: "REQUEST_TIMEOUT", statusClass: "timeout" };
-  }
-  if (error instanceof TypeError) {
-    return { errorCode: "NETWORK_REQUEST_FAILED", statusClass: "network_error" };
-  }
-  return {
-    errorCode: fallbackCode,
-    statusClass: telemetryStatusClass(
-      error instanceof FloPayError3 ? error.statusCode : void 0
-    )
-  };
-}
-function readString(payload, key) {
-  return readErrorString(payload?.[key]);
-}
-function readMessage(payload, key) {
-  return readErrorMessage(payload?.[key]);
-}
-function readNumber(payload, key) {
-  const value = payload?.[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
-}
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function createCheckoutProcessingTimeoutError() {
-  return new FloPayError3(
-    "Checkout is still processing. Please try again shortly.",
-    "api_error",
-    { code: "checkout_processing_timeout" }
-  );
-}
-async function buildApiErrorFromResponse(response, fallbackMessage) {
-  const payload = await response.json().catch(() => null);
-  const nestedError = isRecord(payload?.error) ? payload.error : null;
-  const message = readMessage(payload, "message") ?? readMessage(nestedError, "message") ?? fallbackMessage;
-  const code = readString(payload, "code") ?? readString(payload, "gatewayErrorCode") ?? readString(nestedError, "code") ?? `http_${response.status}`;
-  return new FloPayError3(message, "api_error", {
-    code,
-    statusCode: response.status
-  });
-}
-var NETWORK_RETRY_ATTEMPTS = 2;
-var IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS = 2;
-async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEMPTS, onRetry) {
-  let lastErr;
-  for (let attempt = 0; ; attempt++) {
-    try {
-      return await fetch(input, init);
-    } catch (err) {
-      if (err instanceof Error && err.name === "AbortError") throw err;
-      lastErr = err;
-      if (attempt >= attempts) throw lastErr;
-      try {
-        onRetry?.(attempt + 1);
-      } catch {
-      }
-      await delay(150 * 2 ** attempt);
+      throw new FloPayError(
+        "processPayment requires `nonce` \u2014 pass the value returned from session creation.",
+        "validation_error",
+        { code: "MissingCheckoutSessionToken", param: "nonce" }
+      );
     }
-  }
-}
-function isPaymentApiTelemetryHooks(value) {
-  return "now" in value || "onFirstByte" in value || "onSessionCreateFailure" in value || "onRetry" in value;
-}
-var PaymentAPI = class {
-  constructor(billingApiUrl, telemetryOptionsOrHooks = {}) {
-    this.baseUrl = billingApiUrl.replace(/\/+$/, "");
-    const hasInternalHooks = isPaymentApiTelemetryHooks(telemetryOptionsOrHooks);
-    this.telemetryHooks = hasInternalHooks ? telemetryOptionsOrHooks : void 0;
-    this.directTelemetry = hasInternalHooks || telemetryOptionsOrHooks.telemetry === false ? void 0 : new TelemetryReporter({
-      billingApiUrl: this.baseUrl,
-      sdkVersion: SDK_VERSION
-    });
-  }
-  /** Dispose the reporter owned by direct public usage. Internal hooks are never disposed here. */
-  destroy() {
-    this.directTelemetry?.destroy();
-  }
-  reportDirectFailure(error, fallbackCode, stage, requestCategory, paymentMethodCategory = "unknown") {
-    const failure = telemetryFailure(error, fallbackCode);
-    this.directTelemetry?.error({
-      ...failure,
-      stage,
-      requestCategory,
-      paymentMethodCategory
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "payment.processing.started",
+      stage: "processing",
+      requestCategory: "process_payment"
     });
-  }
-  telemetryTimestamp() {
+    const { nonce, ...processBody } = data;
+    let response;
+    try {
+      response = await fetch(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(data.sessionId)}/process`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-checkout-session-token": nonce
+          },
+          body: JSON.stringify(processBody)
+        }
+      );
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "PAYMENT_PROCESSING_FAILED",
+        "processing",
+        "process_payment"
+      );
+      throw error;
+    }
+    if (!response.ok && response.status !== 202) {
+      this.directTelemetry?.error({
+        errorCode: "PAYMENT_PROCESSING_FAILED",
+        stage: "processing",
+        requestCategory: "process_payment",
+        statusClass: telemetryStatusClass(response.status)
+      });
+      return response;
+    }
     try {
-      return this.telemetryHooks?.now?.() ?? this.directTelemetry?.now() ?? telemetryNow();
-    } catch {
-      return telemetryNow();
+      const result = await this.resolveProcessResponse(
+        response,
+        data.sessionId,
+        { ...options, nonce }
+      );
+      this.directTelemetry?.log({
+        name: "payment.processing.completed",
+        stage: "processing",
+        requestCategory: "process_payment",
+        statusClass: telemetryStatusClass(result.status)
+      });
+      this.directTelemetry?.performance({
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+        durationMode: "machine",
+        requestCategory: "process_payment",
+        statusClass: telemetryStatusClass(result.status)
+      });
+      return result;
+    } catch (error) {
+      if (!(error instanceof FloPayError && error.code === "checkout_processing_timeout")) {
+        this.reportDirectFailure(
+          error,
+          "PAYMENT_PROCESSING_FAILED",
+          "processing",
+          "process_payment"
+        );
+      }
+      throw error;
     }
   }
-  beginDirectTelemetryCheckout(checkoutSessionId) {
-    if (!this.directTelemetry || this.directTelemetryCheckoutId === checkoutSessionId) return;
-    this.directTelemetryCheckoutId = checkoutSessionId;
-    this.directTelemetry.beginCheckout();
-  }
-  beginDirectTelemetryOperation() {
-    if (!this.directTelemetry) return;
-    this.directTelemetryCheckoutId = void 0;
-    this.directTelemetry.beginCheckout();
-  }
-  adoptDirectTelemetryCheckout(checkoutSessionId) {
-    if (checkoutSessionId) this.directTelemetryCheckoutId = checkoutSessionId;
-  }
   /**
-   * Fetch a raw checkout session by ID.
+   * 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).
    *
-   * `nonce` is the session-bound checkout token returned when the session
-   * was created. When supplied it is sent as the `x-checkout-session-token`
-   * header that post-#640 backends match against `checkout_session.nonce`
-   * before returning the row — the UUID alone is no longer sufficient.
-   * Backends that don't yet enforce it ignore the extra header.
+   * 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 getCheckoutSession(checkoutSessionId, nonce) {
-    this.beginDirectTelemetryCheckout(checkoutSessionId);
-    const requestStarted = this.telemetryTimestamp();
+  async patchAccountSnapshot(sessionId, nonce, body, options) {
+    this.beginDirectTelemetryCheckout(sessionId);
+    const startedAt = this.telemetryTimestamp();
     this.directTelemetry?.log({
-      name: "session.read.started",
-      stage: "session_read",
-      requestCategory: "session_read"
+      name: "operation.state_transition",
+      stage: "processing",
+      requestCategory: "account_snapshot"
     });
-    const headers = { [FLO_SDK_VERSION_HEADER]: SDK_VERSION };
-    if (nonce) headers["x-checkout-session-token"] = nonce;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (options?.signal) {
+      if (options.signal.aborted) controller.abort();
+      else options.signal.addEventListener("abort", onCallerAbort, { once: true });
+    }
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      const response = await fetchWithNetworkRetry(
-        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
-        { headers },
-        NETWORK_RETRY_ATTEMPTS,
-        (attempt) => {
-          this.telemetryHooks?.onRetry?.("session_read", attempt);
-          this.directTelemetry?.log({
-            name: "operation.retry",
-            stage: "session_read",
-            requestCategory: "session_read",
-            attempt
-          });
-        }
-      );
-      const firstByteDuration = Math.max(0, this.telemetryTimestamp() - requestStarted);
+      let response;
       try {
-        this.telemetryHooks?.onFirstByte?.(firstByteDuration);
-      } catch {
+        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),
+            signal: controller.signal
+          },
+          NETWORK_RETRY_ATTEMPTS,
+          (attempt) => {
+            this.telemetryHooks?.onRetry?.("account_snapshot", attempt);
+            this.directTelemetry?.log({
+              name: "operation.retry",
+              stage: "processing",
+              requestCategory: "account_snapshot",
+              attempt
+            });
+          }
+        );
+      } finally {
+        clearTimeout(timer);
+        options?.signal?.removeEventListener("abort", onCallerAbort);
+      }
+      if (!response.ok) {
+        throw await buildApiErrorFromResponse(response, "Failed to persist account snapshot");
       }
-      const statusClass = `${Math.floor(response.status / 100)}xx`;
-      this.directTelemetry?.log({
-        name: "session.request.first_byte",
-        stage: "session_first_byte",
-        requestCategory: "session_read",
-        statusClass
-      });
       this.directTelemetry?.performance({
-        stage: "session_first_byte",
-        durationMs: firstByteDuration,
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
         durationMode: "machine",
-        requestCategory: "session_read",
-        statusClass
+        requestCategory: "account_snapshot",
+        statusClass: "2xx"
       });
+    } catch (error) {
+      this.reportDirectFailure(
+        error,
+        "NETWORK_REQUEST_FAILED",
+        "processing",
+        "account_snapshot"
+      );
+      throw error;
+    }
+  }
+  /** Create a wallet/APM/PayPal intent through the session-scoped contract. */
+  async createSessionIntent(sessionId, nonce, request, options) {
+    if (!nonce) {
+      throw new FloPayError(
+        "createSessionIntent requires the checkout session nonce.",
+        "validation_error",
+        { code: "MissingCheckoutSessionToken", param: "nonce" }
+      );
+    }
+    const rawRequest = request;
+    const paymentMethodType = rawRequest["paymentMethodType"];
+    const directCardType = typeof paymentMethodType === "string" && paymentMethodType.trim().toLowerCase() === "card";
+    const commonRequestFieldsValid = typeof paymentMethodType === "string" && paymentMethodType.length > 0 && !directCardType && (typeof rawRequest["paymentMethodId"] === "string" || rawRequest["paymentMethodId"] === null);
+    const stripeRequestValid = rawRequest["provider"] === "stripe" && (rawRequest["paymentMethodCategory"] === "wallet" || rawRequest["paymentMethodCategory"] === "apm") && (rawRequest["intentKind"] === "payment" || rawRequest["intentKind"] === "setup");
+    const paypalRequestValid = rawRequest["provider"] === "paypal" && rawRequest["paymentMethodCategory"] === "wallet" && rawRequest["paymentMethodType"] === "paypal" && rawRequest["paymentMethodId"] === null && (rawRequest["intentKind"] === "order" || rawRequest["intentKind"] === "subscription");
+    if (!commonRequestFieldsValid || !stripeRequestValid && !paypalRequestValid) {
+      throw new FloPayError(
+        "Only wallet, APM, and PayPal session intents are supported.",
+        "validation_error",
+        { code: "InvalidSessionIntentRequest" }
+      );
+    }
+    const suppliedAttemptId = rawRequest["authorizationAttemptId"];
+    if (suppliedAttemptId !== void 0 && !isUuidV4(suppliedAttemptId)) {
+      throw new FloPayError(
+        "authorizationAttemptId must be a v4 UUID identifying one buyer authorization attempt.",
+        "validation_error",
+        { code: "InvalidAuthorizationAttemptId", param: "authorizationAttemptId" }
+      );
+    }
+    const authorizationAttemptId = isUuidV4(suppliedAttemptId) ? suppliedAttemptId : randomUuidV4();
+    this.beginDirectTelemetryCheckout(sessionId);
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "payment.intent.started",
+      stage: "processing",
+      requestCategory: "intent_create"
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      "x-checkout-session-token": nonce,
+      [IDEMPOTENCY_KEY_HEADER]: options?.idempotencyKey || authorizationAttemptId
+    };
+    let failureReported = false;
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/intents`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ ...request, authorizationAttemptId }),
+          signal: options?.signal
+        }
+      );
       if (!response.ok) {
-        throw await buildApiErrorFromResponse(response, "Failed to get checkout session");
+        failureReported = true;
+        this.directTelemetry?.error({
+          errorCode: "PAYMENT_PROCESSING_FAILED",
+          stage: "processing",
+          requestCategory: "intent_create",
+          statusClass: telemetryStatusClass(response.status)
+        });
+        throw await buildApiErrorFromResponse(response, "Failed to create checkout intent");
       }
       const body = await response.json();
+      const data = body.data;
+      if (!data || typeof data !== "object") {
+        throw new FloPayError("Invalid checkout intent response.", "api_error", {
+          code: "InvalidSessionIntentResponse"
+        });
+      }
+      const intent = data;
+      const responsePaymentMethodType = intent["paymentMethodType"];
+      const commonFieldsValid = (intent["paymentMethodCategory"] === "wallet" || intent["paymentMethodCategory"] === "apm") && typeof responsePaymentMethodType === "string" && responsePaymentMethodType.trim().toLowerCase() !== "card" && (typeof intent["paymentMethodId"] === "string" || intent["paymentMethodId"] === null) && typeof intent["providerObjectId"] === "string";
+      const stripeValid = intent["provider"] === "stripe" && (intent["intentKind"] === "payment" || intent["intentKind"] === "setup") && typeof intent["clientSecret"] === "string";
+      const paypalValid = intent["provider"] === "paypal" && intent["paymentMethodCategory"] === "wallet" && intent["paymentMethodType"] === "paypal" && intent["paymentMethodId"] === null && (intent["intentKind"] === "order" || intent["intentKind"] === "subscription") && intent["clientSecret"] === null;
+      const discriminantsMatchRequest = intent["provider"] === request.provider && intent["paymentMethodCategory"] === request.paymentMethodCategory && intent["paymentMethodType"] === request.paymentMethodType && intent["paymentMethodId"] === request.paymentMethodId && intent["intentKind"] === request.intentKind;
+      if (!commonFieldsValid || !stripeValid && !paypalValid || !discriminantsMatchRequest) {
+        throw new FloPayError("Invalid checkout intent response.", "api_error", {
+          code: "InvalidSessionIntentResponse"
+        });
+      }
       this.directTelemetry?.log({
-        name: "session.request.completed",
-        stage: "session_complete",
-        requestCategory: "session_read",
-        statusClass
+        name: "payment.intent.completed",
+        stage: "processing",
+        requestCategory: "intent_create",
+        statusClass: telemetryStatusClass(response.status)
       });
       this.directTelemetry?.performance({
-        stage: "session_complete",
-        durationMs: Math.max(0, this.telemetryTimestamp() - requestStarted),
+        stage: "processing",
+        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
         durationMode: "machine",
-        requestCategory: "session_read",
-        statusClass
+        requestCategory: "intent_create",
+        statusClass: telemetryStatusClass(response.status)
       });
-      return { ...body, data: this.mergeCachedDisplayData(body.data) };
+      return intent;
     } catch (error) {
-      const statusCode = error instanceof FloPayError3 ? error.statusCode : void 0;
-      this.directTelemetry?.error({
-        errorCode: error instanceof FloPayError3 && error.code === "checkout_processing_timeout" ? "REQUEST_TIMEOUT" : "NETWORK_REQUEST_FAILED",
-        stage: "session_read",
-        requestCategory: "session_read",
-        statusClass: statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
-      });
+      if (!failureReported) {
+        this.reportDirectFailure(
+          error,
+          "PAYMENT_PROCESSING_FAILED",
+          "processing",
+          "intent_create"
+        );
+      }
       throw error;
     }
   }
-  /**
-   * Stash display-only data for a session so subsequent fetches can fill in
-   * fields the backend no longer persists (`overrideAmount`, `totalAmount`,
-   * `providerItemName`, `providerPlanName`).
-   *
-   * Backed by `sessionStorage` in the browser, with an in-memory fallback in
-   * Node/SSR contexts. Default TTL: 1 hour.
-   *
-   * Server-returned values always win — cached values fill in only where the
-   * server returned `null` / `undefined`.
-   *
-   * @example
-   * ```ts
-   * paymentAPI.cacheSessionDisplayData(sessionId, {
-   *   currency: 'USD',
-   *   items: [{ code: 'pro_plan', overrideAmount: 24.99, providerItemName: 'Pro' }],
-   * });
-   * ```
-   */
-  cacheSessionDisplayData(sessionId, data, options) {
-    cacheSessionDisplayData(sessionId, data, options);
-  }
-  /**
-   * Drop any cached display data for a session. Call after the payment
-   * completes; otherwise the TTL handles cleanup.
-   */
-  clearSessionDisplayData(sessionId) {
-    clearSessionDisplayData(sessionId);
+  /** Record a provider-neutral non-card decline without sensitive identifiers. */
+  async reportSessionIntentDecline(sessionId, nonce, request, options) {
+    if (!nonce) {
+      throw new FloPayError(
+        "reportSessionIntentDecline requires the checkout session nonce.",
+        "validation_error",
+        { code: "MissingCheckoutSessionToken", param: "nonce" }
+      );
+    }
+    const rawRequest = request;
+    const reason = rawRequest["providerDeclineReason"];
+    const paymentMethodType = rawRequest["paymentMethodType"];
+    const safeReason = typeof reason === "string" && /^[a-z0-9][a-z0-9_.:-]{0,63}$/i.test(reason) && !/^(?:pm|pi|seti|tok|src|cus|sess|sk|pk)_/i.test(reason);
+    const commonFieldsValid = typeof paymentMethodType === "string" && paymentMethodType.length > 0 && paymentMethodType.trim().toLowerCase() !== "card" && safeReason;
+    const stripeFieldsValid = rawRequest["provider"] === "stripe" && (rawRequest["paymentMethodCategory"] === "wallet" || rawRequest["paymentMethodCategory"] === "apm");
+    const paypalFieldsValid = rawRequest["provider"] === "paypal" && rawRequest["paymentMethodCategory"] === "wallet" && rawRequest["paymentMethodType"] === "paypal";
+    if (!commonFieldsValid || !stripeFieldsValid && !paypalFieldsValid) {
+      throw new FloPayError(
+        "Invalid non-card decline classification.",
+        "validation_error",
+        { code: "InvalidSessionIntentDeclineRequest" }
+      );
+    }
+    const safeRequest = paypalFieldsValid ? {
+      provider: "paypal",
+      paymentMethodCategory: "wallet",
+      paymentMethodType: "paypal",
+      providerDeclineReason: reason
+    } : {
+      provider: "stripe",
+      paymentMethodCategory: rawRequest["paymentMethodCategory"],
+      paymentMethodType: rawRequest["paymentMethodType"],
+      providerDeclineReason: reason
+    };
+    const response = await fetch(
+      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/intents/decline`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-checkout-session-token": nonce
+        },
+        body: JSON.stringify(safeRequest),
+        signal: options?.signal
+      }
+    );
+    if (!response.ok) {
+      throw await buildApiErrorFromResponse(response, "Failed to report checkout decline");
+    }
   }
   /**
-   * 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).
+   * Fetch user's prior payments by email.
+   * Used to determine if saved card UX should be shown.
    */
-  async getVaultCapture(checkoutSessionId, nonce) {
-    this.beginDirectTelemetryCheckout(checkoutSessionId);
+  async getPaymentsByEmail(email, options) {
+    this.beginDirectTelemetryOperation();
     const startedAt = this.telemetryTimestamp();
     this.directTelemetry?.log({
-      name: "vault.capture.requested",
-      stage: "vault_request",
-      requestCategory: "vault_capture",
-      paymentMethodCategory: "card"
+      name: "operation.recovery.started",
+      stage: "recovery",
+      requestCategory: "other",
+      paymentMethodCategory: "saved"
+    });
+    const page = options?.page ?? 1;
+    const limit = options?.limit ?? 1;
+    const params = new URLSearchParams({
+      email,
+      page: String(page),
+      limit: String(limit),
+      sortField: "createdAt",
+      sortDirection: "DESC"
     });
-    const headers = { "Content-Type": "application/json" };
-    if (nonce) headers["x-checkout-session-token"] = nonce;
     try {
-      const response = await fetchWithNetworkRetry(
-        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}/vault/capture`,
-        { method: "POST", headers },
-        NETWORK_RETRY_ATTEMPTS,
-        (attempt) => {
-          this.telemetryHooks?.onRetry?.("vault_capture", attempt);
-          this.directTelemetry?.log({
-            name: "operation.retry",
-            stage: "vault_request",
-            requestCategory: "vault_capture",
-            paymentMethodCategory: "card",
-            attempt
-          });
+      const response = await fetch(
+        `${this.baseUrl}/v1/payments?${params.toString()}`,
+        {
+          method: "GET",
+          signal: options?.signal,
+          keepalive: true
         }
       );
       if (!response.ok) {
-        throw await buildApiErrorFromResponse(response, "Failed to load the secure card form");
+        throw new FloPayError(
+          "Failed to fetch payments",
+          "api_error",
+          { statusCode: response.status }
+        );
       }
-      const block = await response.json();
+      const result = await response.json();
+      this.directTelemetry?.log({
+        name: "operation.recovery.completed",
+        stage: "recovery",
+        requestCategory: "other",
+        paymentMethodCategory: "saved",
+        statusClass: "2xx"
+      });
       this.directTelemetry?.performance({
-        stage: "vault_request",
+        stage: "recovery",
         durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
         durationMode: "machine",
-        requestCategory: "vault_capture",
-        paymentMethodCategory: "card",
+        requestCategory: "other",
+        paymentMethodCategory: "saved",
         statusClass: "2xx"
       });
-      return this.toVaultBlock(block);
+      return result;
     } catch (error) {
-      this.reportDirectFailure(
-        error,
-        "VAULT_LOAD_FAILED",
-        "vault_request",
-        "vault_capture",
-        "card"
-      );
+      this.reportDirectFailure(error, "RECOVERY_FAILED", "recovery", "other", "saved");
       throw error;
     }
   }
   /**
-   * Fetch and normalize a checkout session.
+   * Create a checkout session AND return the full session data in one call.
+   * Uses `?expand=true` so the backend returns the complete session
+   * instead of just a UUID — eliminating the need for a second GET.
    *
-   * Reads the backend's `gateways` map to enumerate provider-specific data,
-   * then wraps the session in a `NormalizedCheckoutSession` for provider-
-   * agnostic consumption.
+   * Falls back to create + GET if the backend doesn't support `expand`.
    */
-  async getUnifiedCheckoutSession(checkoutSessionId, nonce) {
-    const res = await this.getCheckoutSession(checkoutSessionId, nonce);
-    const normalized = this.normalizeRawSession(res.data);
-    const vault = res.vault;
-    if (vault && normalized.data.session) {
-      normalized.data.session.vault = this.toVaultBlock(vault);
+  async createAndFetchSession(params) {
+    this.beginDirectTelemetryOperation();
+    const startedAt = this.telemetryTimestamp();
+    this.directTelemetry?.log({
+      name: "session.create.started",
+      stage: "session_create",
+      requestCategory: "session_create"
+    });
+    try {
+      const result = await this.createAndFetchSessionRequest(params, startedAt);
+      this.adoptDirectTelemetryCheckout(result.data.session?.id);
+      this.directTelemetry?.log({
+        name: "session.request.completed",
+        stage: "session_complete",
+        requestCategory: "session_create",
+        statusClass: "2xx"
+      });
+      this.directTelemetry?.performance({
+        stage: "session_create",
+        durationMs: this.telemetryTimestamp() - startedAt,
+        durationMode: "machine",
+        requestCategory: "session_create",
+        statusClass: "2xx"
+      });
+      return result;
+    } catch (error) {
+      if (!(error instanceof FloPayError && error.code === "session_auto_completed")) {
+        try {
+          this.telemetryHooks?.onSessionCreateFailure?.(error);
+        } catch {
+        }
+      }
+      if (error instanceof FloPayError && error.type === "validation_error") {
+        this.directTelemetry?.terminal({
+          outcome: "validation_rejected",
+          stage: "session_create",
+          requestCategory: "session_create"
+        });
+      } else if (!(error instanceof FloPayError && error.code === "session_auto_completed")) {
+        const statusCode = error instanceof FloPayError ? error.statusCode : void 0;
+        this.directTelemetry?.error({
+          errorCode: error instanceof Error && error.name === "AbortError" ? "REQUEST_TIMEOUT" : error instanceof TypeError ? "NETWORK_REQUEST_FAILED" : "CHECKOUT_SESSION_CREATE_FAILED",
+          stage: "session_create",
+          requestCategory: "session_create",
+          statusClass: error instanceof Error && error.name === "AbortError" ? "timeout" : statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
+        });
+      }
+      throw error;
     }
-    return normalized;
   }
-  /**
-   * Submit a tokenized payment to the billing backend.
-   *
-   * The backend will either succeed, return `type: '3ds_required'`
-   * (with a `threeDSecureToken`), or return `type: 'paypal_redirect_required'`.
-   *
-   * Hits the session-scoped route `POST /v1/checkouts/sessions/:id/process`
-   * and forwards `data.nonce` as `x-checkout-session-token`. Backend
-   * `TeamFloPay/backend#640` rejects callers without a matching nonce with a
-   * 401 — this method throws synchronously when `data.nonce` is missing so the
-   * problem surfaces before the network round trip.
-   *
-   * @param userId Vestigial — backend's GatewayInterceptor routes via session,
-   *   not headers, so this value is no longer sent on the wire. Kept in the
-   *   signature for back-compat with existing callers; will be removed in a
-   *   future major version.
-   */
-  async processPayment(_userId, data, options) {
-    this.beginDirectTelemetryCheckout(data.sessionId);
-    if (!data.nonce) {
-      this.directTelemetry?.terminal({
-        outcome: "validation_rejected",
-        stage: "processing",
-        requestCategory: "process_payment"
-      });
-      throw new FloPayError3(
-        "processPayment requires `nonce` \u2014 pass the value returned from session creation.",
+  async createAndFetchSessionRequest(params, telemetryStartedAt) {
+    const wireProducts = params.products ?? foldIntoProducts(params.items, params.subscriptions);
+    const sessionCurrency = resolveSessionCurrency(
+      params.currency,
+      params.items,
+      params.subscriptions,
+      wireProducts
+    );
+    if (!sessionCurrency) {
+      throw new FloPayError(
+        "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
         "validation_error",
-        { code: "MissingCheckoutSessionToken", param: "nonce" }
+        { code: "CurrencyRequired", param: "currency" }
       );
     }
-    const startedAt = this.telemetryTimestamp();
-    this.directTelemetry?.log({
-      name: "payment.processing.started",
-      stage: "processing",
-      requestCategory: "process_payment"
-    });
-    const { nonce, ...processBody } = data;
+    const payload = {
+      clientId: params.clientId,
+      checkoutVersion: SDK_VERSION,
+      successUrl: params.successUrl,
+      cancelUrl: params.cancelUrl,
+      currency: sessionCurrency,
+      checkoutMode: params.checkoutMode ?? "full",
+      products: wireProducts.map((product) => buildProductPayload(product, sessionCurrency)),
+      accountData: {
+        userId: params.account.userId,
+        firstName: params.account.firstName ?? null,
+        lastName: params.account.lastName ?? null,
+        email: params.account.email,
+        country: params.account.country ?? null,
+        gender: params.account.gender ?? null,
+        city: params.account.city ?? null,
+        state: params.account.state ?? null,
+        zip: params.account.zip ?? null,
+        addressLine1: params.account.addressLine1 ?? null,
+        addressLine2: params.account.addressLine2 ?? null
+      },
+      couponCodes: params.couponCodes ?? []
+    };
+    if (params.tokenizedData) payload["tokenizedData"] = params.tokenizedData;
+    if (params.tagsData) payload["tagsData"] = params.tagsData;
+    if (params.utmMetadata?.length) payload["utmMetadata"] = params.utmMetadata;
+    if (params.avsCheck !== void 0) payload["avsCheck"] = params.avsCheck;
+    if (params.checkoutType) payload["checkoutType"] = params.checkoutType;
+    if (params.checkoutLayout) payload["checkoutLayout"] = params.checkoutLayout;
+    if (params.avsConfig) payload["avsConfig"] = params.avsConfig;
+    const headers = {
+      "Content-Type": "application/json",
+      // Retain the SDK version header for compatibility visibility. Backends
+      // must not gate the hosted vault block on this value.
+      [FLO_SDK_VERSION_HEADER]: SDK_VERSION
+    };
+    const idempotencyKey = resolveIdempotencyKey(params.idempotencyKey);
+    if (idempotencyKey) {
+      headers[IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+    }
     let response;
-    try {
-      response = await fetch(
-        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(data.sessionId)}/process`,
+    let firstByteReported = false;
+    for (let attempt = 0; ; attempt++) {
+      response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
         {
           method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "x-checkout-session-token": nonce
-          },
-          body: JSON.stringify(processBody)
+          headers,
+          body: JSON.stringify(payload)
+        },
+        NETWORK_RETRY_ATTEMPTS,
+        (networkAttempt) => {
+          this.telemetryHooks?.onRetry?.("session_create", networkAttempt);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "session_create",
+            requestCategory: "session_create",
+            attempt: networkAttempt
+          });
         }
       );
-    } catch (error) {
-      this.reportDirectFailure(
-        error,
-        "PAYMENT_PROCESSING_FAILED",
-        "processing",
-        "process_payment"
-      );
-      throw error;
-    }
-    if (!response.ok && response.status !== 202) {
-      this.directTelemetry?.error({
-        errorCode: "PAYMENT_PROCESSING_FAILED",
-        stage: "processing",
-        requestCategory: "process_payment",
-        statusClass: telemetryStatusClass(response.status)
-      });
-      return response;
-    }
-    try {
-      const result = await this.resolveProcessResponse(
-        response,
-        data.sessionId,
-        { ...options, nonce }
-      );
-      this.directTelemetry?.log({
-        name: "payment.processing.completed",
-        stage: "processing",
-        requestCategory: "process_payment",
-        statusClass: telemetryStatusClass(result.status)
-      });
-      this.directTelemetry?.performance({
-        stage: "processing",
-        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
-        durationMode: "machine",
-        requestCategory: "process_payment",
-        statusClass: telemetryStatusClass(result.status)
-      });
-      return result;
-    } catch (error) {
-      if (!(error instanceof FloPayError3 && error.code === "checkout_processing_timeout")) {
-        this.reportDirectFailure(
-          error,
-          "PAYMENT_PROCESSING_FAILED",
-          "processing",
-          "process_payment"
+      if (!firstByteReported) {
+        firstByteReported = true;
+        const statusClass = `${Math.floor(response.status / 100)}xx`;
+        this.directTelemetry?.log({
+          name: "session.request.first_byte",
+          stage: "session_first_byte",
+          requestCategory: "session_create",
+          statusClass
+        });
+        this.directTelemetry?.performance({
+          stage: "session_first_byte",
+          durationMs: this.telemetryTimestamp() - telemetryStartedAt,
+          durationMode: "machine",
+          requestCategory: "session_create",
+          statusClass
+        });
+      }
+      if (response.status === 204) {
+        throw new FloPayError(
+          "Session auto-completed \u2014 payment method already on file",
+          "api_error",
+          { code: "session_auto_completed" }
         );
       }
+      if (response.ok) break;
+      const error = await buildApiErrorFromResponse(response, "Failed to create checkout session");
+      if (error.code === IDEMPOTENCY_IN_PROGRESS_CODE && attempt < IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS) {
+        try {
+          this.telemetryHooks?.onRetry?.("session_create", attempt + 1);
+          this.directTelemetry?.log({
+            name: "operation.retry",
+            stage: "session_create",
+            requestCategory: "session_create",
+            attempt: attempt + 1
+          });
+        } catch {
+        }
+        await delay(150 * 2 ** attempt);
+        continue;
+      }
       throw error;
     }
+    const body = await response.json();
+    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 {
+        ...normalized,
+        autoProcessingError: body.autoProcessingError,
+        autoProcessingAttempted: body.autoProcessingAttempted,
+        autoProcessingPending: body.autoProcessingPending
+      };
+    }
+    const uuid = body.data?.uuid;
+    if (!uuid) {
+      throw new FloPayError("No session ID returned", "api_error");
+    }
+    this.autoCacheDisplayData(uuid, params);
+    this.adoptDirectTelemetryCheckout(uuid);
+    const unifiedSession = await this.getUnifiedCheckoutSession(uuid);
+    return {
+      ...unifiedSession,
+      autoProcessingError: body.autoProcessingError,
+      autoProcessingAttempted: body.autoProcessingAttempted,
+      autoProcessingPending: body.autoProcessingPending
+    };
   }
-  /**
-   * 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, options) {
-    this.beginDirectTelemetryCheckout(sessionId);
+  async waitForCheckoutSessionCompletion(checkoutSessionId, options) {
+    this.beginDirectTelemetryCheckout(checkoutSessionId);
     const startedAt = this.telemetryTimestamp();
     this.directTelemetry?.log({
-      name: "operation.state_transition",
-      stage: "processing",
-      requestCategory: "account_snapshot"
+      name: "operation.recovery.started",
+      stage: "recovery",
+      requestCategory: "session_read",
+      paymentMethodCategory: "saved"
     });
-    const timeoutMs = options?.timeoutMs ?? DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const onCallerAbort = () => controller.abort();
-    if (options?.signal) {
-      if (options.signal.aborted) controller.abort();
-      else options.signal.addEventListener("abort", onCallerAbort, { once: true });
-    }
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_PROCESSING_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    let nextDelayMs = this.clampRetryAfterMs(options?.initialDelayMs ?? DEFAULT_PROCESSING_RETRY_AFTER_MS);
+    let pollAttempt = 0;
     try {
-      let response;
-      try {
-        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),
-            signal: controller.signal
-          },
-          NETWORK_RETRY_ATTEMPTS,
-          (attempt) => {
-            this.telemetryHooks?.onRetry?.("account_snapshot", attempt);
+      while (true) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw createCheckoutProcessingTimeoutError();
+        }
+        if (nextDelayMs > 0) {
+          try {
+            pollAttempt += 1;
+            this.telemetryHooks?.onRetry?.("session_read", pollAttempt);
             this.directTelemetry?.log({
               name: "operation.retry",
-              stage: "processing",
-              requestCategory: "account_snapshot",
-              attempt
+              stage: "recovery",
+              requestCategory: "session_read",
+              paymentMethodCategory: "saved",
+              attempt: pollAttempt
             });
+          } catch {
+          }
+          await delay(Math.min(nextDelayMs, remainingMs));
+          if (Date.now() >= deadline) {
+            throw createCheckoutProcessingTimeoutError();
           }
+        }
+        const session = await this.getUnifiedCheckoutSession(checkoutSessionId, options?.nonce);
+        const status = session.data.session?.status;
+        if (status === "complete" || status === "expired") {
+          this.directTelemetry?.log({
+            name: "operation.recovery.completed",
+            stage: "recovery",
+            requestCategory: "session_read",
+            paymentMethodCategory: "saved"
+          });
+          this.directTelemetry?.performance({
+            stage: "recovery",
+            durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
+            durationMode: "machine",
+            requestCategory: "session_read",
+            paymentMethodCategory: "saved"
+          });
+          return session;
+        }
+        if (Date.now() >= deadline) {
+          throw createCheckoutProcessingTimeoutError();
+        }
+        nextDelayMs = this.clampRetryAfterMs(
+          Math.max(nextDelayMs * 2, MIN_PROCESSING_RETRY_AFTER_MS)
         );
-      } finally {
-        clearTimeout(timer);
-        options?.signal?.removeEventListener("abort", onCallerAbort);
-      }
-      if (!response.ok) {
-        throw await buildApiErrorFromResponse(response, "Failed to persist account snapshot");
       }
-      this.directTelemetry?.performance({
-        stage: "processing",
-        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
-        durationMode: "machine",
-        requestCategory: "account_snapshot",
-        statusClass: "2xx"
-      });
     } catch (error) {
-      this.reportDirectFailure(
-        error,
-        "NETWORK_REQUEST_FAILED",
-        "processing",
-        "account_snapshot"
-      );
+      if (error instanceof FloPayError && error.code === "checkout_processing_timeout") {
+        this.reportDirectFailure(
+          error,
+          "RECOVERY_FAILED",
+          "recovery",
+          "session_read",
+          "saved"
+        );
+      }
       throw error;
     }
   }
-  /**
-   * Create a PaymentIntent on the backend.
-   *
-   * Used by the Stripe flow to create a server-side PaymentIntent
-   * with the client's payment method attached.
-   *
-   * Forwards `options.nonce` as `x-checkout-session-token` when supplied — the
-   * 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) {
-    this.beginDirectTelemetryCheckout(sessionId);
-    const startedAt = this.telemetryTimestamp();
-    this.directTelemetry?.log({
-      name: "payment.intent.started",
-      stage: "processing",
-      requestCategory: "intent_create"
-    });
-    const headers = { "Content-Type": "application/json" };
-    if (options?.nonce) headers["x-checkout-session-token"] = options.nonce;
-    try {
-      const response = await fetch(
-        `${this.baseUrl}/v1/checkouts/payments/intents`,
-        {
-          method: "POST",
-          headers,
-          body: JSON.stringify({
-            sessionId,
-            email,
-            paymentMethodType: paymentMethodType ?? null,
-            isPaypal: options?.isPaypal ?? false
-          }),
-          signal: options?.signal
-        }
-      );
-      if (!response.ok) {
-        this.directTelemetry?.error({
-          errorCode: "PAYMENT_PROCESSING_FAILED",
-          stage: "processing",
-          requestCategory: "intent_create",
-          statusClass: telemetryStatusClass(response.status)
-        });
-        return response;
-      }
-      this.directTelemetry?.log({
-        name: "payment.intent.completed",
-        stage: "processing",
-        requestCategory: "intent_create",
-        statusClass: telemetryStatusClass(response.status)
-      });
-      this.directTelemetry?.performance({
-        stage: "processing",
-        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
-        durationMode: "machine",
-        requestCategory: "intent_create",
-        statusClass: telemetryStatusClass(response.status)
-      });
-      return response;
-    } catch (error) {
-      this.reportDirectFailure(
-        error,
-        "PAYMENT_PROCESSING_FAILED",
-        "processing",
-        "intent_create"
-      );
-      throw error;
+  /** Normalize a raw session into a provider-agnostic shape. */
+  normalizeRawSession(session) {
+    const gateways = session.gateways ?? {};
+    const providers = [];
+    const data = {
+      session: this.toCheckoutSession(session)
+    };
+    const stripeGateway = gateways.stripe;
+    if (stripeGateway?.publishableKey) {
+      providers.push("stripe");
+      const rawSession = session;
+      const stripeClientSecret = [
+        rawSession["stripeClientSecret"],
+        stripeGateway.stripeClientSecret
+      ].find((value) => typeof value === "string" && value.length > 0);
+      data.stripe = {
+        clientSecret: stripeClientSecret ?? "",
+        publishableKey: stripeGateway.publishableKey ?? void 0,
+        paypalPublishableKey: stripeGateway.paypalPublishableKey ?? void 0,
+        environment: stripeGateway.environment,
+        enabledPaymentMethods: Array.isArray(stripeGateway.enabledPaymentMethods) ? stripeGateway.enabledPaymentMethods.filter((m) => typeof m === "string") : void 0
+      };
+    }
+    const paypalGateway = gateways.paypal;
+    if (paypalGateway?.publishableKey) {
+      providers.push("paypal");
+      data.paypal = {
+        publishableKey: paypalGateway.publishableKey,
+        environment: paypalGateway.environment
+      };
     }
+    return {
+      providers,
+      mode: "tokenize",
+      data,
+      raw: { data: session }
+    };
+  }
+  /** Convert raw session to the SDK CheckoutSession shape. */
+  toCheckoutSession(raw) {
+    const rawProducts = raw.products ?? [];
+    const hasBackendTotal = typeof raw.totalAmount === "number" && Number.isFinite(raw.totalAmount);
+    const computedTotal = rawProducts.reduce(
+      (sum, p) => sum + (p.overrideAmount ?? p.totalAmount ?? 0),
+      0
+    );
+    const totalAmount = hasBackendTotal ? raw.totalAmount : computedTotal;
+    const amountInCents = Math.round(totalAmount * 100);
+    const currency = raw.currency ?? rawProducts[0]?.currency ?? "USD";
+    const mode = rawProducts.some((p) => p.type === "subscription") ? "subscription" : "payment";
+    return {
+      id: raw.uuid,
+      clientSecret: raw.nonce,
+      mode,
+      status: this.toCheckoutSessionStatus(raw.status),
+      amount: amountInCents,
+      currency,
+      customer: {
+        id: raw.accountData.userId,
+        email: raw.accountData.email,
+        firstName: raw.accountData.firstName,
+        lastName: raw.accountData.lastName,
+        country: raw.accountData.country ?? void 0,
+        city: raw.accountData.city ?? void 0,
+        state: raw.accountData.state ?? void 0,
+        zip: raw.accountData.zip ?? void 0,
+        gender: raw.accountData.gender ?? void 0,
+        line1: raw.accountData.addressLine1 ?? void 0,
+        line2: raw.accountData.addressLine2 ?? void 0
+      },
+      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,
+        overrideAmount: typeof p.overrideAmount === "number" ? p.overrideAmount : null,
+        currency: typeof p.currency === "string" ? p.currency : void 0,
+        metadata: p.metadata ?? null
+      })),
+      successUrl: raw.successUrl,
+      cancelUrl: raw.cancelUrl,
+      coupons: raw.coupons,
+      subtotalAmount: raw.subtotalAmount,
+      discountAmount: raw.discountAmount,
+      totalAmount: raw.totalAmount,
+      createdAt: raw.createdAt,
+      gateways: raw.gateways,
+      accountData: raw.accountData,
+      tagsData: raw.tagsData
+    };
   }
   /**
-   * Create a SetupIntent for saving payment methods.
-   *
-   * Forwards `options.nonce` as `x-checkout-session-token` when supplied —
-   * required by post-#640 backends, ignored by earlier versions.
+   * 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).
    */
-  async createSetupIntent(sessionId, email, paymentMethodType, options) {
-    this.beginDirectTelemetryCheckout(sessionId);
-    const startedAt = this.telemetryTimestamp();
-    this.directTelemetry?.log({
-      name: "payment.intent.started",
-      stage: "processing",
-      requestCategory: "intent_create"
-    });
-    const headers = { "Content-Type": "application/json" };
-    if (options?.nonce) headers["x-checkout-session-token"] = options.nonce;
-    try {
-      const response = await fetch(
-        `${this.baseUrl}/v1/checkouts/payments/setup-intents`,
-        {
-          method: "POST",
-          headers,
-          body: JSON.stringify({ sessionId, email, paymentMethodType }),
-          signal: options?.signal
-        }
-      );
-      if (!response.ok) {
-        this.directTelemetry?.error({
-          errorCode: "PAYMENT_PROCESSING_FAILED",
-          stage: "processing",
-          requestCategory: "intent_create",
-          statusClass: telemetryStatusClass(response.status)
-        });
-        return response;
-      }
-      this.directTelemetry?.log({
-        name: "payment.intent.completed",
-        stage: "processing",
-        requestCategory: "intent_create",
-        statusClass: telemetryStatusClass(response.status)
-      });
-      this.directTelemetry?.performance({
-        stage: "processing",
-        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
-        durationMode: "machine",
-        requestCategory: "intent_create",
-        statusClass: telemetryStatusClass(response.status)
-      });
+  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";
+    }
+    if (status === "expired") {
+      return "expired";
+    }
+    return "open";
+  }
+  async resolveProcessResponse(response, checkoutSessionId, options) {
+    if (response.status !== 202) {
       return response;
-    } catch (error) {
-      this.reportDirectFailure(
-        error,
-        "PAYMENT_PROCESSING_FAILED",
-        "processing",
-        "intent_create"
+    }
+    const payload = await response.json().catch(() => null);
+    const pending = this.toCheckoutProcessingPending(payload, response, checkoutSessionId);
+    const session = await this.waitForCheckoutSessionCompletion(pending.sessionId, {
+      initialDelayMs: pending.retryAfterMs,
+      timeoutMs: options?.pollTimeoutMs,
+      nonce: options?.nonce
+    });
+    if (session.data.session?.status === "complete") {
+      return new Response(null, { status: 204, statusText: "No Content" });
+    }
+    if (session.data.session?.status === "expired") {
+      throw new FloPayError(
+        "Checkout session has expired.",
+        "api_error",
+        { code: "checkout_session_expired" }
       );
-      throw error;
     }
+    throw createCheckoutProcessingTimeoutError();
+  }
+  toCheckoutProcessingPending(payload, response, checkoutSessionId) {
+    const retryAfterHeader = response.headers.get("Retry-After");
+    const headerRetryAfterSeconds = retryAfterHeader === null || retryAfterHeader.trim() === "" ? void 0 : Number(retryAfterHeader);
+    const headerRetryAfterMs = headerRetryAfterSeconds !== void 0 && Number.isFinite(headerRetryAfterSeconds) ? headerRetryAfterSeconds * 1e3 : void 0;
+    return {
+      type: "checkout_processing",
+      sessionId: readString(payload, "sessionId") ?? checkoutSessionId,
+      retryAfterMs: this.clampRetryAfterMs(
+        readNumber(payload, "retryAfterMs") ?? headerRetryAfterMs ?? DEFAULT_PROCESSING_RETRY_AFTER_MS
+      ),
+      statusUrl: readString(payload, "statusUrl"),
+      sessionUrl: readString(payload, "sessionUrl")
+    };
+  }
+  clampRetryAfterMs(retryAfterMs) {
+    return Math.max(0, Math.min(retryAfterMs, MAX_PROCESSING_RETRY_AFTER_MS));
   }
   /**
-   * Fetch user's prior payments by email.
-   * Used to determine if saved card UX should be shown.
+   * Stash the display-only fields the consumer passed into a create-session
+   * call. Runs after the backend assigns a UUID so a later GET on the same
+   * session (typically after a redirect) can fill in fields the backend no
+   * longer persists — `overrideAmount`, `totalAmount`, `name`, etc.
+   *
+   * No-op when no UUID is available.
    */
-  async getPaymentsByEmail(email, options) {
-    this.beginDirectTelemetryOperation();
-    const startedAt = this.telemetryTimestamp();
-    this.directTelemetry?.log({
-      name: "operation.recovery.started",
-      stage: "recovery",
-      requestCategory: "other",
-      paymentMethodCategory: "saved"
+  autoCacheDisplayData(sessionId, params) {
+    if (!sessionId) return;
+    const products = params.products ?? foldIntoProducts(params.items, params.subscriptions);
+    if (products.length === 0 && !params.currency) {
+      return;
+    }
+    const usingUnifiedProducts = params.products !== void 0;
+    const sessionCurrency = resolveSessionCurrency(
+      params.currency,
+      usingUnifiedProducts ? void 0 : params.items,
+      usingUnifiedProducts ? void 0 : params.subscriptions,
+      products
+    );
+    cacheSessionDisplayData(sessionId, {
+      currency: sessionCurrency ?? void 0,
+      products: products.map((p) => ({
+        code: p.code ?? p.providerItemId ?? p.providerPlanId,
+        type: p.type,
+        name: p.name ?? p.itemName ?? p.providerItemName ?? p.subscriptionName ?? p.providerPlanName ?? null,
+        totalAmount: p.totalAmount,
+        overrideAmount: p.overrideAmount,
+        currency: p.currency ?? sessionCurrency ?? void 0
+      }))
     });
-    const page = options?.page ?? 1;
-    const limit = options?.limit ?? 1;
-    const params = new URLSearchParams({
-      email,
-      page: String(page),
-      limit: String(limit),
-      sortField: "createdAt",
-      sortDirection: "DESC"
+  }
+  /**
+   * Merge cached display-only fields (set by {@link cacheSessionDisplayData})
+   * into a raw session response. Server values always win — cache fills in
+   * only where the server returned `null` / `undefined`.
+   */
+  mergeCachedDisplayData(raw) {
+    const cached = getSessionDisplayData(raw.uuid);
+    const cachedProducts = /* @__PURE__ */ new Map();
+    const productKey = (code) => code ? `code:${code}` : void 0;
+    for (const p of cached?.products ?? []) {
+      const key = productKey(p.code);
+      if (key) cachedProducts.set(key, p);
+    }
+    const mergedProducts = (raw.products ?? []).map((p) => {
+      const key = productKey(p.code);
+      const fallback = key ? cachedProducts.get(key) : void 0;
+      return {
+        ...p,
+        name: p.name ?? fallback?.name ?? null,
+        totalAmount: p.totalAmount ?? fallback?.totalAmount,
+        overrideAmount: p.overrideAmount ?? fallback?.overrideAmount,
+        currency: p.currency ?? fallback?.currency
+      };
     });
-    try {
-      const response = await fetch(
-        `${this.baseUrl}/v1/payments?${params.toString()}`,
-        {
-          method: "GET",
-          signal: options?.signal,
-          keepalive: true
+    return {
+      ...raw,
+      currency: raw.currency ?? cached?.currency,
+      products: mergedProducts
+    };
+  }
+};
+function createInstrumentedPaymentAPI(billingApiUrl, hooks) {
+  const InstrumentedPaymentAPI = PaymentAPI;
+  return new InstrumentedPaymentAPI(billingApiUrl, hooks);
+}
+
+// src/stripe-adapter.ts
+function toStripeElementType(type) {
+  const map = {
+    payment: "payment",
+    address: "address"
+  };
+  return map[type];
+}
+function toStripeAppearanceTheme(theme) {
+  switch (theme) {
+    case "night":
+      return "night";
+    case "flat":
+      return "flat";
+    // 'default', 'none', undefined, or any unexpected value → Stripe's baseline.
+    default:
+      return "stripe";
+  }
+}
+function paymentMethodTypesKey(paymentMethodTypes) {
+  return paymentMethodTypes ? JSON.stringify(paymentMethodTypes.map((paymentMethodType) => paymentMethodType.trim().toLowerCase())) : null;
+}
+function wrapStripeElement(stripeElement) {
+  const el = stripeElement;
+  return {
+    mount(container) {
+      el.mount(container);
+    },
+    unmount() {
+      el.unmount();
+    },
+    update(options) {
+      el.update(options);
+    },
+    on(event, handler) {
+      el["on"]?.(event, handler);
+    },
+    off(event, handler) {
+      el["off"]?.(event, handler);
+    },
+    destroy() {
+      el.destroy();
+    }
+  };
+}
+function toStripeBillingDetails(billing) {
+  return {
+    billing_details: {
+      ...billing.email ? { email: billing.email } : {},
+      ...billing.name ? { name: billing.name } : {},
+      ...billing.address ? {
+        address: {
+          ...billing.address.country ? { country: billing.address.country } : {},
+          ...billing.address.postal_code ? { postal_code: billing.address.postal_code } : {},
+          ...billing.address.city ? { city: billing.address.city } : {},
+          ...billing.address.line1 ? { line1: billing.address.line1 } : {},
+          ...billing.address.line2 ? { line2: billing.address.line2 } : {},
+          ...billing.address.state ? { state: billing.address.state } : {}
         }
-      );
-      if (!response.ok) {
-        throw new FloPayError3(
-          "Failed to fetch payments",
-          "api_error",
-          { statusCode: response.status }
-        );
-      }
-      const result = await response.json();
-      this.directTelemetry?.log({
-        name: "operation.recovery.completed",
-        stage: "recovery",
-        requestCategory: "other",
-        paymentMethodCategory: "saved",
-        statusClass: "2xx"
-      });
-      this.directTelemetry?.performance({
-        stage: "recovery",
-        durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
-        durationMode: "machine",
-        requestCategory: "other",
-        paymentMethodCategory: "saved",
-        statusClass: "2xx"
-      });
-      return result;
-    } catch (error) {
-      this.reportDirectFailure(error, "RECOVERY_FAILED", "recovery", "other", "saved");
-      throw error;
+      } : {}
     }
+  };
+}
+var StripeAdapter = class {
+  constructor() {
+    this.name = "stripe";
+    this.stripe = null;
+    this.elements = null;
+    // Serialized appearance currently applied to `this.elements`. Used to detect
+    // when consumers swap themes mid-session so we can live-update the Stripe
+    // Elements group instead of returning a stale-styled cache. `null` while no
+    // elements group exists.
+    this.appliedAppearanceKey = null;
+    this.appliedPaymentMethodTypesKey = null;
+    this.appliedClientSecret = null;
+    this.verifiedClientSecret = null;
+    this.verifiedPaymentMethodTypesKey = null;
   }
-  /**
-   * Create a checkout session AND return the full session data in one call.
-   * Uses `?expand=true` so the backend returns the complete session
-   * instead of just a UUID — eliminating the need for a second GET.
-   *
-   * Falls back to create + GET if the backend doesn't support `expand`.
-   */
-  async createAndFetchSession(params) {
-    this.beginDirectTelemetryOperation();
-    const startedAt = this.telemetryTimestamp();
-    this.directTelemetry?.log({
-      name: "session.create.started",
-      stage: "session_create",
-      requestCategory: "session_create"
+  async initialize(config) {
+    if (typeof window === "undefined") {
+      return;
+    }
+    const stripe = await loadStripe(config.publishableKey, {
+      locale: config.locale ?? "auto"
     });
-    try {
-      const result = await this.createAndFetchSessionRequest(params, startedAt);
-      this.adoptDirectTelemetryCheckout(result.data.session?.id);
-      this.directTelemetry?.log({
-        name: "session.request.completed",
-        stage: "session_complete",
-        requestCategory: "session_create",
-        statusClass: "2xx"
-      });
-      this.directTelemetry?.performance({
-        stage: "session_create",
-        durationMs: this.telemetryTimestamp() - startedAt,
-        durationMode: "machine",
-        requestCategory: "session_create",
-        statusClass: "2xx"
-      });
-      return result;
-    } catch (error) {
-      if (!(error instanceof FloPayError3 && error.code === "session_auto_completed")) {
-        try {
-          this.telemetryHooks?.onSessionCreateFailure?.(error);
-        } catch {
+    if (!stripe) {
+      throw new FloPayError2(
+        "Failed to initialize Stripe. Check your publishable key.",
+        "authentication_error"
+      );
+    }
+    this.stripe = stripe;
+  }
+  /** Lazily creates the Stripe Elements group for the given options. */
+  getElements(options) {
+    if (!this.stripe) {
+      throw new FloPayError2(
+        "StripeAdapter not initialized. Call initialize() first.",
+        "api_error"
+      );
+    }
+    const stripeAppearance = options?.appearance ? {
+      theme: toStripeAppearanceTheme(options.appearance.theme),
+      variables: options.appearance.variables,
+      rules: options.appearance.rules
+    } : void 0;
+    const nextAppearanceKey = stripeAppearance ? JSON.stringify(stripeAppearance) : null;
+    const nextPaymentMethodTypesKey = paymentMethodTypesKey(options?.paymentMethodTypes);
+    const nextClientSecret = options?.clientSecret ?? null;
+    if (this.elements && nextPaymentMethodTypesKey && (nextPaymentMethodTypesKey !== this.appliedPaymentMethodTypesKey || nextClientSecret !== this.appliedClientSecret)) {
+      this.elements = null;
+      this.appliedAppearanceKey = null;
+      this.appliedPaymentMethodTypesKey = null;
+      this.appliedClientSecret = null;
+      this.verifiedClientSecret = null;
+      this.verifiedPaymentMethodTypesKey = 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 if (deferredAmount > 0) {
+        elementsOptions = {
+          mode: "payment",
+          amount: deferredAmount,
+          currency: deferredCurrency,
+          paymentMethodCreation
+        };
+        if (options?.setupFutureUsage) {
+          elementsOptions["setupFutureUsage"] = options.setupFutureUsage;
         }
+      } else {
+        elementsOptions = {
+          mode: "setup",
+          currency: deferredCurrency,
+          paymentMethodCreation
+        };
       }
-      if (error instanceof FloPayError3 && error.type === "validation_error") {
-        this.directTelemetry?.terminal({
-          outcome: "validation_rejected",
-          stage: "session_create",
-          requestCategory: "session_create"
-        });
-      } else if (!(error instanceof FloPayError3 && error.code === "session_auto_completed")) {
-        const statusCode = error instanceof FloPayError3 ? error.statusCode : void 0;
-        this.directTelemetry?.error({
-          errorCode: error instanceof Error && error.name === "AbortError" ? "REQUEST_TIMEOUT" : error instanceof TypeError ? "NETWORK_REQUEST_FAILED" : "CHECKOUT_SESSION_CREATE_FAILED",
-          stage: "session_create",
-          requestCategory: "session_create",
-          statusClass: error instanceof Error && error.name === "AbortError" ? "timeout" : statusCode ? `${Math.floor(statusCode / 100)}xx` : "network_error"
-        });
+      if (!options?.clientSecret && options?.paymentMethodTypes) {
+        elementsOptions["paymentMethodTypes"] = options.paymentMethodTypes;
       }
-      throw error;
+      if (stripeAppearance) {
+        elementsOptions["appearance"] = stripeAppearance;
+      }
+      this.elements = this.stripe.elements(elementsOptions);
+      this.appliedAppearanceKey = nextAppearanceKey;
+      this.appliedPaymentMethodTypesKey = nextPaymentMethodTypesKey;
+      this.appliedClientSecret = nextClientSecret;
+      this.verifiedClientSecret = null;
+      this.verifiedPaymentMethodTypesKey = null;
+    } else if (nextAppearanceKey !== this.appliedAppearanceKey) {
+      this.elements.update({
+        appearance: stripeAppearance ?? {}
+      });
+      this.appliedAppearanceKey = nextAppearanceKey;
     }
+    return this.elements;
   }
-  async createAndFetchSessionRequest(params, telemetryStartedAt) {
-    const wireProducts = params.products ?? foldIntoProducts(params.items, params.subscriptions);
-    const sessionCurrency = resolveSessionCurrency(
-      params.currency,
-      params.items,
-      params.subscriptions,
-      wireProducts
+  async assertClientSecretPaymentMethods(clientSecret, allowedPaymentMethodTypes) {
+    if (!this.stripe) {
+      throw new FloPayError2(
+        "StripeAdapter not initialized. Call initialize() first.",
+        "api_error"
+      );
+    }
+    let intent;
+    let retrievalFailed = false;
+    if (isSetupIntentClientSecret(clientSecret)) {
+      const { setupIntent, error } = await this.stripe.retrieveSetupIntent(clientSecret);
+      intent = setupIntent;
+      retrievalFailed = Boolean(error);
+    } else {
+      const { paymentIntent, error } = await this.stripe.retrievePaymentIntent(clientSecret);
+      intent = paymentIntent;
+      retrievalFailed = Boolean(error);
+    }
+    const providerPaymentMethodTypes = intent?.payment_method_types;
+    if (retrievalFailed || !Array.isArray(providerPaymentMethodTypes)) {
+      throw new FloPayError2(
+        "Unable to verify the payment methods configured for this client secret.",
+        "api_error",
+        { param: "clientSecret" }
+      );
+    }
+    const allowlist = new Set(
+      allowedPaymentMethodTypes.map((paymentMethodType) => paymentMethodType.toLowerCase())
     );
-    if (!sessionCurrency) {
-      throw new FloPayError3(
-        "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
+    const hasDisallowedProviderMethod = providerPaymentMethodTypes.some(
+      (paymentMethodType) => typeof paymentMethodType !== "string" || !allowlist.has(paymentMethodType.trim().toLowerCase())
+    );
+    if (hasDisallowedProviderMethod || providerPaymentMethodTypes.length === 0) {
+      throw new FloPayError2(
+        "The client-secret intent must enable only declared non-card payment methods.",
         "validation_error",
-        { code: "CurrencyRequired", param: "currency" }
+        { param: "clientSecret" }
       );
     }
-    const payload = {
-      clientId: params.clientId,
-      checkoutVersion: SDK_VERSION,
-      successUrl: params.successUrl,
-      cancelUrl: params.cancelUrl,
-      currency: sessionCurrency,
-      checkoutMode: params.checkoutMode ?? "full",
-      products: wireProducts.map((product) => buildProductPayload(product, sessionCurrency)),
-      accountData: {
-        userId: params.account.userId,
-        firstName: params.account.firstName ?? null,
-        lastName: params.account.lastName ?? null,
-        email: params.account.email,
-        country: params.account.country ?? null,
-        gender: params.account.gender ?? null,
-        city: params.account.city ?? null,
-        state: params.account.state ?? null,
-        zip: params.account.zip ?? null,
-        addressLine1: params.account.addressLine1 ?? null,
-        addressLine2: params.account.addressLine2 ?? null
+  }
+  async createElement(type, options) {
+    let resolvedOptions = options;
+    if (type === "payment") {
+      const paymentMethodTypes = options.paymentMethodTypes?.map((paymentMethodType) => paymentMethodType.trim()).filter((paymentMethodType) => paymentMethodType && paymentMethodType.toLowerCase() !== "card");
+      if (!paymentMethodTypes?.length) {
+        throw new FloPayError2(
+          "At least one supported non-card payment method is required.",
+          "validation_error",
+          { param: "paymentMethodTypes" }
+        );
+      }
+      resolvedOptions = { ...options, paymentMethodTypes };
+      if (resolvedOptions.clientSecret) {
+        const resolvedPaymentMethodTypesKey = paymentMethodTypesKey(paymentMethodTypes);
+        const verificationIsCached = Boolean(
+          this.elements && this.appliedClientSecret === resolvedOptions.clientSecret && this.appliedPaymentMethodTypesKey === resolvedPaymentMethodTypesKey && this.verifiedClientSecret === resolvedOptions.clientSecret && this.verifiedPaymentMethodTypesKey === resolvedPaymentMethodTypesKey
+        );
+        if (!verificationIsCached) {
+          await this.assertClientSecretPaymentMethods(
+            resolvedOptions.clientSecret,
+            paymentMethodTypes
+          );
+        }
+      }
+    }
+    const elements = this.getElements(resolvedOptions);
+    if (type === "payment" && resolvedOptions.clientSecret) {
+      this.verifiedClientSecret = resolvedOptions.clientSecret;
+      this.verifiedPaymentMethodTypesKey = paymentMethodTypesKey(
+        resolvedOptions.paymentMethodTypes
+      );
+    }
+    const stripeType = toStripeElementType(type);
+    const elementOptions = {};
+    if (resolvedOptions.layout) {
+      elementOptions["layout"] = resolvedOptions.layout;
+    }
+    if (resolvedOptions.defaultValues) {
+      elementOptions["defaultValues"] = resolvedOptions.defaultValues;
+    }
+    if (resolvedOptions.readOnly) {
+      elementOptions["readOnly"] = resolvedOptions.readOnly;
+    }
+    if (resolvedOptions.mode) {
+      elementOptions["mode"] = resolvedOptions.mode;
+    }
+    const stripeElement = elements.create(stripeType, elementOptions);
+    return wrapStripeElement(stripeElement);
+  }
+  getElement(type) {
+    if (!this.elements) return null;
+    const stripeType = toStripeElementType(type);
+    const existing = this.elements.getElement(stripeType);
+    if (!existing) return null;
+    return wrapStripeElement(existing);
+  }
+  async submitElements() {
+    if (!this.stripe || !this.elements) {
+      return { error: new FloPayError2("Stripe not initialized", "api_error") };
+    }
+    const { error } = await this.elements.submit();
+    if (error) {
+      return {
+        error: new FloPayError2(error.message ?? "Validation failed", "validation_error")
+      };
+    }
+    return {};
+  }
+  async confirmPayment(params) {
+    if (!this.stripe || !this.elements) {
+      throw new FloPayError2(
+        "StripeAdapter not initialized or no elements created.",
+        "api_error"
+      );
+    }
+    const billing = params.billingDetails;
+    const paymentMethodData = billing ? toStripeBillingDetails(billing) : void 0;
+    const { error, paymentIntent } = await this.stripe.confirmPayment({
+      elements: this.elements,
+      clientSecret: params.clientSecret,
+      confirmParams: {
+        return_url: params.returnUrl ?? window.location.href,
+        ...paymentMethodData ? { payment_method_data: paymentMethodData } : {}
       },
-      couponCodes: params.couponCodes ?? []
+      redirect: "if_required"
+    });
+    if (error) {
+      return {
+        status: "failed",
+        error: new FloPayError2(
+          error.message ?? "Payment failed",
+          "api_error",
+          {
+            code: error.code,
+            declineCode: error.decline_code
+          }
+        )
+      };
+    }
+    if (!paymentIntent) {
+      return { status: "failed", error: new FloPayError2("No payment intent returned", "api_error") };
+    }
+    const statusMap = {
+      succeeded: "succeeded",
+      processing: "processing",
+      requires_action: "requires_action",
+      requires_payment_method: "failed",
+      canceled: "failed"
     };
-    if (params.tokenizedData) payload["tokenizedData"] = params.tokenizedData;
-    if (params.tagsData) payload["tagsData"] = params.tagsData;
-    if (params.utmMetadata?.length) payload["utmMetadata"] = params.utmMetadata;
-    if (params.avsCheck !== void 0) payload["avsCheck"] = params.avsCheck;
-    if (params.checkoutType) payload["checkoutType"] = params.checkoutType;
-    if (params.checkoutLayout) payload["checkoutLayout"] = params.checkoutLayout;
-    if (params.avsConfig) payload["avsConfig"] = params.avsConfig;
-    const 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.
-      [FLO_SDK_VERSION_HEADER]: SDK_VERSION
+    return {
+      status: statusMap[paymentIntent.status] ?? "failed",
+      paymentIntentId: paymentIntent.id,
+      paymentMethodId: this.extractPaymentMethodId(paymentIntent.payment_method)
     };
-    const idempotencyKey = resolveIdempotencyKey(params.idempotencyKey);
-    if (idempotencyKey) {
-      headers[IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+  }
+  extractPaymentMethodId(paymentMethod) {
+    if (typeof paymentMethod === "string" && paymentMethod.startsWith("pm_")) {
+      return paymentMethod;
     }
-    let response;
-    let firstByteReported = false;
-    for (let attempt = 0; ; attempt++) {
-      response = await fetchWithNetworkRetry(
-        `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
+    if (paymentMethod && typeof paymentMethod === "object" && typeof paymentMethod.id === "string") {
+      return paymentMethod.id;
+    }
+    return void 0;
+  }
+  async confirmPayPalPayment(params) {
+    if (!this.stripe) {
+      return { status: "failed", error: new FloPayError2("Stripe not initialized", "api_error") };
+    }
+    const baseUrl = params.billingApiUrl.replace(/\/+$/, "");
+    if (this.elements) {
+      const { error: submitError } = await this.elements.submit();
+      if (submitError) {
+        return {
+          status: "failed",
+          error: new FloPayError2(
+            submitError.message ?? "PayPal payment failed",
+            "validation_error",
+            { code: submitError.code }
+          )
+        };
+      }
+    }
+    let intentClientSecret;
+    try {
+      const intent = await new PaymentAPI(baseUrl).createSessionIntent(
+        params.sessionId,
+        params.nonce ?? "",
         {
-          method: "POST",
-          headers,
-          body: JSON.stringify(payload)
-        },
-        NETWORK_RETRY_ATTEMPTS,
-        (networkAttempt) => {
-          this.telemetryHooks?.onRetry?.("session_create", networkAttempt);
-          this.directTelemetry?.log({
-            name: "operation.retry",
-            stage: "session_create",
-            requestCategory: "session_create",
-            attempt: networkAttempt
-          });
+          provider: "stripe",
+          paymentMethodCategory: "wallet",
+          paymentMethodType: "paypal",
+          paymentMethodId: null,
+          intentKind: "payment"
         }
-      );
-      if (!firstByteReported) {
-        firstByteReported = true;
-        const statusClass = `${Math.floor(response.status / 100)}xx`;
-        this.directTelemetry?.log({
-          name: "session.request.first_byte",
-          stage: "session_first_byte",
-          requestCategory: "session_create",
-          statusClass
-        });
-        this.directTelemetry?.performance({
-          stage: "session_first_byte",
-          durationMs: this.telemetryTimestamp() - telemetryStartedAt,
-          durationMode: "machine",
-          requestCategory: "session_create",
-          statusClass
-        });
-      }
-      if (response.status === 204) {
-        throw new FloPayError3(
-          "Session auto-completed \u2014 payment method already on file",
-          "api_error",
-          { code: "session_auto_completed" }
-        );
+      );
+      if (intent.provider !== "stripe") {
+        throw new FloPayError2("Invalid provider returned for PayPal intent", "api_error");
       }
-      if (response.ok) break;
-      const error = await buildApiErrorFromResponse(response, "Failed to create checkout session");
-      if (error.code === IDEMPOTENCY_IN_PROGRESS_CODE && attempt < IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS) {
+      intentClientSecret = intent.clientSecret;
+    } catch (error2) {
+      return {
+        status: "failed",
+        error: error2 instanceof FloPayError2 ? error2 : new FloPayError2("Failed to create PayPal payment intent", "api_error")
+      };
+    }
+    const { error } = await this.stripe.confirmPayment({
+      clientSecret: intentClientSecret,
+      elements: this.elements ?? void 0,
+      confirmParams: { return_url: params.returnUrl }
+    });
+    if (error) {
+      if (params.nonce) {
         try {
-          this.telemetryHooks?.onRetry?.("session_create", attempt + 1);
-          this.directTelemetry?.log({
-            name: "operation.retry",
-            stage: "session_create",
-            requestCategory: "session_create",
-            attempt: attempt + 1
-          });
+          await new PaymentAPI(baseUrl).reportSessionIntentDecline(
+            params.sessionId,
+            params.nonce,
+            {
+              provider: "stripe",
+              paymentMethodCategory: "wallet",
+              paymentMethodType: "paypal",
+              providerDeclineReason: error.code ?? "provider_declined"
+            }
+          );
         } catch {
         }
-        await delay(150 * 2 ** attempt);
-        continue;
-      }
-      throw error;
-    }
-    const body = await response.json();
-    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 {
-        ...normalized,
-        autoProcessingError: body.autoProcessingError,
-        autoProcessingAttempted: body.autoProcessingAttempted,
-        autoProcessingPending: body.autoProcessingPending
+        status: "failed",
+        error: new FloPayError2(error.message ?? "PayPal payment failed", "api_error", { code: error.code })
       };
     }
-    const uuid = body.data?.uuid;
-    if (!uuid) {
-      throw new FloPayError3("No session ID returned", "api_error");
-    }
-    this.autoCacheDisplayData(uuid, params);
-    this.adoptDirectTelemetryCheckout(uuid);
-    const unifiedSession = await this.getUnifiedCheckoutSession(uuid);
     return {
-      ...unifiedSession,
-      autoProcessingError: body.autoProcessingError,
-      autoProcessingAttempted: body.autoProcessingAttempted,
-      autoProcessingPending: body.autoProcessingPending
+      status: "processing"
     };
   }
-  async waitForCheckoutSessionCompletion(checkoutSessionId, options) {
-    this.beginDirectTelemetryCheckout(checkoutSessionId);
-    const startedAt = this.telemetryTimestamp();
-    this.directTelemetry?.log({
-      name: "operation.recovery.started",
-      stage: "recovery",
-      requestCategory: "session_read",
-      paymentMethodCategory: "saved"
-    });
-    const timeoutMs = options?.timeoutMs ?? DEFAULT_PROCESSING_TIMEOUT_MS;
-    const deadline = Date.now() + timeoutMs;
-    let nextDelayMs = this.clampRetryAfterMs(options?.initialDelayMs ?? DEFAULT_PROCESSING_RETRY_AFTER_MS);
-    let pollAttempt = 0;
-    try {
-      while (true) {
-        const remainingMs = deadline - Date.now();
-        if (remainingMs <= 0) {
-          throw createCheckoutProcessingTimeoutError();
-        }
-        if (nextDelayMs > 0) {
-          try {
-            pollAttempt += 1;
-            this.telemetryHooks?.onRetry?.("session_read", pollAttempt);
-            this.directTelemetry?.log({
-              name: "operation.retry",
-              stage: "recovery",
-              requestCategory: "session_read",
-              paymentMethodCategory: "saved",
-              attempt: pollAttempt
-            });
-          } catch {
-          }
-          await delay(Math.min(nextDelayMs, remainingMs));
-          if (Date.now() >= deadline) {
-            throw createCheckoutProcessingTimeoutError();
-          }
-        }
-        const session = await this.getUnifiedCheckoutSession(checkoutSessionId, options?.nonce);
-        const status = session.data.session?.status;
-        if (status === "complete" || status === "expired") {
-          this.directTelemetry?.log({
-            name: "operation.recovery.completed",
-            stage: "recovery",
-            requestCategory: "session_read",
-            paymentMethodCategory: "saved"
-          });
-          this.directTelemetry?.performance({
-            stage: "recovery",
-            durationMs: Math.max(0, this.telemetryTimestamp() - startedAt),
-            durationMode: "machine",
-            requestCategory: "session_read",
-            paymentMethodCategory: "saved"
-          });
-          return session;
-        }
-        if (Date.now() >= deadline) {
-          throw createCheckoutProcessingTimeoutError();
-        }
-        nextDelayMs = this.clampRetryAfterMs(
-          Math.max(nextDelayMs * 2, MIN_PROCESSING_RETRY_AFTER_MS)
-        );
-      }
-    } catch (error) {
-      if (error instanceof FloPayError3 && error.code === "checkout_processing_timeout") {
-        this.reportDirectFailure(
-          error,
-          "RECOVERY_FAILED",
-          "recovery",
-          "session_read",
-          "saved"
-        );
-      }
-      throw error;
+  async resumePayPalPayment() {
+    if (!this.stripe || typeof window === "undefined") return null;
+    const params = new URLSearchParams(window.location.search);
+    const paymentIntentId = params.get("payment_intent");
+    const clientSecret = params.get("payment_intent_client_secret");
+    const redirectStatus = params.get("redirect_status");
+    if (!paymentIntentId || !clientSecret) return null;
+    if (redirectStatus === "failed") {
+      return {
+        status: "failed",
+        error: new FloPayError2("PayPal payment was declined. Please try again.", "api_error")
+      };
     }
-  }
-  /** Normalize a raw session into a provider-agnostic shape. */
-  normalizeRawSession(session) {
-    const gateways = session.gateways ?? {};
-    const providers = [];
-    const data = {
-      session: this.toCheckoutSession(session)
-    };
-    const stripeGateway = gateways.stripe;
-    if (stripeGateway?.publishableKey) {
-      providers.push("stripe");
-      const rawSession = session;
-      const stripeClientSecret = [
-        rawSession["stripeClientSecret"],
-        stripeGateway.stripeClientSecret
-      ].find((value) => typeof value === "string" && value.length > 0);
-      data.stripe = {
-        clientSecret: stripeClientSecret ?? "",
-        publishableKey: stripeGateway.publishableKey ?? void 0,
-        paypalPublishableKey: stripeGateway.paypalPublishableKey ?? void 0,
-        environment: stripeGateway.environment,
-        enabledPaymentMethods: Array.isArray(stripeGateway.enabledPaymentMethods) ? stripeGateway.enabledPaymentMethods.filter((m) => typeof m === "string") : void 0
+    const { paymentIntent, error } = await this.stripe.retrievePaymentIntent(clientSecret);
+    if (error) {
+      return {
+        status: "failed",
+        error: new FloPayError2(error.message ?? "Failed to retrieve PayPal payment", "api_error")
       };
     }
-    const paypalGateway = gateways.paypal;
-    if (paypalGateway?.publishableKey) {
-      providers.push("paypal");
-      data.paypal = {
-        publishableKey: paypalGateway.publishableKey,
-        environment: paypalGateway.environment
+    if (paymentIntent && (paymentIntent.status === "requires_capture" || paymentIntent.status === "succeeded")) {
+      const pmId = typeof paymentIntent.payment_method === "string" ? paymentIntent.payment_method : paymentIntent.payment_method?.id;
+      const url = new URL(window.location.href);
+      url.searchParams.delete("payment_intent");
+      url.searchParams.delete("payment_intent_client_secret");
+      url.searchParams.delete("redirect_status");
+      window.history.replaceState({}, "", url.toString());
+      return {
+        status: paymentIntent.status,
+        paymentIntentId: paymentIntent.id,
+        paymentMethodId: pmId
       };
     }
     return {
-      providers,
-      mode: "tokenize",
-      data,
-      raw: { data: session }
-    };
-  }
-  /** Convert raw session to the SDK CheckoutSession shape. */
-  toCheckoutSession(raw) {
-    const rawProducts = raw.products ?? [];
-    const hasBackendTotal = typeof raw.totalAmount === "number" && Number.isFinite(raw.totalAmount);
-    const computedTotal = rawProducts.reduce(
-      (sum, p) => sum + (p.overrideAmount ?? p.totalAmount ?? 0),
-      0
-    );
-    const totalAmount = hasBackendTotal ? raw.totalAmount : computedTotal;
-    const amountInCents = Math.round(totalAmount * 100);
-    const currency = raw.currency ?? rawProducts[0]?.currency ?? "USD";
-    const mode = rawProducts.some((p) => p.type === "subscription") ? "subscription" : "payment";
-    return {
-      id: raw.uuid,
-      clientSecret: raw.nonce,
-      mode,
-      status: this.toCheckoutSessionStatus(raw.status),
-      amount: amountInCents,
-      currency,
-      customer: {
-        id: raw.accountData.userId,
-        email: raw.accountData.email,
-        firstName: raw.accountData.firstName,
-        lastName: raw.accountData.lastName,
-        country: raw.accountData.country ?? void 0,
-        city: raw.accountData.city ?? void 0,
-        state: raw.accountData.state ?? void 0,
-        zip: raw.accountData.zip ?? void 0,
-        gender: raw.accountData.gender ?? void 0,
-        line1: raw.accountData.addressLine1 ?? void 0,
-        line2: raw.accountData.addressLine2 ?? void 0
-      },
-      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,
-        overrideAmount: typeof p.overrideAmount === "number" ? p.overrideAmount : null,
-        currency: typeof p.currency === "string" ? p.currency : void 0,
-        metadata: p.metadata ?? null
-      })),
-      successUrl: raw.successUrl,
-      cancelUrl: raw.cancelUrl,
-      coupons: raw.coupons,
-      subtotalAmount: raw.subtotalAmount,
-      discountAmount: raw.discountAmount,
-      totalAmount: raw.totalAmount,
-      createdAt: raw.createdAt,
-      gateways: raw.gateways,
-      accountData: raw.accountData,
-      tagsData: raw.tagsData
+      status: "failed",
+      error: new FloPayError2("PayPal payment was not completed. Please try again.", "api_error")
     };
   }
-  /**
-   * 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
-    };
+  getRawProvider() {
+    return this.stripe;
   }
-  toCheckoutSessionStatus(status) {
-    if (status === "completed") {
-      return "complete";
+  createPayPalElements(options) {
+    if (!this.stripe) return null;
+    const elementsOptions = {
+      mode: "payment",
+      amount: options.amount ?? 0,
+      currency: (options.currency ?? "usd").toLowerCase(),
+      captureMethod: "manual"
+    };
+    if (options.setupFutureUsage) {
+      elementsOptions["setupFutureUsage"] = options.setupFutureUsage;
     }
-    if (status === "expired") {
-      return "expired";
+    if (options.appearance) {
+      elementsOptions["appearance"] = {
+        theme: toStripeAppearanceTheme(options.appearance.theme),
+        variables: options.appearance.variables,
+        rules: options.appearance.rules
+      };
     }
-    return "open";
+    return this.stripe.elements(elementsOptions);
   }
-  async resolveProcessResponse(response, checkoutSessionId, options) {
-    if (response.status !== 202) {
-      return response;
+  destroy() {
+    this.elements = null;
+    this.appliedAppearanceKey = null;
+    this.appliedPaymentMethodTypesKey = null;
+    this.appliedClientSecret = null;
+    this.verifiedClientSecret = null;
+    this.verifiedPaymentMethodTypesKey = null;
+    this.stripe = null;
+  }
+};
+
+// src/flopay.ts
+import { FloPayError as FloPayError5, resolveBillingApiUrl as resolveBillingApiUrl2, SDK_VERSION as SDK_VERSION3 } from "@flopay/shared";
+
+// src/elements.ts
+import { FloPayError as FloPayError3 } from "@flopay/shared";
+var FloPayElements = class {
+  constructor(provider, options) {
+    this.elementMap = /* @__PURE__ */ new Map();
+    this.provider = provider;
+    this.baseOptions = options ?? {};
+  }
+  /**
+   * Creates a new element of the given type.
+   * If an element of that type already exists, it is destroyed first.
+   */
+  async create(type, options) {
+    const merged = { ...this.baseOptions, ...options };
+    if (type === "payment") {
+      const paymentMethodTypes = merged.paymentMethodTypes?.map((paymentMethodType) => paymentMethodType.trim()).filter((paymentMethodType) => paymentMethodType && paymentMethodType.toLowerCase() !== "card");
+      if (!paymentMethodTypes?.length) {
+        throw new FloPayError3(
+          "At least one supported non-card payment method is required.",
+          "validation_error",
+          { param: "paymentMethodTypes" }
+        );
+      }
+      merged.paymentMethodTypes = paymentMethodTypes;
     }
-    const payload = await response.json().catch(() => null);
-    const pending = this.toCheckoutProcessingPending(payload, response, checkoutSessionId);
-    const session = await this.waitForCheckoutSessionCompletion(pending.sessionId, {
-      initialDelayMs: pending.retryAfterMs,
-      timeoutMs: options?.pollTimeoutMs,
-      nonce: options?.nonce
-    });
-    if (session.data.session?.status === "complete") {
-      return new Response(null, { status: 204, statusText: "No Content" });
+    const providerExisting = this.provider.getElement(type);
+    if (providerExisting) {
+      this.elementMap.set(type, providerExisting);
+      return providerExisting;
     }
-    if (session.data.session?.status === "expired") {
-      throw new FloPayError3(
-        "Checkout session has expired.",
-        "api_error",
-        { code: "checkout_session_expired" }
-      );
+    const existing = this.elementMap.get(type);
+    if (existing) {
+      existing.destroy();
     }
-    throw createCheckoutProcessingTimeoutError();
-  }
-  toCheckoutProcessingPending(payload, response, checkoutSessionId) {
-    const retryAfterHeader = response.headers.get("Retry-After");
-    const headerRetryAfterSeconds = retryAfterHeader === null || retryAfterHeader.trim() === "" ? void 0 : Number(retryAfterHeader);
-    const headerRetryAfterMs = headerRetryAfterSeconds !== void 0 && Number.isFinite(headerRetryAfterSeconds) ? headerRetryAfterSeconds * 1e3 : void 0;
-    return {
-      type: "checkout_processing",
-      sessionId: readString(payload, "sessionId") ?? checkoutSessionId,
-      retryAfterMs: this.clampRetryAfterMs(
-        readNumber(payload, "retryAfterMs") ?? headerRetryAfterMs ?? DEFAULT_PROCESSING_RETRY_AFTER_MS
-      ),
-      statusUrl: readString(payload, "statusUrl"),
-      sessionUrl: readString(payload, "sessionUrl")
-    };
+    const element = await this.provider.createElement(type, merged);
+    this.elementMap.set(type, element);
+    return element;
   }
-  clampRetryAfterMs(retryAfterMs) {
-    return Math.max(0, Math.min(retryAfterMs, MAX_PROCESSING_RETRY_AFTER_MS));
+  /** Returns a previously created element, or `null`. */
+  getElement(type) {
+    return this.elementMap.get(type) ?? null;
   }
   /**
-   * Stash the display-only fields the consumer passed into a create-session
-   * call. Runs after the backend assigns a UUID so a later GET on the same
-   * session (typically after a redirect) can fill in fields the backend no
-   * longer persists — `overrideAmount`, `totalAmount`, `name`, etc.
+   * Submits all mounted elements for validation.
    *
-   * No-op when no UUID is available.
+   * Returns an object with an optional error if validation fails.
+   * This does NOT confirm the payment — call `floPay.confirmPayment()` for that.
    */
-  autoCacheDisplayData(sessionId, params) {
-    if (!sessionId) return;
-    const products = params.products ?? foldIntoProducts(params.items, params.subscriptions);
-    if (products.length === 0 && !params.currency) {
-      return;
-    }
-    const usingUnifiedProducts = params.products !== void 0;
-    const sessionCurrency = resolveSessionCurrency(
-      params.currency,
-      usingUnifiedProducts ? void 0 : params.items,
-      usingUnifiedProducts ? void 0 : params.subscriptions,
-      products
-    );
-    cacheSessionDisplayData(sessionId, {
-      currency: sessionCurrency ?? void 0,
-      products: products.map((p) => ({
-        code: p.code ?? p.providerItemId ?? p.providerPlanId,
-        type: p.type,
-        name: p.name ?? p.itemName ?? p.providerItemName ?? p.subscriptionName ?? p.providerPlanName ?? null,
-        totalAmount: p.totalAmount,
-        overrideAmount: p.overrideAmount,
-        currency: p.currency ?? sessionCurrency ?? void 0
-      }))
-    });
+  async submit() {
+    return {};
   }
-  /**
-   * Merge cached display-only fields (set by {@link cacheSessionDisplayData})
-   * into a raw session response. Server values always win — cache fills in
-   * only where the server returned `null` / `undefined`.
-   */
-  mergeCachedDisplayData(raw) {
-    const cached = getSessionDisplayData(raw.uuid);
-    const cachedProducts = /* @__PURE__ */ new Map();
-    const productKey = (code) => code ? `code:${code}` : void 0;
-    for (const p of cached?.products ?? []) {
-      const key = productKey(p.code);
-      if (key) cachedProducts.set(key, p);
+  /** Destroys all created elements and clears the internal map. */
+  destroy() {
+    for (const element of this.elementMap.values()) {
+      element.destroy();
     }
-    const mergedProducts = (raw.products ?? []).map((p) => {
-      const key = productKey(p.code);
-      const fallback = key ? cachedProducts.get(key) : void 0;
-      return {
-        ...p,
-        name: p.name ?? fallback?.name ?? null,
-        totalAmount: p.totalAmount ?? fallback?.totalAmount,
-        overrideAmount: p.overrideAmount ?? fallback?.overrideAmount,
-        currency: p.currency ?? fallback?.currency
-      };
-    });
-    return {
-      ...raw,
-      currency: raw.currency ?? cached?.currency,
-      products: mergedProducts
-    };
+    this.elementMap.clear();
   }
 };
-function createInstrumentedPaymentAPI(billingApiUrl, hooks) {
-  const InstrumentedPaymentAPI = PaymentAPI;
-  return new InstrumentedPaymentAPI(billingApiUrl, hooks);
-}
 
 // src/pci-vault-card-capture.ts
 import {
@@ -2847,7 +2861,6 @@ function telemetryProvider(name) {
 var FloPay = class {
   constructor(provider, config, telemetryReporter) {
     this.currentElements = null;
-    this.cardThreeDsStartedAt = /* @__PURE__ */ new Map();
     this.provider = provider;
     this.config = config;
     this.telemetryReporter = telemetryReporter ?? new TelemetryReporter({
@@ -2880,176 +2893,9 @@ var FloPay = class {
   async submitElements() {
     return this.provider.submitElements();
   }
-  /** Create a payment method from the current elements (tokenize card). */
-  async createPaymentMethod(billingDetails) {
-    const started = this.now();
-    const provider = telemetryProvider(this.provider.name);
-    this.telemetryReporter?.log({
-      name: "payment.tokenization.started",
-      stage: "tokenization",
-      provider,
-      paymentMethodCategory: "card"
-    });
-    try {
-      const result = await this.provider.createPaymentMethod(billingDetails);
-      this.telemetryReporter?.performance({
-        stage: "tokenization",
-        durationMs: this.now() - started,
-        durationMode: "machine",
-        provider,
-        paymentMethodCategory: "card"
-      });
-      if (!result.error) {
-        this.telemetryReporter?.log({
-          name: "payment.tokenization.completed",
-          stage: "tokenization",
-          provider,
-          paymentMethodCategory: "card"
-        });
-      } else if (result.error.type !== "validation_error") {
-        this.telemetryReporter?.error({
-          errorCode: "TOKENIZATION_FAILED",
-          stage: "tokenization",
-          provider,
-          paymentMethodCategory: "card"
-        });
-      }
-      return result;
-    } catch (error) {
-      this.telemetryReporter?.performance({
-        stage: "tokenization",
-        durationMs: this.now() - started,
-        durationMode: "machine",
-        provider,
-        paymentMethodCategory: "card"
-      });
-      this.telemetryReporter?.error({
-        errorCode: "TOKENIZATION_FAILED",
-        stage: "tokenization",
-        provider,
-        paymentMethodCategory: "card"
-      });
-      throw error;
-    }
-  }
-  /** Confirm a card payment with a known client secret and payment method ID. */
-  async confirmCardPayment(params) {
-    const provider = telemetryProvider(this.provider.name);
-    const operationStartedAt = this.now();
-    try {
-      const result = await this.provider.confirmCardPayment(params);
-      const completedAt = this.now();
-      const threeDs = result.threeDs;
-      let threeDsFailed = false;
-      if (threeDs?.status === "handoff") {
-        if (this.trackCardThreeDsAttempt(threeDs.attemptId, completedAt)) {
-          this.telemetryReporter?.log({
-            name: "payment.three_ds.handoff",
-            stage: "three_ds_handoff",
-            provider,
-            paymentMethodCategory: "card"
-          });
-          this.telemetryReporter?.performance({
-            stage: "three_ds_handoff",
-            durationMs: completedAt - operationStartedAt,
-            durationMode: "machine",
-            provider,
-            paymentMethodCategory: "card"
-          });
-          this.telemetryReporter?.terminal({
-            outcome: "action_required",
-            stage: "three_ds_handoff",
-            provider,
-            paymentMethodCategory: "card"
-          });
-        }
-      } else if (threeDs) {
-        const threeDsStartedAt = this.takeCardThreeDsAttempt(threeDs.attemptId, completedAt);
-        if (threeDsStartedAt !== void 0) {
-          if (threeDs.status === "returned") {
-            this.telemetryReporter?.log({
-              name: "payment.three_ds.returned",
-              stage: "three_ds_return",
-              provider,
-              paymentMethodCategory: "card"
-            });
-            this.telemetryReporter?.performance({
-              stage: "three_ds_return",
-              durationMs: completedAt - threeDsStartedAt,
-              durationMode: "machine",
-              provider,
-              paymentMethodCategory: "card"
-            });
-          } else {
-            threeDsFailed = true;
-          }
-        }
-      }
-      if (isExpectedDecline(result.error)) {
-        this.telemetryReporter?.terminal({
-          outcome: "payment_declined",
-          provider,
-          paymentMethodCategory: "card"
-        });
-      } else if (result.error?.type === "validation_error") {
-        this.telemetryReporter?.terminal({
-          outcome: "validation_rejected",
-          provider,
-          paymentMethodCategory: "card"
-        });
-      } else if (result.error) {
-        this.telemetryReporter?.error({
-          errorCode: threeDsFailed ? "THREE_DS_FAILED" : "PROVIDER_RUNTIME_FAILED",
-          stage: threeDsFailed ? "three_ds_return" : "processing",
-          provider,
-          paymentMethodCategory: "card"
-        });
-      } else if (!threeDsFailed && threeDs?.status !== "handoff" && result.status === "succeeded") {
-        this.telemetryReporter?.terminal({
-          outcome: "payment_succeeded",
-          provider,
-          paymentMethodCategory: "card"
-        });
-      }
-      return result;
-    } catch (error) {
-      this.telemetryReporter?.error({
-        errorCode: "PROVIDER_RUNTIME_FAILED",
-        stage: "processing",
-        provider,
-        paymentMethodCategory: "card"
-      });
-      throw error;
-    }
-  }
-  trackCardThreeDsAttempt(attemptId, startedAt) {
-    this.pruneExpiredCardThreeDsAttempts(startedAt);
-    if (this.cardThreeDsStartedAt.has(attemptId)) return false;
-    while (this.cardThreeDsStartedAt.size >= MAX_CARD_THREE_DS_ATTEMPTS) {
-      const oldestAttemptId = this.cardThreeDsStartedAt.keys().next().value;
-      if (oldestAttemptId === void 0) break;
-      this.cardThreeDsStartedAt.delete(oldestAttemptId);
-    }
-    this.cardThreeDsStartedAt.set(attemptId, startedAt);
-    return true;
-  }
-  takeCardThreeDsAttempt(attemptId, now) {
-    this.pruneExpiredCardThreeDsAttempts(now);
-    const startedAt = this.cardThreeDsStartedAt.get(attemptId);
-    if (startedAt !== void 0) this.cardThreeDsStartedAt.delete(attemptId);
-    return startedAt;
-  }
-  pruneExpiredCardThreeDsAttempts(now) {
-    for (const [attemptId, startedAt] of this.cardThreeDsStartedAt) {
-      if (now - startedAt >= CARD_THREE_DS_ATTEMPT_TTL_MS) {
-        this.cardThreeDsStartedAt.delete(attemptId);
-      }
-    }
-  }
   /**
    * 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).
+   * backend-rendered hosted vault PCI widget (TeamFloPay/backend#823).
    *
    * The returned adapter injects the server-supplied widget HTML (the session's
    * {@link CheckoutSession.vault} block, or one fetched via
@@ -3238,15 +3084,22 @@ var FloPay = class {
       throw error;
     }
   }
-  /** Confirms a payment using the mounted elements. */
+  /** Confirms a non-card wallet/APM payment using the mounted PaymentElement. */
   async confirmPayment(params) {
+    if (params.paymentMethodCategory !== "wallet" && params.paymentMethodCategory !== "apm" || !params.paymentMethodType?.trim() || params.paymentMethodType.trim().toLowerCase() === "card") {
+      throw new FloPayError5(
+        "A supported non-card payment method is required.",
+        "validation_error",
+        { param: "paymentMethodType" }
+      );
+    }
     const started = this.now();
     const provider = telemetryProvider(this.provider.name);
     this.telemetryReporter?.log({
       name: "payment.processing.started",
       stage: "processing",
       provider,
-      paymentMethodCategory: "unknown"
+      paymentMethodCategory: params.paymentMethodCategory
     });
     try {
       const result = await this.provider.confirmPayment(params);
@@ -3256,39 +3109,39 @@ var FloPay = class {
         durationMs,
         durationMode: "machine",
         provider,
-        paymentMethodCategory: "unknown"
+        paymentMethodCategory: params.paymentMethodCategory
       });
       if (result.status === "succeeded") {
         this.telemetryReporter?.terminal({
           outcome: "payment_succeeded",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       } else if (isExpectedDecline(result.error)) {
         this.telemetryReporter?.terminal({
           outcome: "payment_declined",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       } else if (result.error?.type === "validation_error") {
         this.telemetryReporter?.terminal({
           outcome: "validation_rejected",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       } else if (result.status === "requires_action") {
         this.telemetryReporter?.terminal({
           outcome: "action_required",
           stage: "three_ds_handoff",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       } else if (result.status === "failed" && result.error) {
         this.telemetryReporter?.error({
           errorCode: "PAYMENT_PROCESSING_FAILED",
           stage: "processing",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       }
       if (result.status === "succeeded" || result.status === "failed") {
@@ -3296,14 +3149,14 @@ var FloPay = class {
           name: "payment.processing.completed",
           stage: "processing",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       } else {
         this.telemetryReporter?.log({
           name: "operation.state_transition",
           stage: result.status === "requires_action" ? "three_ds_handoff" : "processing",
           provider,
-          paymentMethodCategory: "unknown"
+          paymentMethodCategory: params.paymentMethodCategory
         });
       }
       return result;
@@ -3313,13 +3166,13 @@ var FloPay = class {
         durationMs: this.now() - started,
         durationMode: "machine",
         provider,
-        paymentMethodCategory: "unknown"
+        paymentMethodCategory: params.paymentMethodCategory
       });
       this.telemetryReporter?.error({
         errorCode: "PAYMENT_PROCESSING_FAILED",
         stage: "processing",
         provider,
-        paymentMethodCategory: "unknown"
+        paymentMethodCategory: params.paymentMethodCategory
       });
       throw error;
     }
@@ -3449,7 +3302,6 @@ var FloPay = class {
   destroy() {
     this.telemetryReporter?.log({ name: "checkout.unmount", stage: "unmount" });
     this.telemetryReporter?.destroy();
-    this.cardThreeDsStartedAt.clear();
     this.currentElements?.destroy();
     this.currentElements = null;
     this.provider.destroy();