@flopay/react 1.3.3 → 1.4.0

package/dist/index.cjs

@@ -69,6 +69,59 @@ var CheckoutContext = (0, import_react.createContext)({
   error: null
 });
 
+// src/telemetry-bridge.ts
+var FLOPAY_TELEMETRY_BRIDGE = /* @__PURE__ */ Symbol.for("@flopay/js.telemetry.bridge.v1");
+var TELEMETRY_REPORTER_FACTORY = /* @__PURE__ */ Symbol.for("@flopay/js.telemetry.reporter-factory.v1");
+function noopTelemetryBridge() {
+  return {
+    error: () => {
+    },
+    log: () => {
+    },
+    performance: () => {
+    },
+    terminal: () => {
+    },
+    now: () => globalThis.performance?.now() ?? 0,
+    elapsed: (startedAt) => Math.max(0, (globalThis.performance?.now() ?? startedAt) - startedAt),
+    setCheckoutContext: () => {
+    },
+    beginCheckout: () => globalThis.performance?.now() ?? 0,
+    disable: () => {
+    },
+    flush: async () => {
+    },
+    destroy: () => {
+    }
+  };
+}
+function normalizeTelemetryBridge(source) {
+  const fallback = noopTelemetryBridge();
+  const bind = (candidate, defaultValue) => candidate ? candidate.bind(source) : defaultValue;
+  const now = bind(source.now, fallback.now);
+  return {
+    error: bind(source.error, fallback.error),
+    log: bind(source.log, fallback.log),
+    performance: bind(source.performance, fallback.performance),
+    terminal: bind(source.terminal, fallback.terminal),
+    now,
+    elapsed: source.elapsed ? source.elapsed.bind(source) : (startedAt) => Math.max(0, now() - startedAt),
+    setCheckoutContext: bind(source.setCheckoutContext, fallback.setCheckoutContext),
+    beginCheckout: bind(source.beginCheckout, fallback.beginCheckout),
+    disable: bind(source.disable, fallback.disable),
+    flush: bind(source.flush, fallback.flush),
+    destroy: bind(source.destroy, fallback.destroy)
+  };
+}
+function createTelemetryBridge(options) {
+  const factory = globalThis[TELEMETRY_REPORTER_FACTORY];
+  return normalizeTelemetryBridge(factory?.(options) ?? {});
+}
+function getFloPayTelemetryBridge(floPay) {
+  if (!floPay) return void 0;
+  return floPay[FLOPAY_TELEMETRY_BRIDGE];
+}
+
 // src/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function FloPayProvider({
@@ -84,6 +137,18 @@ function FloPayProvider({
     paypalFloPayProp instanceof Promise || !paypalFloPayProp ? null : paypalFloPayProp
   );
   const [elements, setElements] = (0, import_react2.useState)(null);
+  const mountedAt = (0, import_react2.useRef)(null);
+  const renderedElements = (0, import_react2.useRef)(null);
+  const interactiveElements = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    if (!flopay) return;
+    const telemetry = getFloPayTelemetryBridge(flopay);
+    mountedAt.current = telemetry?.beginCheckout() ?? telemetry?.now() ?? 0;
+    telemetry?.log({ name: "checkout.mount", stage: "checkout_mount" });
+    return () => {
+      telemetry?.log({ name: "checkout.unmount", stage: "unmount" });
+    };
+  }, [flopay]);
   (0, import_react2.useEffect)(() => {
     let cancelled = false;
     if (floPayProp instanceof Promise) {
@@ -144,10 +209,38 @@ function FloPayProvider({
     options?.paymentMethodCreation,
     options?.setupFutureUsage
   ]);
+  (0, import_react2.useEffect)(() => {
+    if (!flopay || !elements || renderedElements.current === elements) return;
+    renderedElements.current = elements;
+    const telemetry = getFloPayTelemetryBridge(flopay);
+    telemetry?.log({ name: "checkout.rendered", stage: "checkout_render" });
+    telemetry?.performance({
+      stage: "checkout_render",
+      durationMs: telemetry.elapsed(mountedAt.current ?? 0),
+      durationMode: "machine"
+    });
+  }, [elements, flopay]);
+  const reportInteractive = (0, import_react2.useCallback)(() => {
+    if (!flopay || !elements || interactiveElements.current === elements) return;
+    interactiveElements.current = elements;
+    const telemetry = getFloPayTelemetryBridge(flopay);
+    telemetry?.log({ name: "checkout.interactive", stage: "checkout_interactive" });
+    telemetry?.performance({
+      stage: "checkout_interactive",
+      durationMs: telemetry.elapsed(mountedAt.current ?? 0),
+      durationMode: "machine"
+    });
+  }, [elements, flopay]);
   const resolvedBillingApiUrl = (0, import_shared.resolveBillingApiUrl)(options?.billingApiUrl);
   const value = (0, import_react2.useMemo)(
-    () => ({ flopay, paypalFlopay, elements, billingApiUrl: resolvedBillingApiUrl }),
-    [flopay, paypalFlopay, elements, resolvedBillingApiUrl]
+    () => ({
+      flopay,
+      paypalFlopay,
+      elements,
+      billingApiUrl: resolvedBillingApiUrl,
+      reportInteractive
+    }),
+    [flopay, paypalFlopay, elements, resolvedBillingApiUrl, reportInteractive]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FloPayContext.Provider, { value, children });
 }
@@ -241,7 +334,7 @@ function createElementComponent(elementType, displayName) {
   }) {
     const containerRef = (0, import_react4.useRef)(null);
     const elementRef = (0, import_react4.useRef)(null);
-    const { elements } = (0, import_react4.useContext)(FloPayContext);
+    const { elements, reportInteractive } = (0, import_react4.useContext)(FloPayContext);
     (0, import_react4.useEffect)(() => {
       if (!elements || !containerRef.current) return;
       let mounted = true;
@@ -256,7 +349,10 @@ function createElementComponent(elementType, displayName) {
         element.mount(containerRef.current);
         elementRef.current = element;
         if (onChange) element.on("change", onChange);
-        if (onReady) element.on("ready", onReady);
+        element.on("ready", () => {
+          reportInteractive?.();
+          onReady?.();
+        });
         if (onFocus) element.on("focus", onFocus);
         if (onBlur) element.on("blur", onBlur);
         if (onEscape) element.on("escape", onEscape);
@@ -271,7 +367,7 @@ function createElementComponent(elementType, displayName) {
           elementRef.current = null;
         }
       };
-    }, [elements]);
+    }, [elements, reportInteractive]);
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { ref: containerRef, className, id, style });
   }
   ElementComponent.displayName = displayName;
@@ -802,9 +898,77 @@ var import_react8 = require("react");
 var import_paypal_js = require("@paypal/paypal-js");
 var import_js = require("@flopay/js");
 var import_shared4 = require("@flopay/shared");
+
+// src/merchant-callback.ts
+function invokeMerchantCallback(callback) {
+  if (!callback) return;
+  const reportFailure = (error) => {
+    console.error("[FloPay] Merchant callback failed; checkout continued.", error);
+  };
+  try {
+    void Promise.resolve(callback()).catch(reportFailure);
+  } catch (error) {
+    reportFailure(error);
+  }
+}
+
+// src/external-method-recovery.ts
+var EXTERNAL_METHOD_CALLBACK_GRACE_MS = 600;
+function getProviderErrorMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "object" && err !== null) {
+    const message = err.message;
+    return typeof message === "string" ? message : void 0;
+  }
+  return typeof err === "string" ? err : void 0;
+}
+function sanitizeExternalFailureCode(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return /^[a-z0-9_.-]{1,64}$/i.test(trimmed) ? trimmed : void 0;
+}
+function getProviderErrorCode(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const record = err;
+  return sanitizeExternalFailureCode(record.code) ?? sanitizeExternalFailureCode(record.type) ?? sanitizeExternalFailureCode(record.name);
+}
+function getProviderDeclineCode(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  return sanitizeExternalFailureCode(err.decline_code);
+}
+function isProviderDecline(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const type = sanitizeExternalFailureCode(err.type)?.toLowerCase();
+  return type === "card_error" || getProviderDeclineCode(err) !== void 0;
+}
+function isPopupBlockedError(err) {
+  const message = getProviderErrorMessage(err)?.toLowerCase() ?? "";
+  const code = getProviderErrorCode(err)?.toLowerCase() ?? "";
+  const signal = `${code} ${message}`;
+  return signal.includes("popup") && signal.includes("block");
+}
+
+// src/direct-paypal-button.tsx
 var import_jsx_runtime6 = require("react/jsx-runtime");
 var DEFAULT_BUTTON_HEIGHT = 45;
-function DirectPayPalButton({
+var DIRECT_PAYPAL_RECOVERY_MESSAGE = "We couldn't open PayPal. Try again or choose another payment method.";
+var DIRECT_PAYPAL_RECOVERY_ACTION_STYLE = {
+  width: "100%",
+  minHeight: DEFAULT_BUTTON_HEIGHT,
+  margin: "0 0 0.5rem",
+  padding: "0.75rem 0.875rem",
+  border: "1px solid #2563eb",
+  borderRadius: 8,
+  background: "#eff6ff",
+  color: "#1d4ed8",
+  fontSize: "0.95rem",
+  fontWeight: 700,
+  cursor: "pointer"
+};
+function buildDirectPayPalRecoveryMessage(popupBlocked) {
+  return popupBlocked ? `${DIRECT_PAYPAL_RECOVERY_MESSAGE} Allow pop-ups for this site, then try again.` : DIRECT_PAYPAL_RECOVERY_MESSAGE;
+}
+function DirectPayPalButtonImplementation({
   sessionId,
   nonce,
   billingApiUrl,
@@ -817,16 +981,70 @@ function DirectPayPalButton({
   onComplete,
   onErrorChange,
   onDecline,
+  onTechnicalFailure,
   isProcessing = false,
   onLoadStateChange,
   onButtonClick,
   runBeforeButtonClick,
   session,
   existingOrderId,
+  telemetry,
+  telemetryContext,
   debug = false
 }) {
+  const flopay = useFloPay();
+  const standaloneTelemetry = (0, import_react8.useMemo)(() => {
+    if (flopay) return null;
+    const reporter = createTelemetryBridge({
+      billingApiUrl,
+      sdkPackage: "@flopay/react",
+      sdkVersion: import_shared4.SDK_VERSION,
+      enabled: telemetry !== false
+    });
+    reporter.setCheckoutContext(telemetryContext ?? {});
+    reporter.beginCheckout(telemetryContext ?? {});
+    return reporter;
+  }, [
+    billingApiUrl,
+    flopay,
+    telemetry,
+    telemetryContext?.checkoutMode,
+    telemetryContext?.layout
+  ]);
+  const floPayTelemetry = (0, import_react8.useMemo)(() => getFloPayTelemetryBridge(flopay), [flopay]);
+  (0, import_react8.useEffect)(() => () => {
+    if (!standaloneTelemetry) return;
+    void standaloneTelemetry.flush().catch(() => {
+    }).finally(() => standaloneTelemetry.destroy());
+  }, [standaloneTelemetry]);
+  const telemetrySource = (0, import_react8.useMemo)(() => ({
+    error: (input) => {
+      if (floPayTelemetry) floPayTelemetry.error(input);
+      else standaloneTelemetry?.error(input);
+    },
+    log: (input) => {
+      if (floPayTelemetry) floPayTelemetry.log(input);
+      else standaloneTelemetry?.log(input);
+    },
+    performance: (input) => {
+      if (floPayTelemetry) floPayTelemetry.performance(input);
+      else standaloneTelemetry?.performance(input);
+    },
+    terminal: (input) => {
+      if (floPayTelemetry) floPayTelemetry.terminal(input);
+      else standaloneTelemetry?.terminal(input);
+    },
+    startTiming: () => floPayTelemetry?.now() ?? standaloneTelemetry?.now() ?? 0,
+    elapsed: (startedAt) => floPayTelemetry?.elapsed(startedAt) ?? Math.max(0, (standaloneTelemetry?.now() ?? startedAt) - startedAt)
+  }), [floPayTelemetry, standaloneTelemetry]);
   const containerRef = (0, import_react8.useRef)(null);
+  const providerStartedAt = (0, import_react8.useRef)(0);
+  const focusTargetRef = (0, import_react8.useRef)(null);
+  const pendingProviderFocusRef = (0, import_react8.useRef)(false);
   const [ready, setReady] = (0, import_react8.useState)(false);
+  const [renderGeneration, setRenderGeneration] = (0, import_react8.useState)(0);
+  const activeRenderGenerationRef = (0, import_react8.useRef)(0);
+  const [showRetryFocusTarget, setShowRetryFocusTarget] = (0, import_react8.useState)(false);
   const [failed, setFailed] = (0, import_react8.useState)(false);
   const [submitting, setSubmitting] = (0, import_react8.useState)(false);
   const baseUrl = (0, import_react8.useMemo)(() => billingApiUrl.replace(/\/+$/, ""), [billingApiUrl]);
@@ -839,6 +1057,7 @@ function DirectPayPalButton({
   const onCompleteRef = (0, import_react8.useRef)(onComplete);
   const onErrorChangeRef = (0, import_react8.useRef)(onErrorChange);
   const onDeclineRef = (0, import_react8.useRef)(onDecline);
+  const onTechnicalFailureRef = (0, import_react8.useRef)(onTechnicalFailure);
   const onButtonClickRef = (0, import_react8.useRef)(onButtonClick);
   const onLoadStateChangeRef = (0, import_react8.useRef)(onLoadStateChange);
   const runBeforeButtonClickRef = (0, import_react8.useRef)(runBeforeButtonClick);
@@ -846,6 +1065,11 @@ function DirectPayPalButton({
   const emailRef = (0, import_react8.useRef)(email);
   const nonceRef = (0, import_react8.useRef)(nonce);
   const beforeClickRef = (0, import_react8.useRef)(null);
+  const attemptGenerationRef = (0, import_react8.useRef)(0);
+  const attemptRef = (0, import_react8.useRef)(null);
+  const invalidatedAttemptGenerationRef = (0, import_react8.useRef)(null);
+  const attemptContextBySurfaceRef = (0, import_react8.useRef)(/* @__PURE__ */ new Map());
+  const approvalContextByTokenRef = (0, import_react8.useRef)(/* @__PURE__ */ new Map());
   (0, import_react8.useEffect)(() => {
     onTokenizedBodyRef.current = onTokenizedBody;
   }, [onTokenizedBody]);
@@ -858,6 +1082,9 @@ function DirectPayPalButton({
   (0, import_react8.useEffect)(() => {
     onDeclineRef.current = onDecline;
   }, [onDecline]);
+  (0, import_react8.useEffect)(() => {
+    onTechnicalFailureRef.current = onTechnicalFailure;
+  }, [onTechnicalFailure]);
   (0, import_react8.useEffect)(() => {
     onButtonClickRef.current = onButtonClick;
   }, [onButtonClick]);
@@ -877,7 +1104,130 @@ function DirectPayPalButton({
     nonceRef.current = nonce;
   }, [nonce]);
   (0, import_react8.useEffect)(() => {
-    onLoadStateChangeRef.current?.(ready && !failed);
+    activeRenderGenerationRef.current = renderGeneration;
+  }, [renderGeneration]);
+  (0, import_react8.useEffect)(() => {
+    if (showRetryFocusTarget) focusTargetRef.current?.focus();
+  }, [showRetryFocusTarget, renderGeneration]);
+  const focusRetryTarget = (0, import_react8.useCallback)(() => {
+    window.setTimeout(() => {
+      focusTargetRef.current?.focus();
+    }, 0);
+  }, []);
+  const remountPayPalButtons = (0, import_react8.useCallback)(() => {
+    setReady(false);
+    setRenderGeneration((current) => current + 1);
+  }, []);
+  const focusPayPalSurface = (0, import_react8.useCallback)(() => {
+    setShowRetryFocusTarget(false);
+    const target = containerRef.current?.querySelector(
+      'iframe, button, [tabindex]:not([tabindex="-1"])'
+    );
+    (target ?? containerRef.current)?.focus?.();
+  }, []);
+  (0, import_react8.useEffect)(() => {
+    if (!ready || !pendingProviderFocusRef.current) return;
+    pendingProviderFocusRef.current = false;
+    focusPayPalSurface();
+  }, [focusPayPalSurface, ready, renderGeneration]);
+  const notifyTechnicalFailure = (0, import_react8.useCallback)((err, options) => {
+    const handler = onTechnicalFailureRef.current;
+    if (handler) {
+      handler("paypal", err, options);
+      return;
+    }
+    onErrorChangeRef.current?.(
+      buildDirectPayPalRecoveryMessage(options?.popupBlocked ?? isPopupBlockedError(err))
+    );
+  }, []);
+  const clearAttemptTimer = () => {
+    if (attemptRef.current?.timer) {
+      clearTimeout(attemptRef.current.timer);
+      attemptRef.current.timer = null;
+    }
+  };
+  const startAttempt = () => {
+    clearAttemptTimer();
+    const generation = attemptGenerationRef.current + 1;
+    attemptGenerationRef.current = generation;
+    invalidatedAttemptGenerationRef.current = null;
+    attemptRef.current = { generation, timer: null, yieldedControl: false };
+    setShowRetryFocusTarget(false);
+    return generation;
+  };
+  const finishAttempt = (generation) => {
+    if (generation !== void 0 && attemptRef.current?.generation !== generation) return false;
+    clearAttemptTimer();
+    attemptRef.current = null;
+    invalidatedAttemptGenerationRef.current = null;
+    return true;
+  };
+  const invalidateAttempt = (options) => {
+    const generation = options?.generation ?? attemptRef.current?.generation ?? attemptGenerationRef.current;
+    if (!options?.generation || attemptRef.current?.generation === generation) {
+      clearAttemptTimer();
+      attemptRef.current = null;
+    }
+    invalidatedAttemptGenerationRef.current = generation;
+    if (options?.showRetry) setShowRetryFocusTarget(true);
+    if (options?.remount) remountPayPalButtons();
+    if (options?.focus !== false) focusRetryTarget();
+  };
+  const isAttemptActive = (generation) => attemptRef.current?.generation === generation && invalidatedAttemptGenerationRef.current !== generation;
+  const armMissingCallbackRecovery = (attempt) => {
+    if (typeof document !== "undefined" && document.visibilityState !== "visible") return;
+    clearAttemptTimer();
+    attempt.timer = setTimeout(() => {
+      if (attemptRef.current?.generation !== attempt.generation) return;
+      attemptRef.current = null;
+      invalidatedAttemptGenerationRef.current = attempt.generation;
+      notifyTechnicalFailure(
+        new Error("External payment method returned without a terminal callback."),
+        { code: "external_method_missing_terminal_callback" }
+      );
+      setShowRetryFocusTarget(true);
+      remountPayPalButtons();
+      focusRetryTarget();
+    }, EXTERNAL_METHOD_CALLBACK_GRACE_MS);
+  };
+  const scheduleMissingCallbackRecovery = () => {
+    const attempt = attemptRef.current;
+    if (!attempt?.yieldedControl) return;
+    armMissingCallbackRecovery(attempt);
+  };
+  const markAttemptYieldedControl = () => {
+    const attempt = attemptRef.current;
+    if (!attempt) return;
+    attempt.yieldedControl = true;
+    clearAttemptTimer();
+  };
+  const registerApprovalContext = (token) => {
+    const context = beforeClickRef.current;
+    if (context) {
+      approvalContextByTokenRef.current.set(token, context);
+    }
+    return token;
+  };
+  (0, import_react8.useEffect)(() => {
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "visible") {
+        scheduleMissingCallbackRecovery();
+      } else {
+        markAttemptYieldedControl();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    window.addEventListener("focus", scheduleMissingCallbackRecovery);
+    window.addEventListener("blur", markAttemptYieldedControl);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("focus", scheduleMissingCallbackRecovery);
+      window.removeEventListener("blur", markAttemptYieldedControl);
+      clearAttemptTimer();
+    };
+  }, []);
+  (0, import_react8.useEffect)(() => {
+    invokeMerchantCallback(() => onLoadStateChangeRef.current?.(ready && !failed));
   }, [ready, failed]);
   const normalizedEnv = (0, import_shared4.normalizeGatewayEnvironment)(environment);
   (0, import_react8.useEffect)(() => {
@@ -888,6 +1238,13 @@ function DirectPayPalButton({
     if (!clientId) {
       appendDebug("FAIL: clientId empty \u2014 gateway misconfigured");
       setFailed(true);
+      telemetrySource.error({
+        errorCode: "CONFIGURATION_INVALID",
+        stage: "provider_load",
+        provider: "paypal",
+        paymentMethodCategory: "paypal",
+        requestCategory: "provider_sdk"
+      });
       console.error("[FloPay] DirectPayPal: clientId empty \u2014 gateway misconfigured");
       return;
     }
@@ -895,8 +1252,33 @@ function DirectPayPalButton({
       appendDebug("FAIL: containerRef not attached");
       return;
     }
+    providerStartedAt.current = telemetrySource.startTiming();
+    telemetrySource.log({
+      name: "provider.load.started",
+      stage: "provider_load",
+      provider: "paypal",
+      paymentMethodCategory: "paypal"
+    });
     let cancelled = false;
     let activeButtons = null;
+    let overlayStartedAt = null;
+    const finishOverlay = () => {
+      if (overlayStartedAt === null) return;
+      telemetrySource.log({
+        name: "provider.overlay.returned",
+        stage: "overlay_return",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      telemetrySource.performance({
+        stage: "overlay_return",
+        durationMs: telemetrySource.elapsed(overlayStartedAt),
+        durationMode: "buyer",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      overlayStartedAt = null;
+    };
     let rendered = false;
     const container = containerRef.current;
     let containerObserver = null;
@@ -1000,7 +1382,7 @@ function DirectPayPalButton({
       if (cancelled) return;
       if (isZoidLifecycleMessage(message)) return;
       const friendly = applyFriendlyMessageOverride(message) ?? message;
-      onErrorChangeRef.current?.(friendly);
+      invokeMerchantCallback(() => onErrorChangeRef.current?.(friendly));
     };
     const markRenderFailed = (message) => {
       if (cancelled) return;
@@ -1009,29 +1391,60 @@ function DirectPayPalButton({
         return;
       }
       setFailed(true);
+      if (!message.includes("paypal_ineligible")) {
+        telemetrySource.error({
+          errorCode: "PROVIDER_LOAD_FAILED",
+          stage: "provider_load",
+          provider: "paypal",
+          paymentMethodCategory: "paypal",
+          requestCategory: "provider_sdk"
+        });
+      }
       console.error("[FloPay] DirectPayPal load/render failure:", message);
     };
     setFailed(false);
-    const dispatchTokenizedBody = async (body) => {
-      const prepared = beforeClickRef.current;
+    const dispatchTokenizedBody = async (body, prepared = beforeClickRef.current) => {
       const effectiveSessionId = prepared?.sessionId ?? sessionId;
       if (onTokenizedBodyRef.current) {
-        onTokenizedBodyRef.current(body, {
+        await onTokenizedBodyRef.current(body, {
           sessionId: effectiveSessionId,
-          accountPatch: prepared?.accountPatch
+          accountPatch: prepared?.accountPatch,
+          nonce: prepared?.nonce
         });
         return;
       }
+      const processingStartedAt = telemetrySource.startTiming();
+      telemetrySource.log({
+        name: "payment.processing.started",
+        stage: "processing",
+        provider: "paypal",
+        paymentMethodCategory: "paypal"
+      });
+      const finishProcessing = () => {
+        telemetrySource.log({
+          name: "payment.processing.completed",
+          stage: "processing",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+        telemetrySource.performance({
+          stage: "processing",
+          durationMs: telemetrySource.elapsed(processingStartedAt),
+          durationMode: "machine",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+      };
       try {
         const currentSession = sessionRef.current;
         const currentEmail = prepared?.accountPatch?.email ?? emailRef.current;
         const effectiveUserId = prepared?.accountPatch?.userId ?? currentSession?.customer?.id ?? currentSession?.accountData?.userId ?? "";
-        const api = new import_js.PaymentAPI(baseUrl);
+        const api = new import_js.PaymentAPI(baseUrl, { telemetry: false });
         const response = await api.processPayment(
           effectiveUserId,
           {
             sessionId: effectiveSessionId,
-            nonce: nonceRef.current,
+            nonce: prepared?.nonce ?? nonceRef.current,
             tokenizedData: body,
             accountData: {
               userId: effectiveUserId,
@@ -1044,31 +1457,72 @@ function DirectPayPalButton({
           }
         );
         if (response.ok) {
-          onCompleteRef.current?.({ status: "succeeded", checkoutMethod: "paypal" });
+          finishProcessing();
+          telemetrySource.terminal({
+            outcome: "payment_succeeded",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
+        } else {
+          const json = await response.json().catch(() => null);
+          const rawMessage = json?.["message"] ?? "PayPal payment failed.";
+          const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
+          finishProcessing();
+          if (typeof json?.["declineCode"] === "string") {
+            telemetrySource.terminal({
+              outcome: "payment_declined",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+          } else {
+            telemetrySource.error({
+              errorCode: "PAYMENT_PROCESSING_FAILED",
+              stage: "processing",
+              provider: "paypal",
+              paymentMethodCategory: "paypal",
+              requestCategory: "process_payment",
+              statusClass: response.status >= 500 ? "5xx" : response.status >= 400 ? "4xx" : response.status >= 300 ? "3xx" : "unknown"
+            });
+          }
+          forwardError(message);
+          invokeMerchantCallback(() => onDeclineRef.current?.(buildDeclineEvent("paypal", message, {
+            code: json?.["code"],
+            declineCode: json?.["declineCode"]
+          })));
           return;
         }
-        const json = await response.json().catch(() => null);
-        const rawMessage = json?.["message"] ?? "PayPal payment failed.";
-        const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
-        forwardError(message);
-        onDeclineRef.current?.(buildDeclineEvent("paypal", message, {
-          code: json?.["code"],
-          declineCode: json?.["declineCode"]
-        }));
       } catch (err) {
+        finishProcessing();
+        telemetrySource.error({
+          errorCode: "NETWORK_REQUEST_FAILED",
+          stage: "processing",
+          provider: "paypal",
+          paymentMethodCategory: "paypal",
+          requestCategory: "process_payment",
+          statusClass: "network_error"
+        });
         const rawMessage = err instanceof Error ? err.message : "PayPal payment failed.";
         const message = applyFriendlyMessageOverride(rawMessage) ?? rawMessage;
         forwardError(message);
-        onDeclineRef.current?.(buildDeclineEvent("paypal", message));
+        invokeMerchantCallback(() => onDeclineRef.current?.(buildDeclineEvent("paypal", message)));
+        return;
       }
+      invokeMerchantCallback(() => onCompleteRef.current?.({ status: "succeeded", checkoutMethod: "paypal" }));
     };
     const createPaypalIntent = async (fallbackMessage) => {
       const prepared = beforeClickRef.current;
       const effectiveSessionId = prepared?.sessionId ?? sessionId;
       const effectiveEmail = prepared?.accountPatch?.email ?? emailRef.current;
       const intentHeaders = { "Content-Type": "application/json" };
-      const currentNonce = nonceRef.current;
+      const currentNonce = prepared?.nonce ?? nonceRef.current;
       if (currentNonce) intentHeaders["x-checkout-session-token"] = currentNonce;
+      telemetrySource.log({
+        name: "payment.intent.started",
+        stage: "processing",
+        provider: "paypal",
+        paymentMethodCategory: "paypal",
+        requestCategory: "intent_create"
+      });
       const response = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
         method: "POST",
         headers: intentHeaders,
@@ -1087,8 +1541,17 @@ function DirectPayPalButton({
       if (!id) {
         throw new Error(fallbackMessage);
       }
+      telemetrySource.log({
+        name: "payment.intent.completed",
+        stage: "processing",
+        provider: "paypal",
+        paymentMethodCategory: "paypal",
+        requestCategory: "intent_create",
+        statusClass: "2xx"
+      });
       return id;
     };
+    const effectRenderGeneration = renderGeneration;
     appendDebug("loadScript:scheduled (deferred 1 tick)");
     let loadPromise = null;
     const startTimer = setTimeout(() => {
@@ -1120,11 +1583,24 @@ function DirectPayPalButton({
           if (!cancelled && !paypal?.Buttons) appendDebug("FAIL: namespace missing Buttons factory");
           return;
         }
+        telemetrySource.log({
+          name: "provider.availability.checked",
+          stage: "provider_ready",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
         const handleApprove = async (data) => {
+          if (cancelled || activeRenderGenerationRef.current !== effectRenderGeneration) return;
+          const token = data.subscriptionID ?? data.orderID ?? "";
+          const context = token ? approvalContextByTokenRef.current.get(token) : attemptContextBySurfaceRef.current.get(effectRenderGeneration);
+          if (!context || !isAttemptActive(context.generation)) return;
+          if (!finishAttempt(context.generation)) return;
+          approvalContextByTokenRef.current.delete(token);
+          attemptContextBySurfaceRef.current.delete(context.surfaceKey);
+          finishOverlay();
           try {
             setSubmitting(true);
-            onErrorChangeRef.current?.(null);
-            const token = data.subscriptionID ?? data.orderID ?? "";
+            invokeMerchantCallback(() => onErrorChangeRef.current?.(null));
             if (!token) {
               throw new import_shared4.FloPayError(
                 "PayPal did not return an approval token.",
@@ -1135,7 +1611,7 @@ function DirectPayPalButton({
             await dispatchTokenizedBody({
               id: token,
               isPaypal: true
-            });
+            }, context);
           } catch (err) {
             forwardError(err instanceof Error ? err.message : "PayPal capture failed.");
           } finally {
@@ -1151,47 +1627,104 @@ function DirectPayPalButton({
           // matching the Stripe-rendered PayPal flow.
           onClick: async (_data, actions) => {
             const runner = runBeforeButtonClickRef.current;
+            let prepared = {};
             if (runner) {
               try {
                 const beforeClick = await runner("paypal");
                 if (!beforeClick.proceed) {
                   beforeClickRef.current = null;
+                  attemptContextBySurfaceRef.current.delete(effectRenderGeneration);
                   await actions.reject();
                   return;
                 }
-                beforeClickRef.current = {
+                prepared = {
                   sessionId: beforeClick.sessionId,
-                  accountPatch: beforeClick.accountPatch
+                  accountPatch: beforeClick.accountPatch,
+                  nonce: beforeClick.nonce
                 };
               } catch (err) {
                 appendDebug(`onClick:runBeforeButtonClick rejected msg=${(err instanceof Error ? err.message : String(err)).slice(0, 120)}`);
                 beforeClickRef.current = null;
+                attemptContextBySurfaceRef.current.delete(effectRenderGeneration);
                 await actions.reject();
                 return;
               }
-            } else {
-              beforeClickRef.current = null;
             }
-            onButtonClickRef.current?.("paypal");
+            invokeMerchantCallback(() => onButtonClickRef.current?.("paypal"));
+            const generation = startAttempt();
+            const context = {
+              generation,
+              surfaceKey: effectRenderGeneration,
+              ...prepared
+            };
+            beforeClickRef.current = context;
+            attemptContextBySurfaceRef.current.set(effectRenderGeneration, context);
             await actions.resolve();
+            telemetrySource.log({
+              name: "payment.method.selected",
+              stage: "processing",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+            telemetrySource.log({
+              name: "provider.popup.opened",
+              stage: "overlay_open",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+            telemetrySource.log({
+              name: "provider.overlay.opened",
+              stage: "overlay_open",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+            overlayStartedAt = telemetrySource.startTiming();
           },
           // When the SDK is already holding an order/subscription id from a
           // prior backend round-trip (the `paypal_direct_required` retry
           // path), feed it straight to PayPal instead of creating a new one.
           // Otherwise fall back to the normal create-intent call.
-          createOrder: isSubscription ? void 0 : existingOrderId ? () => Promise.resolve(existingOrderId) : () => createPaypalIntent("Failed to create PayPal order."),
-          createSubscription: isSubscription ? existingOrderId ? () => Promise.resolve(existingOrderId) : () => createPaypalIntent("Failed to create PayPal subscription.") : void 0,
+          createOrder: isSubscription ? void 0 : existingOrderId ? () => Promise.resolve(registerApprovalContext(existingOrderId)) : () => createPaypalIntent("Failed to create PayPal order.").then(registerApprovalContext),
+          createSubscription: isSubscription ? existingOrderId ? () => Promise.resolve(registerApprovalContext(existingOrderId)) : () => createPaypalIntent("Failed to create PayPal subscription.").then(registerApprovalContext) : void 0,
           onApprove: handleApprove,
           onCancel: () => {
+            const context = attemptContextBySurfaceRef.current.get(effectRenderGeneration) ?? beforeClickRef.current;
+            if (context) attemptContextBySurfaceRef.current.delete(context.surfaceKey);
             beforeClickRef.current = null;
-            onDeclineRef.current?.(buildDeclineEvent("paypal", "PayPal checkout was cancelled."));
+            finishOverlay();
+            telemetrySource.terminal({
+              outcome: "payment_cancelled",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+            pendingProviderFocusRef.current = true;
+            invalidateAttempt({ generation: context?.generation, remount: true, focus: false });
           },
           onError: (err) => {
+            if (cancelled || activeRenderGenerationRef.current !== effectRenderGeneration) return;
             const message = err instanceof Error ? err.message : "PayPal failed to render.";
             appendDebug(`onError rendered=${rendered} msg=${message.slice(0, 120)}`);
             if (rendered) {
-              forwardError(message);
-              onDeclineRef.current?.(buildDeclineEvent("paypal", message));
+              const context = attemptContextBySurfaceRef.current.get(effectRenderGeneration) ?? beforeClickRef.current;
+              if (context && !isAttemptActive(context.generation)) return;
+              if (!context && invalidatedAttemptGenerationRef.current === attemptGenerationRef.current) return;
+              if (isZoidLifecycleMessage(message)) {
+                finishAttempt(context?.generation);
+                return;
+              }
+              finishOverlay();
+              const lower = message.toLowerCase();
+              telemetrySource.error({
+                errorCode: lower.includes("popup") && lower.includes("block") ? "POPUP_BLOCKED" : "PROVIDER_RUNTIME_FAILED",
+                stage: "provider_ready",
+                provider: "paypal",
+                paymentMethodCategory: "paypal",
+                requestCategory: "provider_sdk"
+              });
+              if (context) attemptContextBySurfaceRef.current.delete(context.surfaceKey);
+              beforeClickRef.current = null;
+              invalidateAttempt({ generation: context?.generation, remount: true, showRetry: true, focus: true });
+              notifyTechnicalFailure(err, { code: "paypal_runtime_failed" });
               return;
             }
             markRenderFailed(message);
@@ -1199,6 +1732,12 @@ function DirectPayPalButton({
         });
         const eligible = buttons.isEligible();
         appendDebug(`isEligible=${eligible}`);
+        telemetrySource.log({
+          name: "provider.eligibility.checked",
+          stage: "provider_ready",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
         if (!eligible) {
           setReady(false);
           markRenderFailed(
@@ -1270,6 +1809,19 @@ function DirectPayPalButton({
           activeButtons = typedButtons;
           rendered = true;
           setReady(true);
+          telemetrySource.log({
+            name: "provider.ready",
+            stage: "provider_ready",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
+          telemetrySource.performance({
+            stage: "provider_ready",
+            durationMs: telemetrySource.elapsed(providerStartedAt.current),
+            durationMode: "machine",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
         }).catch((err) => {
           const message = err instanceof Error ? err.message : "PayPal failed to render.";
           appendDebug(`render:rejected msg=${message.slice(0, 120)}`);
@@ -1291,7 +1843,7 @@ function DirectPayPalButton({
         });
       }
     };
-  }, [baseUrl, clientId, currency, environment, isSubscription, sessionId, existingOrderId]);
+  }, [baseUrl, clientId, currency, environment, isSubscription, sessionId, existingOrderId, renderGeneration, telemetrySource]);
   const debugPanel = debug ? /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)(
     "pre",
     {
@@ -1346,18 +1898,38 @@ ${debugLines.join("\n")}`
           {
             ref: containerRef,
             "data-testid": "flopay-direct-paypal-container",
+            tabIndex: -1,
+            "aria-label": "PayPal payment method",
             style: {
               minHeight: DEFAULT_BUTTON_HEIGHT,
               display: "flex",
               opacity: ready ? 1 : 0
             },
             "aria-busy": submitting || isProcessing
-          }
+          },
+          renderGeneration
         )
-      ] })
+      ] }),
+      showRetryFocusTarget && /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+        "button",
+        {
+          ref: focusTargetRef,
+          type: "button",
+          "data-testid": "flopay-direct-paypal-focus-target",
+          onClick: focusPayPalSurface,
+          style: DIRECT_PAYPAL_RECOVERY_ACTION_STYLE,
+          children: "Try PayPal again"
+        }
+      )
     ] })
   );
 }
+function DirectPayPalButton(props) {
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(DirectPayPalButtonImplementation, { ...props });
+}
+function InstrumentedDirectPayPalButton(props) {
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(DirectPayPalButtonImplementation, { ...props });
+}
 
 // src/split-card-form.tsx
 var import_shared6 = require("@flopay/shared");
@@ -1438,6 +2010,19 @@ var BUTTONS_PANEL_HIDDEN_STYLE = {
   height: 0,
   overflow: "hidden"
 };
+var EXTERNAL_METHOD_RECOVERY_BUTTON_STYLE = {
+  width: "100%",
+  minHeight: DEFAULT_BUTTONS_LAYOUT_BUTTON_HEIGHT,
+  margin: "0 0 0.5rem",
+  padding: "0.75rem 0.875rem",
+  border: "1px solid #2563eb",
+  borderRadius: 8,
+  background: "#eff6ff",
+  color: "#1d4ed8",
+  fontSize: "0.95rem",
+  fontWeight: 700,
+  cursor: "pointer"
+};
 function getButtonMethodLabel(method) {
   switch (method) {
     case "paypal":
@@ -1450,6 +2035,118 @@ function getButtonMethodLabel(method) {
       return "Card";
   }
 }
+function checkoutButtonMethodFromProviderMethod(method) {
+  if (method === "paypal") return "paypal";
+  if (method === "apple_pay") return "apple_pay";
+  return "google_pay";
+}
+function getExternalMethodDisplayName(method) {
+  return method === "paypal" ? "PayPal" : (0, import_shared5.getStripeMethodDisplayName)(method);
+}
+function buildExternalMethodRecoveryMessage(method, popupBlocked) {
+  const base = `We couldn't open ${getExternalMethodDisplayName(method)}. Try again or choose another payment method.`;
+  return popupBlocked ? `${base} Allow pop-ups for this site, then try again.` : base;
+}
+function useExternalAttemptReconciliation(onMissingTerminal) {
+  const generationRef = (0, import_react9.useRef)(0);
+  const invalidatedGenerationRef = (0, import_react9.useRef)(null);
+  const attemptRef = (0, import_react9.useRef)(null);
+  const clearAttemptTimer = (0, import_react9.useCallback)((targetAttempt = attemptRef.current) => {
+    const attempt = targetAttempt;
+    if (attempt?.timer) {
+      clearTimeout(attempt.timer);
+      attempt.timer = null;
+    }
+  }, []);
+  const armAttemptTimer = (0, import_react9.useCallback)((attempt, delayMs) => {
+    if (typeof document !== "undefined" && document.visibilityState !== "visible") return;
+    clearAttemptTimer(attempt);
+    attempt.timer = setTimeout(() => {
+      attempt.timer = null;
+      if (attemptRef.current?.generation !== attempt.generation) return;
+      attemptRef.current = null;
+      invalidatedGenerationRef.current = attempt.generation;
+      onMissingTerminal(
+        attempt.method,
+        new Error("External payment method returned without a terminal callback."),
+        { code: "external_method_missing_terminal_callback" }
+      );
+    }, delayMs);
+  }, [clearAttemptTimer, onMissingTerminal]);
+  const armRecoveryTimer = (0, import_react9.useCallback)((attempt) => {
+    if (!attempt.yieldedControl) return;
+    armAttemptTimer(attempt, EXTERNAL_METHOD_CALLBACK_GRACE_MS);
+  }, [armAttemptTimer]);
+  const startAttempt = (0, import_react9.useCallback)((method) => {
+    clearAttemptTimer();
+    const generation = generationRef.current + 1;
+    generationRef.current = generation;
+    invalidatedGenerationRef.current = null;
+    const attempt = { generation, method, timer: null, yieldedControl: false };
+    attemptRef.current = attempt;
+    return generation;
+  }, [clearAttemptTimer]);
+  const finishAttempt = (0, import_react9.useCallback)((generation) => {
+    const attempt = attemptRef.current;
+    if (typeof generation === "number" && attempt?.generation !== generation) return false;
+    clearAttemptTimer(attempt);
+    attemptRef.current = null;
+    if (typeof generation !== "number" || invalidatedGenerationRef.current === generation) {
+      invalidatedGenerationRef.current = null;
+    }
+    return true;
+  }, [clearAttemptTimer]);
+  const invalidateAttempt = (0, import_react9.useCallback)((generation) => {
+    const attempt = attemptRef.current;
+    const targetGeneration = generation ?? attempt?.generation ?? generationRef.current;
+    if (!generation || attempt?.generation === generation) {
+      clearAttemptTimer(attempt);
+      attemptRef.current = null;
+    }
+    invalidatedGenerationRef.current = targetGeneration;
+  }, [clearAttemptTimer]);
+  const isAttemptInvalidated = (0, import_react9.useCallback)(
+    (generation) => invalidatedGenerationRef.current === (generation ?? generationRef.current),
+    []
+  );
+  const isAttemptCurrent = (0, import_react9.useCallback)(
+    (generation) => attemptRef.current?.generation === generation && invalidatedGenerationRef.current !== generation,
+    []
+  );
+  const scheduleRecoveryIfReturned = (0, import_react9.useCallback)(() => {
+    const attempt = attemptRef.current;
+    if (!attempt) return;
+    armRecoveryTimer(attempt);
+  }, [armRecoveryTimer]);
+  const markAttemptYieldedControl = (0, import_react9.useCallback)(() => {
+    const attempt = attemptRef.current;
+    if (!attempt) return;
+    attempt.yieldedControl = true;
+    clearAttemptTimer(attempt);
+  }, [clearAttemptTimer]);
+  (0, import_react9.useEffect)(() => {
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "visible") {
+        scheduleRecoveryIfReturned();
+      } else {
+        markAttemptYieldedControl();
+      }
+    };
+    const handleBlur = () => {
+      markAttemptYieldedControl();
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    window.addEventListener("blur", handleBlur);
+    window.addEventListener("focus", scheduleRecoveryIfReturned);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("blur", handleBlur);
+      window.removeEventListener("focus", scheduleRecoveryIfReturned);
+      clearAttemptTimer();
+    };
+  }, [clearAttemptTimer, markAttemptYieldedControl, scheduleRecoveryIfReturned]);
+  return { startAttempt, finishAttempt, invalidateAttempt, isAttemptInvalidated, isAttemptCurrent };
+}
 function malformedPostcodeMessage(country) {
   const example = (0, import_shared5.getPostalCodeExample)(country);
   return `Enter a valid ${(0, import_shared5.getPostalCodeLabel)(country)}${example ? ` (e.g. ${example})` : ""}`;
@@ -1544,10 +2241,12 @@ function PayPalButtonInner({
   isProcessing = false,
   onButtonClick,
   onDecline,
+  onTechnicalFailure,
   runBeforeButtonClick,
   onLoadStateChange,
   placeholderBorderRadius
 }) {
+  const flopay = useFloPay();
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
   const [loadState, setLoadState] = (0, import_react9.useState)("loading");
@@ -1556,8 +2255,55 @@ function PayPalButtonInner({
   }, [loadState, onLoadStateChange]);
   const [submitting, setSubmitting] = (0, import_react9.useState)(false);
   const paypalResumeAttempted = (0, import_react9.useRef)(false);
-  const beforeClickRef = (0, import_react9.useRef)(null);
+  const focusTargetRef = (0, import_react9.useRef)(null);
+  const recoveryActionRef = (0, import_react9.useRef)(null);
+  const [surfaceKey, setSurfaceKey] = (0, import_react9.useState)(0);
+  const [showRecoveryAction, setShowRecoveryAction] = (0, import_react9.useState)(false);
+  const pendingProviderFocusRef = (0, import_react9.useRef)(false);
+  const attemptContextBySurfaceRef = (0, import_react9.useRef)(/* @__PURE__ */ new Map());
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
+  const {
+    startAttempt,
+    finishAttempt,
+    invalidateAttempt,
+    isAttemptInvalidated,
+    isAttemptCurrent
+  } = useExternalAttemptReconciliation((method, err, options) => {
+    onTechnicalFailure?.(method, err, {
+      ...options,
+      popupBlocked: options?.popupBlocked ?? isPopupBlockedError(err)
+    });
+    setShowRecoveryAction(true);
+    setSurfaceKey((key) => key + 1);
+  });
+  (0, import_react9.useEffect)(() => {
+    if (showRecoveryAction) recoveryActionRef.current?.focus();
+  }, [showRecoveryAction, surfaceKey]);
+  const resetSurface = (0, import_react9.useCallback)(() => {
+    setSurfaceKey((key) => key + 1);
+  }, []);
+  const recoverTechnicalFailure = (0, import_react9.useCallback)((err, code, generation) => {
+    invalidateAttempt(generation);
+    onTechnicalFailure?.("paypal", err, { code, popupBlocked: isPopupBlockedError(err) });
+    setShowRecoveryAction(true);
+    resetSurface();
+  }, [invalidateAttempt, onTechnicalFailure, resetSurface]);
+  const focusProviderSurface = (0, import_react9.useCallback)(() => {
+    window.setTimeout(() => {
+      const target = focusTargetRef.current?.querySelector("iframe");
+      (target ?? focusTargetRef.current)?.focus();
+    }, 0);
+  }, []);
+  (0, import_react9.useEffect)(() => {
+    if (!pendingProviderFocusRef.current) return;
+    pendingProviderFocusRef.current = false;
+    focusProviderSurface();
+  }, [focusProviderSurface, surfaceKey]);
+  const handleRecoveryActionClick = (0, import_react9.useCallback)(() => {
+    setShowRecoveryAction(false);
+    onErrorChange?.(null);
+    focusProviderSurface();
+  }, [focusProviderSurface, onErrorChange]);
   (0, import_react9.useEffect)(() => {
     if (!stripe || paypalResumeAttempted.current) return;
     const params = new URLSearchParams(window.location.search);
@@ -1631,22 +2377,33 @@ function PayPalButtonInner({
     }
     const beforeClick = runBeforeButtonClick ? await runBeforeButtonClick("paypal") : { proceed: true };
     if (!beforeClick.proceed) {
-      beforeClickRef.current = null;
+      attemptContextBySurfaceRef.current.delete(surfaceKey);
       event.reject();
       return;
     }
-    beforeClickRef.current = {
+    const generation = startAttempt("paypal");
+    attemptContextBySurfaceRef.current.set(surfaceKey, {
+      generation,
       accountPatch: beforeClick.accountPatch,
       sessionId: beforeClick.sessionId,
       nonce: beforeClick.nonce
-    };
+    });
+    setShowRecoveryAction(false);
     onButtonClick?.("paypal");
     event.resolve();
-  }, [isProcessing, onButtonClick, runBeforeButtonClick, submitting]);
+  }, [attemptContextBySurfaceRef, isProcessing, onButtonClick, runBeforeButtonClick, startAttempt, submitting, surfaceKey]);
   const handlePayPalConfirm = (0, import_react9.useCallback)(async (event) => {
     if (!stripe || !elements) return;
-    let prepared = beforeClickRef.current;
-    beforeClickRef.current = null;
+    const attemptContext = attemptContextBySurfaceRef.current.get(surfaceKey);
+    if (attemptContext && !isAttemptCurrent(attemptContext.generation)) {
+      attemptContextBySurfaceRef.current.delete(surfaceKey);
+      return;
+    }
+    if (!attemptContext && isAttemptInvalidated()) return;
+    if (attemptContext && !finishAttempt(attemptContext.generation)) return;
+    if (!attemptContext) finishAttempt();
+    let prepared = attemptContext ?? null;
+    attemptContextBySurfaceRef.current.delete(surfaceKey);
     if (!prepared && runBeforeButtonClick) {
       const beforeClick = await runBeforeButtonClick("paypal");
       if (!beforeClick.proceed) {
@@ -1671,9 +2428,8 @@ function PayPalButtonInner({
       const createPM = stripe.createPaymentMethod;
       const { error: pmError, paymentMethod } = await createPM({ type: "paypal" });
       if (pmError) {
-        const message = pmError.message ?? "PayPal payment failed.";
-        onErrorChange?.(message);
-        event.paymentFailed({ reason: "fail", message });
+        recoverTechnicalFailure(pmError, "stripe_paypal_create_payment_method_failed", attemptContext?.generation);
+        event.paymentFailed({ reason: "fail" });
         return;
       }
       const intentHeaders = { "Content-Type": "application/json" };
@@ -1732,11 +2488,16 @@ function PayPalButtonInner({
           } catch {
           }
         }
-        const message = confirmError.message ?? "PayPal payment failed.";
-        onErrorChange?.(message);
-        onDecline?.(buildDeclineEvent("paypal", message, {
-          code: confirmError.code
-        }));
+        if (isProviderDecline(confirmError)) {
+          const message = confirmError.message ?? "Your payment was declined.";
+          onErrorChange?.(message);
+          onDecline?.(buildDeclineEvent("paypal", message, {
+            code: getProviderErrorCode(confirmError),
+            declineCode: getProviderDeclineCode(confirmError)
+          }));
+        } else {
+          recoverTechnicalFailure(confirmError, "stripe_paypal_confirm_failed", attemptContext?.generation);
+        }
         return;
       }
       if (typeof window !== "undefined") {
@@ -1758,11 +2519,11 @@ function PayPalButtonInner({
       });
       return;
     } catch (err) {
-      onErrorChange?.(err instanceof Error ? err.message : "PayPal payment failed. Please try again.");
+      recoverTechnicalFailure(err, "stripe_paypal_failed", attemptContext?.generation);
     } finally {
       setSubmitting(false);
     }
-  }, [stripe, elements, sessionId, nonce, email, baseUrl, onTokenizedBody, onErrorChange, onDecline, runBeforeButtonClick]);
+  }, [stripe, elements, sessionId, nonce, email, baseUrl, onTokenizedBody, onErrorChange, onDecline, runBeforeButtonClick, recoverTechnicalFailure, finishAttempt, isAttemptCurrent, isAttemptInvalidated, surfaceKey]);
   return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(import_jsx_runtime7.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
       ExpressCheckoutReadySwap,
@@ -1770,29 +2531,62 @@ function PayPalButtonInner({
         state: loadState,
         placeholderTestId: "flopay-paypal-placeholder",
         borderRadius: placeholderBorderRadius,
-        children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
-          import_react_stripe_js.ExpressCheckoutElement,
+        children: /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(
+          "div",
           {
-            onReady: (event) => setLoadState(resolveExpressCheckoutLoadState(event, ["paypal"])),
-            onLoadError: () => setLoadState("load_error"),
-            onClick: handlePayPalClick,
-            onConfirm: handlePayPalConfirm,
-            onCancel: () => {
-              beforeClickRef.current = null;
-              onDecline?.(buildDeclineEvent("paypal", "PayPal checkout was cancelled."));
-            },
-            options: {
-              buttonType: { paypal: "paypal" },
-              billingAddressRequired: false,
-              phoneNumberRequired: false,
-              shippingAddressRequired: false,
-              paymentMethods: {
-                applePay: "never",
-                googlePay: "never",
-                paypal: "auto",
-                link: "never"
-              }
-            }
+            ref: focusTargetRef,
+            tabIndex: -1,
+            "data-testid": "flopay-paypal-focus-target",
+            "aria-label": "PayPal payment method",
+            style: { borderRadius: 8, outlineOffset: 4 },
+            children: [
+              showRecoveryAction && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+                "button",
+                {
+                  ref: recoveryActionRef,
+                  type: "button",
+                  "data-testid": "flopay-paypal-retry-button",
+                  onClick: handleRecoveryActionClick,
+                  style: EXTERNAL_METHOD_RECOVERY_BUTTON_STYLE,
+                  children: "Try PayPal again"
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+                import_react_stripe_js.ExpressCheckoutElement,
+                {
+                  onReady: (event) => setLoadState(resolveExpressCheckoutLoadState(event, ["paypal"])),
+                  onLoadError: () => setLoadState("load_error"),
+                  onClick: handlePayPalClick,
+                  onConfirm: handlePayPalConfirm,
+                  onCancel: () => {
+                    const attemptContext = attemptContextBySurfaceRef.current.get(surfaceKey);
+                    attemptContextBySurfaceRef.current.delete(surfaceKey);
+                    getFloPayTelemetryBridge(flopay)?.terminal({
+                      outcome: "payment_cancelled",
+                      provider: "paypal",
+                      paymentMethodCategory: "paypal"
+                    });
+                    invalidateAttempt(attemptContext?.generation);
+                    setShowRecoveryAction(false);
+                    pendingProviderFocusRef.current = true;
+                    resetSurface();
+                  },
+                  options: {
+                    buttonType: { paypal: "paypal" },
+                    billingAddressRequired: false,
+                    phoneNumberRequired: false,
+                    shippingAddressRequired: false,
+                    paymentMethods: {
+                      applePay: "never",
+                      googlePay: "never",
+                      paypal: "auto",
+                      link: "never"
+                    }
+                  }
+                },
+                surfaceKey
+              )
+            ]
           }
         )
       }
@@ -1810,10 +2604,12 @@ function WalletButtonInner({
   onErrorChange,
   onButtonClick,
   onDecline,
+  onTechnicalFailure,
   runBeforeButtonClick,
   onLoadStateChange,
   placeholderBorderRadius
 }) {
+  const flopay = useFloPay();
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
   const [loadState, setLoadState] = (0, import_react9.useState)("loading");
@@ -1822,15 +2618,74 @@ function WalletButtonInner({
   }, [loadState, onLoadStateChange]);
   const [submitting, setSubmitting] = (0, import_react9.useState)(false);
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
-  const lastWalletMethodRef = (0, import_react9.useRef)("card");
-  const beforeClickRef = (0, import_react9.useRef)(null);
+  const focusTargetRef = (0, import_react9.useRef)(null);
+  const recoveryActionRef = (0, import_react9.useRef)(null);
+  const [surfaceKey, setSurfaceKey] = (0, import_react9.useState)(0);
+  const [showRecoveryAction, setShowRecoveryAction] = (0, import_react9.useState)(false);
+  const [recoveryActionMethod, setRecoveryActionMethod] = (0, import_react9.useState)("google_pay");
+  const pendingProviderFocusRef = (0, import_react9.useRef)(false);
+  const lastWalletProviderMethodRef = (0, import_react9.useRef)("google_pay");
+  const lastWalletMethodRef = (0, import_react9.useRef)("google_pay");
+  const attemptContextBySurfaceRef = (0, import_react9.useRef)(/* @__PURE__ */ new Map());
+  const {
+    startAttempt,
+    finishAttempt,
+    invalidateAttempt,
+    isAttemptInvalidated,
+    isAttemptCurrent
+  } = useExternalAttemptReconciliation((method, err, options) => {
+    onTechnicalFailure?.(method, err, {
+      ...options,
+      popupBlocked: options?.popupBlocked ?? isPopupBlockedError(err)
+    });
+    setRecoveryActionMethod(method);
+    setShowRecoveryAction(true);
+    setSurfaceKey((key) => key + 1);
+  });
+  (0, import_react9.useEffect)(() => {
+    if (showRecoveryAction) recoveryActionRef.current?.focus();
+  }, [showRecoveryAction, surfaceKey]);
+  const resetSurface = (0, import_react9.useCallback)(() => {
+    setSurfaceKey((key) => key + 1);
+  }, []);
+  const recoverTechnicalFailure = (0, import_react9.useCallback)((method, err, code, generation) => {
+    invalidateAttempt(generation);
+    onTechnicalFailure?.(method, err, { code, popupBlocked: isPopupBlockedError(err) });
+    setRecoveryActionMethod(method);
+    setShowRecoveryAction(true);
+    resetSurface();
+  }, [invalidateAttempt, onTechnicalFailure, resetSurface]);
+  const focusProviderSurface = (0, import_react9.useCallback)(() => {
+    window.setTimeout(() => {
+      const target = focusTargetRef.current?.querySelector("iframe");
+      (target ?? focusTargetRef.current)?.focus();
+    }, 0);
+  }, []);
+  (0, import_react9.useEffect)(() => {
+    if (!pendingProviderFocusRef.current) return;
+    pendingProviderFocusRef.current = false;
+    focusProviderSurface();
+  }, [focusProviderSurface, surfaceKey]);
+  const handleRecoveryActionClick = (0, import_react9.useCallback)(() => {
+    setShowRecoveryAction(false);
+    onErrorChange?.(null);
+    focusProviderSurface();
+  }, [focusProviderSurface, onErrorChange]);
   const handleWalletConfirm = (0, import_react9.useCallback)(
     async (event) => {
       if (!stripe || !elements) return;
-      const walletType = event.expressPaymentType;
-      let prepared = beforeClickRef.current;
-      beforeClickRef.current = null;
-      const buttonMethod = walletType === "apple_pay" ? "apple_pay" : "google_pay";
+      const attemptContext = attemptContextBySurfaceRef.current.get(surfaceKey);
+      if (attemptContext && !isAttemptCurrent(attemptContext.generation)) {
+        attemptContextBySurfaceRef.current.delete(surfaceKey);
+        return;
+      }
+      if (!attemptContext && isAttemptInvalidated()) return;
+      if (attemptContext && !finishAttempt(attemptContext.generation)) return;
+      if (!attemptContext) finishAttempt();
+      const walletType = event.expressPaymentType ?? attemptContext?.method ?? lastWalletProviderMethodRef.current;
+      let prepared = attemptContext ?? null;
+      attemptContextBySurfaceRef.current.delete(surfaceKey);
+      const buttonMethod = checkoutButtonMethodFromProviderMethod(walletType);
       if (!prepared && runBeforeButtonClick) {
         const beforeClick = await runBeforeButtonClick(buttonMethod);
         if (!beforeClick.proceed) {
@@ -1852,12 +2707,12 @@ function WalletButtonInner({
         onErrorChange?.(null);
         const { error: submitError } = await elements.submit();
         if (submitError) {
-          onErrorChange?.(submitError.message ?? "Wallet payment failed.");
+          recoverTechnicalFailure(walletType, submitError, "stripe_wallet_submit_failed", attemptContext?.generation);
           return;
         }
         const { error: pmError, paymentMethod } = await stripe.createPaymentMethod({ elements });
         if (pmError || !paymentMethod) {
-          onErrorChange?.(pmError?.message ?? "Failed to create payment method.");
+          recoverTechnicalFailure(walletType, pmError ?? new Error("Failed to create payment method."), "stripe_wallet_create_payment_method_failed", attemptContext?.generation);
           return;
         }
         if (!effectiveSessionId || !effectiveEmail) {
@@ -1890,11 +2745,16 @@ function WalletButtonInner({
         if (!intentClientSecret) throw new Error("No client_secret in payment intent response");
         const { error: confirmError, intentId } = (0, import_shared6.isSetupIntentClientSecret)(intentClientSecret) ? await stripe.confirmCardSetup(intentClientSecret, { payment_method: paymentMethod.id }).then((r) => ({ error: r.error, intentId: r.setupIntent?.id })) : await stripe.confirmCardPayment(intentClientSecret, { payment_method: paymentMethod.id }).then((r) => ({ error: r.error, intentId: r.paymentIntent?.id }));
         if (confirmError) {
-          const message = confirmError.message ?? "Wallet payment failed.";
-          onErrorChange?.(message);
-          onDecline?.(buildDeclineEvent(method, message, {
-            code: confirmError.code
-          }));
+          if (isProviderDecline(confirmError)) {
+            const message = confirmError.message ?? "Your payment was declined.";
+            onErrorChange?.(message);
+            onDecline?.(buildDeclineEvent(method, message, {
+              code: getProviderErrorCode(confirmError),
+              declineCode: getProviderDeclineCode(confirmError)
+            }));
+          } else {
+            recoverTechnicalFailure(walletType, confirmError, "stripe_wallet_confirm_failed", attemptContext?.generation);
+          }
           return;
         }
         onTokenizedBody({
@@ -1907,12 +2767,12 @@ function WalletButtonInner({
           nonce: effectiveNonce
         });
       } catch (err) {
-        onErrorChange?.(err instanceof Error ? err.message : "Wallet payment failed. Please try again.");
+        recoverTechnicalFailure(walletType, err, "stripe_wallet_failed", attemptContext?.generation);
       } finally {
         setSubmitting(false);
       }
     },
-    [stripe, elements, sessionId, nonce, email, baseUrl, onTokenizedBody, onErrorChange, onDecline, runBeforeButtonClick]
+    [stripe, elements, sessionId, nonce, email, baseUrl, onTokenizedBody, onErrorChange, onDecline, runBeforeButtonClick, recoverTechnicalFailure, finishAttempt, isAttemptCurrent, isAttemptInvalidated, surfaceKey]
   );
   const expressMethodMap = (0, import_react9.useMemo)(() => {
     const allKeys = ["applePay", "googlePay", "paypal", "link", "amazonPay", "klarna"];
@@ -1939,41 +2799,90 @@ function WalletButtonInner({
         state: loadState,
         placeholderTestId: "flopay-wallet-placeholder",
         borderRadius: placeholderBorderRadius,
-        children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
-          import_react_stripe_js.ExpressCheckoutElement,
+        children: /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(
+          "div",
           {
-            onReady: (event) => {
-              setLoadState(resolveExpressCheckoutLoadState(event, availableMethodKeys));
-            },
-            onLoadError: (_event) => {
-              setLoadState("load_error");
-            },
-            onClick: async (event) => {
-              lastWalletMethodRef.current = event.expressPaymentType === "apple_pay" ? "apple_pay" : "google_pay";
-              const beforeClick = runBeforeButtonClick ? await runBeforeButtonClick(lastWalletMethodRef.current) : { proceed: true };
-              if (!beforeClick.proceed) {
-                beforeClickRef.current = null;
-                event.reject();
-                return;
-              }
-              beforeClickRef.current = {
-                accountPatch: beforeClick.accountPatch,
-                sessionId: beforeClick.sessionId,
-                nonce: beforeClick.nonce
-              };
-              onButtonClick?.(lastWalletMethodRef.current);
-              event.resolve();
-            },
-            onConfirm: handleWalletConfirm,
-            onCancel: () => {
-              beforeClickRef.current = null;
-              onDecline?.(buildDeclineEvent(lastWalletMethodRef.current, "Wallet checkout was cancelled."));
-            },
-            options: {
-              buttonType: { applePay: "plain", googlePay: "plain" },
-              paymentMethods: expressMethodMap,
-              layout: { maxColumns: 1, overflow: "never" }
-            }
+            ref: focusTargetRef,
+            tabIndex: -1,
+            "data-testid": "flopay-wallet-focus-target",
+            "aria-label": "Wallet payment methods",
+            style: { borderRadius: 8, outlineOffset: 4 },
+            children: [
+              showRecoveryAction && /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(
+                "button",
+                {
+                  ref: recoveryActionRef,
+                  type: "button",
+                  "data-testid": "flopay-wallet-retry-button",
+                  onClick: handleRecoveryActionClick,
+                  style: EXTERNAL_METHOD_RECOVERY_BUTTON_STYLE,
+                  children: [
+                    "Try ",
+                    getExternalMethodDisplayName(recoveryActionMethod),
+                    " again"
+                  ]
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+                import_react_stripe_js.ExpressCheckoutElement,
+                {
+                  onReady: (event) => {
+                    setLoadState(resolveExpressCheckoutLoadState(event, availableMethodKeys));
+                  },
+                  onLoadError: (_event) => {
+                    setLoadState("load_error");
+                    getFloPayTelemetryBridge(flopay)?.error({
+                      errorCode: "PROVIDER_LOAD_FAILED",
+                      stage: "provider_load",
+                      provider: "stripe",
+                      paymentMethodCategory: "wallet",
+                      requestCategory: "provider_sdk"
+                    });
+                  },
+                  onClick: async (event) => {
+                    lastWalletProviderMethodRef.current = event.expressPaymentType;
+                    lastWalletMethodRef.current = checkoutButtonMethodFromProviderMethod(event.expressPaymentType);
+                    const beforeClick = runBeforeButtonClick ? await runBeforeButtonClick(lastWalletMethodRef.current) : { proceed: true };
+                    if (!beforeClick.proceed) {
+                      attemptContextBySurfaceRef.current.delete(surfaceKey);
+                      event.reject();
+                      return;
+                    }
+                    const generation = startAttempt(event.expressPaymentType);
+                    attemptContextBySurfaceRef.current.set(surfaceKey, {
+                      generation,
+                      method: event.expressPaymentType,
+                      accountPatch: beforeClick.accountPatch,
+                      sessionId: beforeClick.sessionId,
+                      nonce: beforeClick.nonce
+                    });
+                    setShowRecoveryAction(false);
+                    onButtonClick?.(lastWalletMethodRef.current);
+                    event.resolve();
+                  },
+                  onConfirm: handleWalletConfirm,
+                  onCancel: () => {
+                    const attemptContext = attemptContextBySurfaceRef.current.get(surfaceKey);
+                    attemptContextBySurfaceRef.current.delete(surfaceKey);
+                    getFloPayTelemetryBridge(flopay)?.terminal({
+                      outcome: "payment_cancelled",
+                      provider: "stripe",
+                      paymentMethodCategory: "wallet"
+                    });
+                    invalidateAttempt(attemptContext?.generation);
+                    setShowRecoveryAction(false);
+                    pendingProviderFocusRef.current = true;
+                    resetSurface();
+                  },
+                  options: {
+                    buttonType: { applePay: "plain", googlePay: "plain" },
+                    paymentMethods: expressMethodMap,
+                    layout: { maxColumns: 1, overflow: "never" }
+                  }
+                },
+                surfaceKey
+              )
+            ]
           }
         )
       }
@@ -2130,6 +3039,7 @@ function StripeMethodInlineForm({
   submitButtonStyle,
   errorText
 }) {
+  const flopay = useFloPay();
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
   const [submitting, setSubmitting] = (0, import_react9.useState)(false);
@@ -2282,7 +3192,16 @@ function StripeMethodInlineForm({
       import_react_stripe_js.PaymentElement,
       {
         onReady: () => setLoadState("ready"),
-        onLoadError: () => setLoadState("load_error"),
+        onLoadError: () => {
+          setLoadState("load_error");
+          getFloPayTelemetryBridge(flopay)?.error({
+            errorCode: "PROVIDER_LOAD_FAILED",
+            stage: "provider_load",
+            provider: "stripe",
+            paymentMethodCategory: "apm",
+            requestCategory: "provider_sdk"
+          });
+        },
         onChange: (event) => {
           const evRecord = event;
           setIsMethodComplete(!!evRecord.complete);
@@ -2884,6 +3803,30 @@ function SplitCardFormInner({
     },
     [onDecline]
   );
+  const recoverExternalMethodTechnicalFailure = (0, import_react9.useCallback)(
+    (method, err, options) => {
+      const popupBlocked = options?.popupBlocked ?? isPopupBlockedError(err);
+      const message = buildExternalMethodRecoveryMessage(method, popupBlocked);
+      const providerCode = sanitizeExternalFailureCode(options?.code) ?? getProviderErrorCode(err) ?? "external_payment_method_failed";
+      const floPayError = new import_shared6.FloPayError(message, "api_error", {
+        code: "external_payment_method_failed",
+        param: method
+      });
+      setOverlayStatus(null);
+      if (layout === "buttons") {
+        setViewState("buttons");
+        setExpandedApmMethod(null);
+      }
+      updateError(message);
+      onError?.(floPayError);
+      console.error("[FloPay] External payment method failed:", {
+        method,
+        code: providerCode,
+        popupBlocked
+      });
+    },
+    [layout, onError, updateError]
+  );
   (0, import_react9.useEffect)(() => {
     if (!vaultActive || !sessionId) {
       setVaultMount(null);
@@ -4340,6 +5283,7 @@ function SplitCardFormInner({
                     onComplete,
                     onErrorChange: updateError,
                     onDecline,
+                    onTechnicalFailure: recoverExternalMethodTechnicalFailure,
                     onButtonClick,
                     runBeforeButtonClick,
                     isProcessing: isSubmitting,
@@ -4363,6 +5307,7 @@ function SplitCardFormInner({
                   isProcessing: isSubmitting,
                   onButtonClick,
                   onDecline,
+                  onTechnicalFailure: recoverExternalMethodTechnicalFailure,
                   runBeforeButtonClick,
                   onLoadStateChange: setPaypalLoadState,
                   placeholderBorderRadius: buttonBorderRadius
@@ -4380,6 +5325,7 @@ function SplitCardFormInner({
                   onErrorChange: updateError,
                   onButtonClick,
                   onDecline,
+                  onTechnicalFailure: recoverExternalMethodTechnicalFailure,
                   runBeforeButtonClick,
                   onLoadStateChange: setWalletLoadState,
                   placeholderBorderRadius: buttonBorderRadius
@@ -4735,6 +5681,7 @@ function SplitCardFormInner({
             onComplete,
             onErrorChange: updateError,
             onDecline,
+            onTechnicalFailure: recoverExternalMethodTechnicalFailure,
             onButtonClick,
             runBeforeButtonClick,
             isProcessing: isSubmitting,
@@ -4758,6 +5705,7 @@ function SplitCardFormInner({
           isProcessing: isSubmitting,
           onButtonClick,
           onDecline,
+          onTechnicalFailure: recoverExternalMethodTechnicalFailure,
           runBeforeButtonClick,
           onLoadStateChange: setPaypalLoadState,
           placeholderBorderRadius: buttonBorderRadius
@@ -4775,6 +5723,7 @@ function SplitCardFormInner({
           onErrorChange: updateError,
           onButtonClick,
           onDecline,
+          onTechnicalFailure: recoverExternalMethodTechnicalFailure,
           runBeforeButtonClick,
           onLoadStateChange: setWalletLoadState,
           placeholderBorderRadius: buttonBorderRadius
@@ -5168,7 +6117,7 @@ async function recover3DSRedirectResult({
     return null;
   }
   try {
-    const api = new import_js3.PaymentAPI(billingApiUrl);
+    const api = new import_js3.PaymentAPI(billingApiUrl, { telemetry: false });
     const unified = await api.getUnifiedCheckoutSession(sessionId, nonce);
     const refreshedToken = unified.data.stripe?.clientSecret;
     if (isStripePaymentIntentClientSecret(refreshedToken)) {
@@ -5187,7 +6136,8 @@ async function processSavedPaymentForMode({
   session,
   nonce,
   tokenizedData,
-  returnUrl
+  returnUrl,
+  telemetry
 }) {
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
   const resolvedSessionId = sessionId ?? session.id;
@@ -5198,7 +6148,10 @@ async function processSavedPaymentForMode({
   const lastName = session.customer?.lastName ?? session.accountData?.lastName ?? "";
   const country = session.customer?.country ?? session.accountData?.country ?? void 0;
   const zip = session.customer?.zip ?? session.accountData?.zip ?? void 0;
-  const api = new import_js3.PaymentAPI(baseUrl);
+  const api = new import_js3.PaymentAPI(
+    baseUrl,
+    telemetry === false ? { telemetry: false } : void 0
+  );
   const response = await retryOnceOnFetchFailure(() => api.processPayment(customerId, {
     sessionId: resolvedSessionId,
     nonce: resolvedNonce,
@@ -5275,7 +6228,8 @@ async function handleSavedPaymentRedirectResult(redirectResult, {
   billingApiUrl,
   sessionId,
   session,
-  returnUrl
+  returnUrl,
+  telemetry
 }) {
   const stripe = flopay?.getRawProvider();
   if (!stripe) {
@@ -5358,6 +6312,7 @@ async function handleSavedPaymentRedirectResult(redirectResult, {
         billingApiUrl,
         sessionId,
         session,
+        telemetry,
         tokenizedData: {
           id: paymentIntent.id,
           type: "card",
@@ -5379,7 +6334,8 @@ async function handleSavedPaymentRedirectResult(redirectResult, {
         billingApiUrl,
         sessionId,
         session,
-        returnUrl
+        returnUrl,
+        telemetry
       });
     }
     throw Object.assign(
@@ -5485,7 +6441,8 @@ async function loadSavedPaymentProviders({
   publishableKey,
   paypalPublishableKey,
   billingApiUrl,
-  locale
+  locale,
+  telemetry
 }) {
   if (!publishableKey) {
     return { flopay: null, paypalFlopay: null };
@@ -5494,11 +6451,13 @@ async function loadSavedPaymentProviders({
   const [instance, paypalInstanceOrError] = await Promise.all([
     (0, import_js3.loadFloPay)(publishableKey, {
       billingApiUrl,
-      locale
+      locale,
+      telemetry
     }),
     needsSeparatePaypal ? (0, import_js3.loadFloPay)(paypalPublishableKey, {
       billingApiUrl,
-      locale
+      locale,
+      telemetry
     }).catch((err) => {
       console.warn("[FloPay] Failed to load PayPal Stripe instance:", err);
       return null;
@@ -5518,6 +6477,33 @@ var sessionInflightMap = /* @__PURE__ */ new Map();
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function createStandaloneTelemetryReporter(billingApiUrl, enabled, context) {
+  const reporter = createTelemetryBridge({
+    billingApiUrl,
+    sdkPackage: "@flopay/react",
+    sdkVersion: import_shared8.SDK_VERSION,
+    enabled: enabled !== false
+  });
+  reporter.beginCheckout(context);
+  return reporter;
+}
+function finishStandaloneTelemetry(reporter) {
+  void reporter.flush().catch(() => {
+  }).finally(() => reporter.destroy());
+}
+function reportStandaloneTelemetryError(billingApiUrl, enabled, context, errorCode, stage) {
+  const reporter = createStandaloneTelemetryReporter(billingApiUrl, enabled, context);
+  reporter.error({
+    errorCode,
+    stage,
+    paymentMethodCategory: "unknown",
+    ...stage === "session_read" ? { requestCategory: "session_read" } : {}
+  });
+  finishStandaloneTelemetry(reporter);
+}
+function isExpectedExistingSessionError(error) {
+  return error.type === "validation_error" || error.code === "checkout_session_not_found" || error.code === "checkout_session_expired" || error.code === "checkout_session_completed" || error.code === "session_auto_completed";
+}
 function resolveDirectPaypalConfig(unified) {
   const clientId = unified?.data.paypal?.publishableKey;
   if (!clientId) return void 0;
@@ -5622,6 +6608,7 @@ function FloPayCheckout({
   nonce: nonceProp,
   createSession: createSessionParams,
   billingApiUrl,
+  telemetry,
   appearance: appearanceOverride,
   locale,
   loading: loadingNode,
@@ -5687,12 +6674,22 @@ function FloPayCheckout({
   const autoCheckoutAttempted = (0, import_react10.useRef)(false);
   const paypalResumeAttempted = (0, import_react10.useRef)(false);
   const savedPaymentKeysRef = (0, import_react10.useRef)(null);
+  const telemetryCheckoutContext = (0, import_react10.useMemo)(() => ({
+    checkoutMode: checkoutModeProp ?? currentMode,
+    layout: children ? "unknown" : layout === "buttons" ? "buttons" : "embedded"
+  }), [checkoutModeProp, children, currentMode, layout]);
   const onCompleteRef = (0, import_react10.useRef)(onComplete);
   onCompleteRef.current = onComplete;
   const onErrorRef = (0, import_react10.useRef)(onError);
   onErrorRef.current = onError;
   const onDeclineRef = (0, import_react10.useRef)(onDecline);
   onDeclineRef.current = onDecline;
+  (0, import_react10.useEffect)(() => {
+    getFloPayTelemetryBridge(flopay)?.setCheckoutContext(telemetryCheckoutContext);
+    if (paypalFlopay && paypalFlopay !== flopay) {
+      getFloPayTelemetryBridge(paypalFlopay)?.setCheckoutContext(telemetryCheckoutContext);
+    }
+  }, [flopay, paypalFlopay, telemetryCheckoutContext]);
   const onSessionCompletedRef = (0, import_react10.useRef)(onSessionCompleted);
   onSessionCompletedRef.current = onSessionCompleted;
   (0, import_react10.useEffect)(() => {
@@ -5732,9 +6729,11 @@ function FloPayCheckout({
   }, [initialErrorMessage]);
   const emitDecline = (0, import_react10.useCallback)(
     (method, input, overrides) => {
-      onDeclineRef.current?.(buildDeclineEvent(method, input, overrides));
+      invokeMerchantCallback(() => {
+        onDeclineRef.current?.(buildDeclineEvent(method, input, overrides));
+      });
     },
-    []
+    [invokeMerchantCallback]
   );
   const runSavedPaymentFlow = (0, import_react10.useCallback)(
     async (sess, options) => {
@@ -5742,10 +6741,98 @@ function FloPayCheckout({
       setModeOverlayError(null);
       setModeOverlayStatus("processing");
       const activeSessionId2 = options?.sessionId ?? sess.id;
+      const activeFloPay = flopayRef.current ?? paypalFlopayRef.current;
+      const activeTelemetry = getFloPayTelemetryBridge(activeFloPay);
+      const standaloneTelemetry = activeFloPay ? null : createStandaloneTelemetryReporter(
+        resolvedBillingUrl,
+        telemetry,
+        telemetryCheckoutContext
+      );
+      const telemetrySource = {
+        log: (input) => {
+          if (activeTelemetry) activeTelemetry.log(input);
+          else standaloneTelemetry?.log(input);
+        },
+        error: (input) => {
+          if (activeTelemetry) activeTelemetry.error(input);
+          else standaloneTelemetry?.error(input);
+        },
+        terminal: (input) => {
+          if (activeTelemetry) activeTelemetry.terminal(input);
+          else standaloneTelemetry?.terminal(input);
+        },
+        performance: (input) => {
+          if (activeTelemetry) activeTelemetry.performance(input);
+          else standaloneTelemetry?.performance(input);
+        },
+        now: () => activeTelemetry?.now() ?? standaloneTelemetry?.now() ?? 0,
+        elapsed: (startedAt) => activeTelemetry?.elapsed(startedAt) ?? Math.max(0, (standaloneTelemetry?.now() ?? startedAt) - startedAt)
+      };
+      const processingStartedAt = telemetrySource.now();
+      let recoveryFlow = Boolean(
+        options?.initialAutoProcessingError || options?.initialAutoProcessingPending
+      );
+      let recoveryStarted = false;
+      let recoveryStartedAt;
+      const startRecovery = () => {
+        if (recoveryStarted) return;
+        recoveryStarted = true;
+        recoveryFlow = true;
+        recoveryStartedAt = telemetrySource.now();
+        telemetrySource.log({
+          name: "checkout.recovery.started",
+          stage: "recovery",
+          paymentMethodCategory: "saved"
+        });
+        telemetrySource.log({
+          name: "operation.recovery.started",
+          stage: "recovery",
+          paymentMethodCategory: "saved"
+        });
+      };
+      let processingFinished = false;
+      const finishProcessing = () => {
+        if (processingFinished) return;
+        processingFinished = true;
+        telemetrySource.log({
+          name: "payment.processing.completed",
+          stage: "processing",
+          paymentMethodCategory: "saved"
+        });
+        telemetrySource.performance({
+          stage: "processing",
+          durationMs: telemetrySource.elapsed(processingStartedAt),
+          durationMode: "machine",
+          paymentMethodCategory: "saved"
+        });
+        if (recoveryStartedAt !== void 0) {
+          telemetrySource.performance({
+            stage: "recovery",
+            durationMs: telemetrySource.elapsed(recoveryStartedAt),
+            durationMode: "machine",
+            paymentMethodCategory: "saved"
+          });
+        }
+      };
+      telemetrySource.log({
+        name: "payment.method.selected",
+        stage: "processing",
+        paymentMethodCategory: "saved"
+      });
+      telemetrySource.log({
+        name: "payment.processing.started",
+        stage: "processing",
+        paymentMethodCategory: "saved"
+      });
+      if (recoveryFlow) {
+        startRecovery();
+      }
+      let completionCallback;
       try {
         const redirectResult = getRedirectResultFromCheckoutProcessError(options?.initialAutoProcessingError);
         let paymentResult;
         if (redirectResult) {
+          startRecovery();
           if (redirectResult.type === "paypal_redirect_required" && savedPaymentKeysRef.current?.publishableKey) {
             persistPayPalResumeState({
               sessionId: activeSessionId2,
@@ -5759,13 +6846,14 @@ function FloPayCheckout({
             attempt3DS: options?.attempt3DS,
             billingApiUrl: resolvedBillingUrl,
             sessionId: activeSessionId2,
-            session: sess
+            session: sess,
+            telemetry: false
           });
           if (redirectResult.type === "paypal_redirect_required") {
             clearPayPalResumeState();
           }
         } else if (options?.initialAutoProcessingPending) {
-          const api = new import_js4.PaymentAPI(resolvedBillingUrl);
+          const api = new import_js4.PaymentAPI(resolvedBillingUrl, { telemetry: false });
           const completed = await api.waitForCheckoutSessionCompletion(options.initialAutoProcessingPending.sessionId, {
             initialDelayMs: options.initialAutoProcessingPending.retryAfterMs
           });
@@ -5793,11 +6881,13 @@ function FloPayCheckout({
           const result = await processSavedPaymentForMode({
             billingApiUrl: resolvedBillingUrl,
             sessionId: activeSessionId2,
-            session: sess
+            session: sess,
+            telemetry: false
           });
           if (result.type === "success") {
             paymentResult = result.result;
           } else {
+            startRecovery();
             if (result.type === "paypal_redirect_required" && savedPaymentKeysRef.current?.publishableKey) {
               persistPayPalResumeState({
                 sessionId: activeSessionId2,
@@ -5811,7 +6901,8 @@ function FloPayCheckout({
               attempt3DS: options?.attempt3DS,
               billingApiUrl: resolvedBillingUrl,
               sessionId: activeSessionId2,
-              session: sess
+              session: sess,
+              telemetry: false
             });
             if (result.type === "paypal_redirect_required") {
               clearPayPalResumeState();
@@ -5819,20 +6910,57 @@ function FloPayCheckout({
           }
         }
         if (activeSessionId2) markSessionRecentlyCompleted(activeSessionId2);
+        finishProcessing();
+        if (recoveryFlow) {
+          telemetrySource.log({
+            name: "checkout.recovery.completed",
+            stage: "recovery",
+            paymentMethodCategory: "saved"
+          });
+          telemetrySource.log({
+            name: "operation.recovery.completed",
+            stage: "recovery",
+            paymentMethodCategory: "saved"
+          });
+        }
+        telemetrySource.terminal({
+          outcome: "payment_succeeded",
+          paymentMethodCategory: "saved"
+        });
         setModeOverlayStatus("success");
         await sleep(PROCESSING_OVERLAY_SUCCESS_DELAY_MS);
-        onCompleteRef.current?.(paymentResult);
-        return true;
+        completionCallback = () => onCompleteRef.current?.(paymentResult);
       } catch (err) {
         const floPayErr = normalizeSavedPaymentError(err);
         const method = floPayErr.checkoutMethod ?? DEFAULT_SAVED_PAYMENT_DECLINE_METHOD;
         setModeError(floPayErr.message);
         setModeOverlayError(floPayErr.message);
         if (options?.fallbackToFull) {
+          telemetrySource.log({
+            name: "operation.fallback",
+            stage: "recovery",
+            paymentMethodCategory: "saved"
+          });
           setCurrentMode("full");
           replaceCheckoutModeQueryParam("full");
         }
-        onErrorRef.current?.(floPayErr);
+        finishProcessing();
+        const expectedDecline = Boolean(
+          floPayErr.declineCode || floPayErr.code?.toLowerCase().includes("declin")
+        );
+        if (expectedDecline) {
+          telemetrySource.terminal({
+            outcome: "payment_declined",
+            paymentMethodCategory: "saved"
+          });
+        } else {
+          telemetrySource.error({
+            errorCode: recoveryFlow ? "RECOVERY_FAILED" : "PAYMENT_PROCESSING_FAILED",
+            stage: recoveryFlow ? "recovery" : "processing",
+            paymentMethodCategory: "saved"
+          });
+        }
+        invokeMerchantCallback(() => onErrorRef.current?.(floPayErr));
         emitDecline(method, floPayErr, {
           code: floPayErr.code,
           declineCode: floPayErr.declineCode
@@ -5842,16 +6970,35 @@ function FloPayCheckout({
           sleep(PROCESSING_OVERLAY_ERROR_DELAY_MS),
           options?.ensureProvidersReady ? options.ensureProvidersReady() : Promise.resolve()
         ]);
+        if (recoveryFlow) {
+          telemetrySource.log({
+            name: "checkout.recovery.completed",
+            stage: "recovery",
+            paymentMethodCategory: "saved"
+          });
+          telemetrySource.log({
+            name: "operation.recovery.completed",
+            stage: "recovery",
+            paymentMethodCategory: "saved"
+          });
+        }
         return false;
       } finally {
+        finishProcessing();
+        if (standaloneTelemetry) finishStandaloneTelemetry(standaloneTelemetry);
         setModeOverlayStatus(null);
         setModeOverlayError(null);
       }
+      invokeMerchantCallback(completionCallback);
+      return true;
     },
     [
       emitDecline,
+      invokeMerchantCallback,
       normalizeSavedPaymentError,
-      resolvedBillingUrl
+      resolvedBillingUrl,
+      telemetry,
+      telemetryCheckoutContext
     ]
   );
   (0, import_react10.useEffect)(() => {
@@ -5869,6 +7016,8 @@ function FloPayCheckout({
     }
     paypalResumeAttempted.current = true;
     void (async () => {
+      let resumeTelemetry;
+      let redirectResumeStartedAt = 0;
       setModeError(null);
       setModeOverlayError(null);
       setModeOverlayStatus("processing");
@@ -5876,7 +7025,11 @@ function FloPayCheckout({
       try {
         if (params.get("redirect_status") === "failed") {
           throw Object.assign(
-            new import_shared8.FloPayError("PayPal payment was declined. Please try again.", "api_error"),
+            new import_shared8.FloPayError(
+              "PayPal payment was declined. Please try again.",
+              "api_error",
+              { declineCode: "paypal_redirect_failed" }
+            ),
             { checkoutMethod: "paypal" }
           );
         }
@@ -5887,7 +7040,22 @@ function FloPayCheckout({
           publishableKey: resumeState.publishableKey,
           paypalPublishableKey: resumeState.paypalPublishableKey,
           billingApiUrl: resolvedBillingUrl,
-          locale
+          locale,
+          telemetry
+        });
+        resumeTelemetry = getFloPayTelemetryBridge(resumePaypalFlopay ?? resumeFlopay);
+        redirectResumeStartedAt = resumeTelemetry?.now() ?? 0;
+        resumeTelemetry?.log({
+          name: "provider.redirect.resumed",
+          stage: "redirect_resume",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+        resumeTelemetry?.log({
+          name: "operation.recovery.started",
+          stage: "recovery",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
         });
         const paypalStripe = (resumePaypalFlopay ?? resumeFlopay)?.getRawProvider();
         if (!paypalStripe) {
@@ -5917,7 +7085,7 @@ function FloPayCheckout({
         const paymentMethodId = typeof paymentIntent.payment_method === "string" ? paymentIntent.payment_method : paymentIntent.payment_method?.id;
         let finalResultStatus = resultStatus;
         if (resumeState.sessionId) {
-          const resumeApi = new import_js4.PaymentAPI(resolvedBillingUrl);
+          const resumeApi = new import_js4.PaymentAPI(resolvedBillingUrl, { telemetry: false });
           const resumeSessionResult = await resumeApi.getUnifiedCheckoutSession(resumeState.sessionId);
           const resumeSession = resumeSessionResult.data.session;
           if (resumeSession && resumeSession.status !== "complete") {
@@ -5925,6 +7093,7 @@ function FloPayCheckout({
               billingApiUrl: resolvedBillingUrl,
               sessionId: resumeState.sessionId,
               session: resumeSession,
+              telemetry: false,
               tokenizedData: {
                 id: paymentMethodId ?? paymentIntent.id,
                 type: "card",
@@ -5942,20 +7111,84 @@ function FloPayCheckout({
           }
         }
         if (resumeState.sessionId) markSessionRecentlyCompleted(resumeState.sessionId);
+        resumeTelemetry?.log({
+          name: "operation.recovery.completed",
+          stage: "recovery",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+        resumeTelemetry?.performance({
+          stage: "redirect_resume",
+          durationMs: resumeTelemetry.elapsed(redirectResumeStartedAt),
+          durationMode: "machine",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
+        resumeTelemetry?.terminal({
+          outcome: "payment_succeeded",
+          provider: "paypal",
+          paymentMethodCategory: "paypal"
+        });
         setModeOverlayStatus("success");
         await sleep(PROCESSING_OVERLAY_SUCCESS_DELAY_MS);
-        onCompleteRef.current?.({
+        invokeMerchantCallback(() => onCompleteRef.current?.({
           status: finalResultStatus,
           paymentIntentId: paymentIntent.id,
           paymentMethodId,
           checkoutMethod: "paypal"
-        });
+        }));
       } catch (err) {
         const floPayErr = normalizeSavedPaymentError(err);
         const method = floPayErr.checkoutMethod ?? "paypal";
+        const expectedDecline = Boolean(
+          floPayErr.declineCode || floPayErr.code?.toLowerCase().includes("declin")
+        );
+        if (resumeTelemetry) {
+          resumeTelemetry.performance({
+            stage: "redirect_resume",
+            durationMs: resumeTelemetry.elapsed(redirectResumeStartedAt),
+            durationMode: "machine",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
+          if (expectedDecline) {
+            resumeTelemetry.terminal({
+              outcome: "payment_declined",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+          } else {
+            resumeTelemetry.error({
+              errorCode: "REDIRECT_RESUME_FAILED",
+              stage: "redirect_resume",
+              provider: "paypal",
+              paymentMethodCategory: "paypal"
+            });
+          }
+        } else if (expectedDecline) {
+          const reporter = createStandaloneTelemetryReporter(
+            resolvedBillingUrl,
+            telemetry,
+            telemetryCheckoutContext
+          );
+          reporter.terminal({
+            outcome: "payment_declined",
+            provider: "paypal",
+            paymentMethodCategory: "paypal"
+          });
+          finishStandaloneTelemetry(reporter);
+        } else {
+          reportStandaloneTelemetryError(
+            resolvedBillingUrl,
+            telemetry,
+            telemetryCheckoutContext,
+            "REDIRECT_RESUME_FAILED",
+            "redirect_resume"
+          );
+        }
         setModeError(floPayErr.message);
         setModeOverlayError(floPayErr.message);
-        onErrorRef.current?.(floPayErr);
+        invokeMerchantCallback(() => onErrorRef.current?.(floPayErr));
         emitDecline(method, floPayErr, {
           code: floPayErr.code,
           declineCode: floPayErr.declineCode
@@ -5970,7 +7203,7 @@ function FloPayCheckout({
         setConfirmProcessing(false);
       }
     })();
-  }, [emitDecline, locale, normalizeSavedPaymentError, resolvedBillingUrl]);
+  }, [emitDecline, invokeMerchantCallback, locale, normalizeSavedPaymentError, resolvedBillingUrl, telemetry]);
   const initializedHashRef = (0, import_react10.useRef)(null);
   function hashCreateParams(params) {
     const key = JSON.stringify({
@@ -6020,42 +7253,105 @@ function FloPayCheckout({
     setModeOverlayStatus(null);
   }, [createSessionHash, initialErrorMessage, sessionIdProp]);
   async function resolveInlineSession(params, cacheKey) {
-    const api = new import_js4.PaymentAPI(resolvedBillingUrl);
-    const cached = readCachedInlineSession(cacheKey);
-    let sid = cached?.sid ?? null;
-    let realResult = null;
-    if (sid) {
-      try {
-        realResult = await api.getUnifiedCheckoutSession(sid, cached?.nonce);
-        const status = realResult.data.session?.status;
-        if (status === "complete") {
-          if (wasSessionRecentlyCompleted(sid)) {
-            return { sid, result: realResult };
+    const reporter = createStandaloneTelemetryReporter(
+      resolvedBillingUrl,
+      telemetry,
+      telemetryCheckoutContext
+    );
+    const api = new import_js4.PaymentAPI(resolvedBillingUrl, { telemetry: false });
+    try {
+      const cached = readCachedInlineSession(cacheKey);
+      reporter.log({
+        name: cached ? "operation.cache.hit" : "operation.cache.miss",
+        stage: "session_create",
+        requestCategory: "session_create"
+      });
+      let sid = cached?.sid ?? null;
+      let realResult = null;
+      if (sid) {
+        try {
+          realResult = await api.getUnifiedCheckoutSession(sid, cached?.nonce);
+          const status = realResult.data.session?.status;
+          if (status === "complete") {
+            if (wasSessionRecentlyCompleted(sid)) {
+              return { sid, result: realResult };
+            }
+            clearCachedInlineSession(cacheKey);
+            sid = null;
+            realResult = null;
           }
+        } catch {
+          reporter.log({
+            name: "operation.fallback",
+            stage: "session_read",
+            requestCategory: "session_read"
+          });
           clearCachedInlineSession(cacheKey);
           sid = null;
-          realResult = null;
         }
-      } catch {
-        clearCachedInlineSession(cacheKey);
-        sid = null;
       }
-    }
-    if (!sid) {
-      const paramsWithAnalytics = {
-        ...params,
-        avsCheck: !!enableAVS,
-        avsConfig: typeof enableAVS === "object" ? enableAVS : void 0,
-        checkoutType: "embedded_checkout",
-        checkoutLayout: children ? "custom_layout" : layout === "buttons" ? "buttons_layout" : "default_layout"
-      };
-      realResult = await api.createAndFetchSession(paramsWithAnalytics);
-      sid = realResult.data.session?.id ?? "";
-      if (sid) {
-        persistCachedInlineSession(cacheKey, sid, realResult.data.session?.clientSecret);
+      if (!sid) {
+        const sessionCreateStartedAt = reporter.now();
+        reporter.log({
+          name: "session.create.started",
+          stage: "session_create",
+          requestCategory: "session_create"
+        });
+        const paramsWithAnalytics = {
+          ...params,
+          avsCheck: !!enableAVS,
+          avsConfig: typeof enableAVS === "object" ? enableAVS : void 0,
+          checkoutType: "embedded_checkout",
+          checkoutLayout: children ? "custom_layout" : layout === "buttons" ? "buttons_layout" : "default_layout"
+        };
+        try {
+          realResult = await api.createAndFetchSession(paramsWithAnalytics);
+          reporter.log({
+            name: "session.request.completed",
+            stage: "session_complete",
+            requestCategory: "session_create",
+            statusClass: "2xx"
+          });
+          reporter.performance({
+            stage: "session_create",
+            durationMs: reporter.now() - sessionCreateStartedAt,
+            durationMode: "machine",
+            requestCategory: "session_create",
+            statusClass: "2xx"
+          });
+        } catch (error) {
+          reporter.performance({
+            stage: "session_create",
+            durationMs: reporter.now() - sessionCreateStartedAt,
+            durationMode: "machine",
+            requestCategory: "session_create",
+            statusClass: "network_error"
+          });
+          if (error instanceof import_shared8.FloPayError && error.type === "validation_error") {
+            reporter.terminal({
+              outcome: "validation_rejected",
+              stage: "session_create",
+              paymentMethodCategory: "unknown"
+            });
+          } else {
+            reporter.error({
+              errorCode: "CHECKOUT_SESSION_CREATE_FAILED",
+              stage: "session_create",
+              paymentMethodCategory: "unknown",
+              requestCategory: "session_create"
+            });
+          }
+          throw error;
+        }
+        sid = realResult.data.session?.id ?? "";
+        if (sid) {
+          persistCachedInlineSession(cacheKey, sid, realResult.data.session?.clientSecret);
+        }
       }
+      return { sid: sid ?? "", result: realResult };
+    } finally {
+      finishStandaloneTelemetry(reporter);
     }
-    return { sid: sid ?? "", result: realResult };
   }
   const bootstrapInlineSession = (0, import_react10.useCallback)(
     async (patch) => {
@@ -6101,7 +7397,8 @@ function FloPayCheckout({
           publishableKey,
           paypalPublishableKey,
           billingApiUrl: resolvedBillingUrl,
-          locale
+          locale,
+          telemetry
         });
         flopayRef.current = instance;
         setFloPay(instance);
@@ -6116,7 +7413,7 @@ function FloPayCheckout({
       }
       return resolved;
     },
-    [locale, resolvedBillingUrl]
+    [locale, resolvedBillingUrl, telemetry, telemetryCheckoutContext]
   );
   const handleInlineSessionPatch = (0, import_react10.useCallback)(async (patch) => {
     if (!hasInlineSessionPatchData(patch) || cardBootstrapPending) {
@@ -6195,7 +7492,9 @@ function FloPayCheckout({
             setModeOverlayStatus("success");
             await sleep(PROCESSING_OVERLAY_SUCCESS_DELAY_MS);
             if (!cancelled) {
-              onCompleteRef.current?.({ status: "succeeded" });
+              invokeMerchantCallback(() => {
+                onCompleteRef.current?.({ status: "succeeded" });
+              });
               setModeOverlayStatus(null);
               setModeOverlayError(null);
             }
@@ -6215,8 +7514,9 @@ function FloPayCheckout({
     }
     setIsLoading(true);
     async function init() {
+      let sessionReadCompleted = false;
       try {
-        const api = new import_js4.PaymentAPI(resolvedBillingUrl);
+        const api = new import_js4.PaymentAPI(resolvedBillingUrl, { telemetry: false });
         const result = await api.getUnifiedCheckoutSession(activeSessionId, nonceProp);
         if (cancelled) return;
         setUnified(result);
@@ -6227,7 +7527,9 @@ function FloPayCheckout({
         }
         if (sess.status === "complete") {
           setIsLoading(false);
-          onSessionCompletedRef.current?.(sess.successUrl ?? "");
+          invokeMerchantCallback(() => {
+            onSessionCompletedRef.current?.(sess.successUrl ?? "");
+          });
           return;
         }
         if (sess.status === "expired") {
@@ -6235,6 +7537,7 @@ function FloPayCheckout({
             code: "checkout_session_expired"
           });
         }
+        sessionReadCompleted = true;
         const effectiveMode = checkoutModeProp ?? sess.checkoutMode ?? "full";
         setCurrentMode(effectiveMode);
         const hasPayPalRedirectParams = typeof window !== "undefined" && new URLSearchParams(window.location.search).has("payment_intent");
@@ -6266,6 +7569,23 @@ function FloPayCheckout({
         if (!cancelled) setIsLoading(false);
       } catch (err) {
         if (cancelled) return;
+        if (!(err instanceof import_shared8.FloPayError)) {
+          reportStandaloneTelemetryError(
+            resolvedBillingUrl,
+            telemetry,
+            telemetryCheckoutContext,
+            "INTERNAL_SDK_ERROR",
+            "checkout_mount"
+          );
+        } else if (!sessionReadCompleted && !isExpectedExistingSessionError(err)) {
+          reportStandaloneTelemetryError(
+            resolvedBillingUrl,
+            telemetry,
+            telemetryCheckoutContext,
+            "NETWORK_REQUEST_FAILED",
+            "session_read"
+          );
+        }
         const floPayErr = err instanceof import_shared8.FloPayError ? err : new import_shared8.FloPayError(err instanceof Error ? err.message : "Failed to initialize checkout", "api_error");
         setLoadError(floPayErr);
         setIsLoading(false);
@@ -6287,7 +7607,8 @@ function FloPayCheckout({
         publishableKey,
         paypalPublishableKey,
         billingApiUrl: resolvedBillingUrl,
-        locale
+        locale,
+        telemetry
       });
       flopayRef.current = instance;
       setFloPay(instance);
@@ -6304,6 +7625,7 @@ function FloPayCheckout({
     createSessionHash,
     effectiveCreateSessionMode,
     initSessionDependency,
+    invokeMerchantCallback,
     nonceProp,
     runSavedPaymentFlow
   ]);
@@ -6471,7 +7793,7 @@ function FloPayCheckout({
           }
         ),
         /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
-          DirectPayPalButton,
+          InstrumentedDirectPayPalButton,
           {
             sessionId: activeSessionId,
             nonce: session.clientSecret || void 0,
@@ -6486,6 +7808,8 @@ function FloPayCheckout({
             onDecline,
             onButtonClick,
             session,
+            telemetry,
+            telemetryContext: telemetryCheckoutContext,
             debug
           }
         )
@@ -7553,7 +8877,7 @@ function FloPayAutomaticPaymentButton({
     };
   }, []);
   (0, import_react13.useEffect)(() => {
-    if (!fallbackSession || typeof window === "undefined") {
+    if (typeof window === "undefined") {
       return;
     }
     const handleKeyDown = (event) => {
@@ -7565,7 +8889,7 @@ function FloPayAutomaticPaymentButton({
     return () => {
       window.removeEventListener("keydown", handleKeyDown);
     };
-  }, [fallbackSession]);
+  }, []);
   const emitDecline = (0, import_react13.useCallback)((error, method = DEFAULT_SAVED_PAYMENT_DECLINE_METHOD) => {
     onDeclineRef.current?.(buildDeclineEvent(method, error, {
       code: error.code,