@flopay/react 1.3.3 → 1.3.4

package/dist/index.mjs

@@ -100,7 +100,7 @@ function FloPayProvider({
 }
 
 // src/flopay-checkout.tsx
-import React8, { useCallback as useCallback2, useEffect as useEffect6, useMemo as useMemo4, useRef as useRef5, useState as useState4 } from "react";
+import React8, { useCallback as useCallback3, useEffect as useEffect6, useMemo as useMemo4, useRef as useRef5, useState as useState4 } from "react";
 import { PaymentAPI as PaymentAPI4 } from "@flopay/js";
 import { SDK_VERSION, FloPayError as FloPayError5, resolveBillingApiUrl as resolveBillingApiUrl3, buildCheckoutDisplayData, resolveButtonsLayoutTheme as resolveButtonsLayoutTheme2, resolveTheme as resolveTheme2 } from "@flopay/shared";
 
@@ -333,7 +333,7 @@ function VaultCardFields({
 }
 
 // src/split-card-form.tsx
-import React7, { forwardRef, useCallback, useContext as useContext3, useEffect as useEffect5, useImperativeHandle, useMemo as useMemo3, useRef as useRef4, useState as useState3 } from "react";
+import React7, { forwardRef, useCallback as useCallback2, useContext as useContext3, useEffect as useEffect5, useImperativeHandle, useMemo as useMemo3, useRef as useRef4, useState as useState3 } from "react";
 
 // src/hooks.ts
 import { useContext as useContext2 } from "react";
@@ -770,12 +770,67 @@ function isInAppBrowser(userAgent) {
 }
 
 // src/direct-paypal-button.tsx
-import { useEffect as useEffect4, useMemo as useMemo2, useRef as useRef3, useState as useState2 } from "react";
+import { useCallback, useEffect as useEffect4, useMemo as useMemo2, useRef as useRef3, useState as useState2 } from "react";
 import { loadScript } from "@paypal/paypal-js";
 import { PaymentAPI } from "@flopay/js";
 import { FloPayError as FloPayError2, normalizeGatewayEnvironment } from "@flopay/shared";
+
+// 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
 import { jsx as jsx6, jsxs as jsxs3 } from "react/jsx-runtime";
 var DEFAULT_BUTTON_HEIGHT = 45;
+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 DirectPayPalButton({
   sessionId,
   nonce,
@@ -789,6 +844,7 @@ function DirectPayPalButton({
   onComplete,
   onErrorChange,
   onDecline,
+  onTechnicalFailure,
   isProcessing = false,
   onLoadStateChange,
   onButtonClick,
@@ -798,7 +854,12 @@ function DirectPayPalButton({
   debug = false
 }) {
   const containerRef = useRef3(null);
+  const focusTargetRef = useRef3(null);
+  const pendingProviderFocusRef = useRef3(false);
   const [ready, setReady] = useState2(false);
+  const [renderGeneration, setRenderGeneration] = useState2(0);
+  const activeRenderGenerationRef = useRef3(0);
+  const [showRetryFocusTarget, setShowRetryFocusTarget] = useState2(false);
   const [failed, setFailed] = useState2(false);
   const [submitting, setSubmitting] = useState2(false);
   const baseUrl = useMemo2(() => billingApiUrl.replace(/\/+$/, ""), [billingApiUrl]);
@@ -811,6 +872,7 @@ function DirectPayPalButton({
   const onCompleteRef = useRef3(onComplete);
   const onErrorChangeRef = useRef3(onErrorChange);
   const onDeclineRef = useRef3(onDecline);
+  const onTechnicalFailureRef = useRef3(onTechnicalFailure);
   const onButtonClickRef = useRef3(onButtonClick);
   const onLoadStateChangeRef = useRef3(onLoadStateChange);
   const runBeforeButtonClickRef = useRef3(runBeforeButtonClick);
@@ -818,6 +880,11 @@ function DirectPayPalButton({
   const emailRef = useRef3(email);
   const nonceRef = useRef3(nonce);
   const beforeClickRef = useRef3(null);
+  const attemptGenerationRef = useRef3(0);
+  const attemptRef = useRef3(null);
+  const invalidatedAttemptGenerationRef = useRef3(null);
+  const attemptContextBySurfaceRef = useRef3(/* @__PURE__ */ new Map());
+  const approvalContextByTokenRef = useRef3(/* @__PURE__ */ new Map());
   useEffect4(() => {
     onTokenizedBodyRef.current = onTokenizedBody;
   }, [onTokenizedBody]);
@@ -830,6 +897,9 @@ function DirectPayPalButton({
   useEffect4(() => {
     onDeclineRef.current = onDecline;
   }, [onDecline]);
+  useEffect4(() => {
+    onTechnicalFailureRef.current = onTechnicalFailure;
+  }, [onTechnicalFailure]);
   useEffect4(() => {
     onButtonClickRef.current = onButtonClick;
   }, [onButtonClick]);
@@ -848,6 +918,129 @@ function DirectPayPalButton({
   useEffect4(() => {
     nonceRef.current = nonce;
   }, [nonce]);
+  useEffect4(() => {
+    activeRenderGenerationRef.current = renderGeneration;
+  }, [renderGeneration]);
+  useEffect4(() => {
+    if (showRetryFocusTarget) focusTargetRef.current?.focus();
+  }, [showRetryFocusTarget, renderGeneration]);
+  const focusRetryTarget = useCallback(() => {
+    window.setTimeout(() => {
+      focusTargetRef.current?.focus();
+    }, 0);
+  }, []);
+  const remountPayPalButtons = useCallback(() => {
+    setReady(false);
+    setRenderGeneration((current) => current + 1);
+  }, []);
+  const focusPayPalSurface = useCallback(() => {
+    setShowRetryFocusTarget(false);
+    const target = containerRef.current?.querySelector(
+      'iframe, button, [tabindex]:not([tabindex="-1"])'
+    );
+    (target ?? containerRef.current)?.focus?.();
+  }, []);
+  useEffect4(() => {
+    if (!ready || !pendingProviderFocusRef.current) return;
+    pendingProviderFocusRef.current = false;
+    focusPayPalSurface();
+  }, [focusPayPalSurface, ready, renderGeneration]);
+  const notifyTechnicalFailure = 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;
+  };
+  useEffect4(() => {
+    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();
+    };
+  }, []);
   useEffect4(() => {
     onLoadStateChangeRef.current?.(ready && !failed);
   }, [ready, failed]);
@@ -984,13 +1177,13 @@ function DirectPayPalButton({
       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, {
           sessionId: effectiveSessionId,
-          accountPatch: prepared?.accountPatch
+          accountPatch: prepared?.accountPatch,
+          nonce: prepared?.nonce
         });
         return;
       }
@@ -1003,7 +1196,7 @@ function DirectPayPalButton({
           effectiveUserId,
           {
             sessionId: effectiveSessionId,
-            nonce: nonceRef.current,
+            nonce: prepared?.nonce ?? nonceRef.current,
             tokenizedData: body,
             accountData: {
               userId: effectiveUserId,
@@ -1039,7 +1232,7 @@ function DirectPayPalButton({
       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;
       const response = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
         method: "POST",
@@ -1061,6 +1254,7 @@ function DirectPayPalButton({
       }
       return id;
     };
+    const effectRenderGeneration = renderGeneration;
     appendDebug("loadScript:scheduled (deferred 1 tick)");
     let loadPromise = null;
     const startTimer = setTimeout(() => {
@@ -1093,10 +1287,16 @@ function DirectPayPalButton({
           return;
         }
         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);
           try {
             setSubmitting(true);
             onErrorChangeRef.current?.(null);
-            const token = data.subscriptionID ?? data.orderID ?? "";
             if (!token) {
               throw new FloPayError2(
                 "PayPal did not return an approval token.",
@@ -1107,7 +1307,7 @@ function DirectPayPalButton({
             await dispatchTokenizedBody({
               id: token,
               isPaypal: true
-            });
+            }, context);
           } catch (err) {
             forwardError(err instanceof Error ? err.message : "PayPal capture failed.");
           } finally {
@@ -1123,47 +1323,70 @@ 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");
+            const generation = startAttempt();
+            const context = {
+              generation,
+              surfaceKey: effectRenderGeneration,
+              ...prepared
+            };
+            beforeClickRef.current = context;
+            attemptContextBySurfaceRef.current.set(effectRenderGeneration, context);
             await actions.resolve();
           },
           // 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."));
+            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;
+              }
+              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);
@@ -1263,7 +1486,7 @@ function DirectPayPalButton({
         });
       }
     };
-  }, [baseUrl, clientId, currency, environment, isSubscription, sessionId, existingOrderId]);
+  }, [baseUrl, clientId, currency, environment, isSubscription, sessionId, existingOrderId, renderGeneration]);
   const debugPanel = debug ? /* @__PURE__ */ jsxs3(
     "pre",
     {
@@ -1318,15 +1541,29 @@ ${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__ */ jsx6(
+        "button",
+        {
+          ref: focusTargetRef,
+          type: "button",
+          "data-testid": "flopay-direct-paypal-focus-target",
+          onClick: focusPayPalSurface,
+          style: DIRECT_PAYPAL_RECOVERY_ACTION_STYLE,
+          children: "Try PayPal again"
+        }
+      )
     ] })
   );
 }
@@ -1410,6 +1647,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":
@@ -1422,6 +1672,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" : 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 = useRef4(0);
+  const invalidatedGenerationRef = useRef4(null);
+  const attemptRef = useRef4(null);
+  const clearAttemptTimer = useCallback2((targetAttempt = attemptRef.current) => {
+    const attempt = targetAttempt;
+    if (attempt?.timer) {
+      clearTimeout(attempt.timer);
+      attempt.timer = null;
+    }
+  }, []);
+  const armAttemptTimer = useCallback2((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 = useCallback2((attempt) => {
+    if (!attempt.yieldedControl) return;
+    armAttemptTimer(attempt, EXTERNAL_METHOD_CALLBACK_GRACE_MS);
+  }, [armAttemptTimer]);
+  const startAttempt = useCallback2((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 = useCallback2((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 = useCallback2((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 = useCallback2(
+    (generation) => invalidatedGenerationRef.current === (generation ?? generationRef.current),
+    []
+  );
+  const isAttemptCurrent = useCallback2(
+    (generation) => attemptRef.current?.generation === generation && invalidatedGenerationRef.current !== generation,
+    []
+  );
+  const scheduleRecoveryIfReturned = useCallback2(() => {
+    const attempt = attemptRef.current;
+    if (!attempt) return;
+    armRecoveryTimer(attempt);
+  }, [armRecoveryTimer]);
+  const markAttemptYieldedControl = useCallback2(() => {
+    const attempt = attemptRef.current;
+    if (!attempt) return;
+    attempt.yieldedControl = true;
+    clearAttemptTimer(attempt);
+  }, [clearAttemptTimer]);
+  useEffect5(() => {
+    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 = getPostalCodeExample(country);
   return `Enter a valid ${getPostalCodeLabel(country)}${example ? ` (e.g. ${example})` : ""}`;
@@ -1516,6 +1878,7 @@ function PayPalButtonInner({
   isProcessing = false,
   onButtonClick,
   onDecline,
+  onTechnicalFailure,
   runBeforeButtonClick,
   onLoadStateChange,
   placeholderBorderRadius
@@ -1528,8 +1891,55 @@ function PayPalButtonInner({
   }, [loadState, onLoadStateChange]);
   const [submitting, setSubmitting] = useState3(false);
   const paypalResumeAttempted = useRef4(false);
-  const beforeClickRef = useRef4(null);
+  const focusTargetRef = useRef4(null);
+  const recoveryActionRef = useRef4(null);
+  const [surfaceKey, setSurfaceKey] = useState3(0);
+  const [showRecoveryAction, setShowRecoveryAction] = useState3(false);
+  const pendingProviderFocusRef = useRef4(false);
+  const attemptContextBySurfaceRef = useRef4(/* @__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);
+  });
+  useEffect5(() => {
+    if (showRecoveryAction) recoveryActionRef.current?.focus();
+  }, [showRecoveryAction, surfaceKey]);
+  const resetSurface = useCallback2(() => {
+    setSurfaceKey((key) => key + 1);
+  }, []);
+  const recoverTechnicalFailure = useCallback2((err, code, generation) => {
+    invalidateAttempt(generation);
+    onTechnicalFailure?.("paypal", err, { code, popupBlocked: isPopupBlockedError(err) });
+    setShowRecoveryAction(true);
+    resetSurface();
+  }, [invalidateAttempt, onTechnicalFailure, resetSurface]);
+  const focusProviderSurface = useCallback2(() => {
+    window.setTimeout(() => {
+      const target = focusTargetRef.current?.querySelector("iframe");
+      (target ?? focusTargetRef.current)?.focus();
+    }, 0);
+  }, []);
+  useEffect5(() => {
+    if (!pendingProviderFocusRef.current) return;
+    pendingProviderFocusRef.current = false;
+    focusProviderSurface();
+  }, [focusProviderSurface, surfaceKey]);
+  const handleRecoveryActionClick = useCallback2(() => {
+    setShowRecoveryAction(false);
+    onErrorChange?.(null);
+    focusProviderSurface();
+  }, [focusProviderSurface, onErrorChange]);
   useEffect5(() => {
     if (!stripe || paypalResumeAttempted.current) return;
     const params = new URLSearchParams(window.location.search);
@@ -1596,29 +2006,40 @@ function PayPalButtonInner({
       }
     })();
   }, [stripe, onTokenizedBody, onErrorChange, onDecline]);
-  const handlePayPalClick = useCallback(async (event) => {
+  const handlePayPalClick = useCallback2(async (event) => {
     if (isProcessing || submitting) {
       event.reject();
       return;
     }
     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]);
-  const handlePayPalConfirm = useCallback(async (event) => {
+  }, [attemptContextBySurfaceRef, isProcessing, onButtonClick, runBeforeButtonClick, startAttempt, submitting, surfaceKey]);
+  const handlePayPalConfirm = useCallback2(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) {
@@ -1643,9 +2064,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" };
@@ -1704,11 +2124,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") {
@@ -1730,11 +2155,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__ */ jsxs4(Fragment2, { children: [
     /* @__PURE__ */ jsx7(
       ExpressCheckoutReadySwap,
@@ -1742,29 +2167,57 @@ function PayPalButtonInner({
         state: loadState,
         placeholderTestId: "flopay-paypal-placeholder",
         borderRadius: placeholderBorderRadius,
-        children: /* @__PURE__ */ jsx7(
-          ExpressCheckoutElement,
+        children: /* @__PURE__ */ jsxs4(
+          "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__ */ jsx7(
+                "button",
+                {
+                  ref: recoveryActionRef,
+                  type: "button",
+                  "data-testid": "flopay-paypal-retry-button",
+                  onClick: handleRecoveryActionClick,
+                  style: EXTERNAL_METHOD_RECOVERY_BUTTON_STYLE,
+                  children: "Try PayPal again"
+                }
+              ),
+              /* @__PURE__ */ jsx7(
+                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);
+                    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
+              )
+            ]
           }
         )
       }
@@ -1782,6 +2235,7 @@ function WalletButtonInner({
   onErrorChange,
   onButtonClick,
   onDecline,
+  onTechnicalFailure,
   runBeforeButtonClick,
   onLoadStateChange,
   placeholderBorderRadius
@@ -1794,15 +2248,74 @@ function WalletButtonInner({
   }, [loadState, onLoadStateChange]);
   const [submitting, setSubmitting] = useState3(false);
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
-  const lastWalletMethodRef = useRef4("card");
-  const beforeClickRef = useRef4(null);
-  const handleWalletConfirm = useCallback(
+  const focusTargetRef = useRef4(null);
+  const recoveryActionRef = useRef4(null);
+  const [surfaceKey, setSurfaceKey] = useState3(0);
+  const [showRecoveryAction, setShowRecoveryAction] = useState3(false);
+  const [recoveryActionMethod, setRecoveryActionMethod] = useState3("google_pay");
+  const pendingProviderFocusRef = useRef4(false);
+  const lastWalletProviderMethodRef = useRef4("google_pay");
+  const lastWalletMethodRef = useRef4("google_pay");
+  const attemptContextBySurfaceRef = useRef4(/* @__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);
+  });
+  useEffect5(() => {
+    if (showRecoveryAction) recoveryActionRef.current?.focus();
+  }, [showRecoveryAction, surfaceKey]);
+  const resetSurface = useCallback2(() => {
+    setSurfaceKey((key) => key + 1);
+  }, []);
+  const recoverTechnicalFailure = useCallback2((method, err, code, generation) => {
+    invalidateAttempt(generation);
+    onTechnicalFailure?.(method, err, { code, popupBlocked: isPopupBlockedError(err) });
+    setRecoveryActionMethod(method);
+    setShowRecoveryAction(true);
+    resetSurface();
+  }, [invalidateAttempt, onTechnicalFailure, resetSurface]);
+  const focusProviderSurface = useCallback2(() => {
+    window.setTimeout(() => {
+      const target = focusTargetRef.current?.querySelector("iframe");
+      (target ?? focusTargetRef.current)?.focus();
+    }, 0);
+  }, []);
+  useEffect5(() => {
+    if (!pendingProviderFocusRef.current) return;
+    pendingProviderFocusRef.current = false;
+    focusProviderSurface();
+  }, [focusProviderSurface, surfaceKey]);
+  const handleRecoveryActionClick = useCallback2(() => {
+    setShowRecoveryAction(false);
+    onErrorChange?.(null);
+    focusProviderSurface();
+  }, [focusProviderSurface, onErrorChange]);
+  const handleWalletConfirm = useCallback2(
     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) {
@@ -1824,12 +2337,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) {
@@ -1862,11 +2375,16 @@ function WalletButtonInner({
         if (!intentClientSecret) throw new Error("No client_secret in payment intent response");
         const { error: confirmError, intentId } = isSetupIntentClientSecret2(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({
@@ -1879,12 +2397,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 = useMemo3(() => {
     const allKeys = ["applePay", "googlePay", "paypal", "link", "amazonPay", "klarna"];
@@ -1911,41 +2429,78 @@ function WalletButtonInner({
         state: loadState,
         placeholderTestId: "flopay-wallet-placeholder",
         borderRadius: placeholderBorderRadius,
-        children: /* @__PURE__ */ jsx7(
-          ExpressCheckoutElement,
+        children: /* @__PURE__ */ jsxs4(
+          "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__ */ jsxs4(
+                "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__ */ jsx7(
+                ExpressCheckoutElement,
+                {
+                  onReady: (event) => {
+                    setLoadState(resolveExpressCheckoutLoadState(event, availableMethodKeys));
+                  },
+                  onLoadError: (_event) => {
+                    setLoadState("load_error");
+                  },
+                  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);
+                    invalidateAttempt(attemptContext?.generation);
+                    setShowRecoveryAction(false);
+                    pendingProviderFocusRef.current = true;
+                    resetSurface();
+                  },
+                  options: {
+                    buttonType: { applePay: "plain", googlePay: "plain" },
+                    paymentMethods: expressMethodMap,
+                    layout: { maxColumns: 1, overflow: "never" }
+                  }
+                },
+                surfaceKey
+              )
+            ]
           }
         )
       }
@@ -2109,7 +2664,7 @@ function StripeMethodInlineForm({
   const [isMethodComplete, setIsMethodComplete] = useState3(false);
   const [loadState, setLoadState] = useState3("loading");
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
-  const handlePay = useCallback(async () => {
+  const handlePay = useCallback2(async () => {
     if (!stripe || !elements || isProcessing || submittingRef.current || !isMethodComplete) return;
     submittingRef.current = true;
     setSubmitting(true);
@@ -2350,7 +2905,7 @@ function StripePaymentElementInner({
       onLoadStateChange?.("loading");
     }
   }, [paymentElementMethods.length, stripeInstance, onLoadStateChange]);
-  const handleAutoConfirm = useCallback(async (method) => {
+  const handleAutoConfirm = useCallback2(async (method) => {
     if (!stripeInstance) return;
     if (submittingRef.current || isProcessing) return;
     submittingRef.current = true;
@@ -2491,7 +3046,7 @@ function StripePaymentElementInner({
   ]);
   const [localExpandedMethod, setLocalExpandedMethod] = useState3(null);
   const activeExpandedMethod = onExpandApm ? expandedApmMethod ?? null : localExpandedMethod;
-  const handleMethodClick = useCallback((method) => {
+  const handleMethodClick = useCallback2((method) => {
     if (submittingRef.current || isProcessing) return;
     if (activeExpandedMethod && activeExpandedMethod !== method) return;
     if (needsStripeMethodExplicitConfirm(method)) {
@@ -2696,20 +3251,20 @@ function SplitCardFormInner({
   const [expandedApmMethod, setExpandedApmMethod] = useState3(null);
   const showCardForm = viewState === "expanding" || viewState === "card";
   const TRANSITION_MS = 280;
-  const expandToCard = useCallback(() => {
+  const expandToCard = useCallback2(() => {
     setViewState("expanding");
     setTimeout(() => setViewState("card"), TRANSITION_MS);
   }, []);
-  const collapseToButtons = useCallback(() => {
+  const collapseToButtons = useCallback2(() => {
     setViewState("collapsing");
     setTimeout(() => setViewState("buttons"), TRANSITION_MS);
   }, []);
-  const expandToApm = useCallback((method) => {
+  const expandToApm = useCallback2((method) => {
     setExpandedApmMethod(method);
     setViewState("apm-expanding");
     setTimeout(() => setViewState("apm-form"), TRANSITION_MS);
   }, []);
-  const collapseFromApm = useCallback(() => {
+  const collapseFromApm = useCallback2(() => {
     setViewState("apm-collapsing");
     setTimeout(() => {
       setViewState("buttons");
@@ -2834,7 +3389,7 @@ function SplitCardFormInner({
     setupFutureUsage: "off_session",
     ...stripeAppearanceProp
   }), [amountInCents, currency, stripeAppearanceProp]);
-  const updateError = useCallback(
+  const updateError = useCallback2(
     (err) => {
       setError(err);
       onErrorChange?.(err);
@@ -2850,12 +3405,36 @@ function SplitCardFormInner({
       updateError(null);
     }
   }, [viewState, updateError]);
-  const emitDecline = useCallback(
+  const emitDecline = useCallback2(
     (method, input, overrides) => {
       onDecline?.(buildDeclineEvent(method, input, overrides));
     },
     [onDecline]
   );
+  const recoverExternalMethodTechnicalFailure = useCallback2(
+    (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 FloPayError3(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]
+  );
   useEffect5(() => {
     if (!vaultActive || !sessionId) {
       setVaultMount(null);
@@ -2921,7 +3500,7 @@ function SplitCardFormInner({
     baseUrl
   };
   const vaultCompletedRef = useRef4(false);
-  const buildVaultAccountSnapshot = useCallback(() => {
+  const buildVaultAccountSnapshot = useCallback2(() => {
     const { resolvedAccount: resolvedAccount2, avsConfig: avsConfig2, fullName: fullName2, avsCheckProp: avsCheckProp2 } = vaultOutcomeRef.current;
     const cc = selectedCountryRef.current || resolvedAccount2.country || "US";
     const stateVisible = avsConfig2 ? isAVSFieldVisible(avsConfig2.state, cc) : false;
@@ -3111,14 +3690,14 @@ function SplitCardFormInner({
       `[FloPay] ${stale.join(" / ")} ${stale.length === 1 ? "is" : "are"} deprecated: the Apple Pay / Google Pay surface is now driven by \`gateways.stripe.enabledPaymentMethods\` on the session response. Remove the legacy prop(s) to silence this warning.`
     );
   }, [hasEnabledMethods, showApplePay, showGooglePay]);
-  const handleNameChange = useCallback((value) => {
+  const handleNameChange = useCallback2((value) => {
     setFullName(value);
     onFullNameChange?.(value);
     const parts = value.trim().split(/\s+/);
     onFirstNameChange?.(parts[0] ?? "");
     onLastNameChange?.(parts.length > 1 ? parts.slice(1).join(" ") : "");
   }, [onFullNameChange, onFirstNameChange, onLastNameChange]);
-  const applyInlineSessionPatch = useCallback(
+  const applyInlineSessionPatch = useCallback2(
     (patch, method) => {
       if (!checkout.applyInlineSessionPatch) {
         return Promise.resolve({ error: null, sessionId, nonce });
@@ -3140,7 +3719,7 @@ function SplitCardFormInner({
     },
     [checkout.applyInlineSessionPatch, nonce, onError, sessionId, updateError]
   );
-  const runBeforeButtonClick = useCallback(async (method) => {
+  const runBeforeButtonClick = useCallback2(async (method) => {
     if (!onBeforeButtonClick) return { proceed: true };
     try {
       const result = await onBeforeButtonClick({
@@ -3177,7 +3756,7 @@ function SplitCardFormInner({
       return { proceed: false };
     }
   }, [applyInlineSessionPatch, checkout.inlineSessionDraft, onBeforeButtonClick, onError, sessionId, updateError]);
-  const processPaymentInternal = useCallback(
+  const processPaymentInternal = useCallback2(
     async (tokenizedBody, overrides) => {
       if (processingRef.current) return;
       processingRef.current = true;
@@ -3388,7 +3967,7 @@ function SplitCardFormInner({
     },
     [baseUrl, sessionId, nonce, resolvedAccount, fullName, chv, flopay, paypalFlopay, onComplete, onError, updateError, emitDecline]
   );
-  const dispatchTokenizedBody = useCallback(
+  const dispatchTokenizedBody = useCallback2(
     (tokenizedBody, overrides) => {
       if (onTokenizedBody) {
         onTokenizedBody(tokenizedBody);
@@ -3504,7 +4083,7 @@ function SplitCardFormInner({
       }, persistedOverrides);
     })();
   }, [sessionId, dispatchTokenizedBody, flopay, updateError, emitDecline]);
-  const handleSubmit = useCallback(
+  const handleSubmit = useCallback2(
     async (e) => {
       e.preventDefault();
       if (!flopay || !elements || isSubmitting || processingRef.current) return;
@@ -4312,6 +4891,7 @@ function SplitCardFormInner({
                     onComplete,
                     onErrorChange: updateError,
                     onDecline,
+                    onTechnicalFailure: recoverExternalMethodTechnicalFailure,
                     onButtonClick,
                     runBeforeButtonClick,
                     isProcessing: isSubmitting,
@@ -4335,6 +4915,7 @@ function SplitCardFormInner({
                   isProcessing: isSubmitting,
                   onButtonClick,
                   onDecline,
+                  onTechnicalFailure: recoverExternalMethodTechnicalFailure,
                   runBeforeButtonClick,
                   onLoadStateChange: setPaypalLoadState,
                   placeholderBorderRadius: buttonBorderRadius
@@ -4352,6 +4933,7 @@ function SplitCardFormInner({
                   onErrorChange: updateError,
                   onButtonClick,
                   onDecline,
+                  onTechnicalFailure: recoverExternalMethodTechnicalFailure,
                   runBeforeButtonClick,
                   onLoadStateChange: setWalletLoadState,
                   placeholderBorderRadius: buttonBorderRadius
@@ -4707,6 +5289,7 @@ function SplitCardFormInner({
             onComplete,
             onErrorChange: updateError,
             onDecline,
+            onTechnicalFailure: recoverExternalMethodTechnicalFailure,
             onButtonClick,
             runBeforeButtonClick,
             isProcessing: isSubmitting,
@@ -4730,6 +5313,7 @@ function SplitCardFormInner({
           isProcessing: isSubmitting,
           onButtonClick,
           onDecline,
+          onTechnicalFailure: recoverExternalMethodTechnicalFailure,
           runBeforeButtonClick,
           onLoadStateChange: setPaypalLoadState,
           placeholderBorderRadius: buttonBorderRadius
@@ -4747,6 +5331,7 @@ function SplitCardFormInner({
           onErrorChange: updateError,
           onButtonClick,
           onDecline,
+          onTechnicalFailure: recoverExternalMethodTechnicalFailure,
           runBeforeButtonClick,
           onLoadStateChange: setWalletLoadState,
           placeholderBorderRadius: buttonBorderRadius
@@ -5702,13 +6287,13 @@ function FloPayCheckout({
   useEffect6(() => {
     setModeError(initialErrorMessage);
   }, [initialErrorMessage]);
-  const emitDecline = useCallback2(
+  const emitDecline = useCallback3(
     (method, input, overrides) => {
       onDeclineRef.current?.(buildDeclineEvent(method, input, overrides));
     },
     []
   );
-  const runSavedPaymentFlow = useCallback2(
+  const runSavedPaymentFlow = useCallback3(
     async (sess, options) => {
       setModeError(null);
       setModeOverlayError(null);
@@ -6029,7 +6614,7 @@ function FloPayCheckout({
     }
     return { sid: sid ?? "", result: realResult };
   }
-  const bootstrapInlineSession = useCallback2(
+  const bootstrapInlineSession = useCallback3(
     async (patch) => {
       const baseParams = createSessionParamsRef.current;
       if (!baseParams) {
@@ -6090,7 +6675,7 @@ function FloPayCheckout({
     },
     [locale, resolvedBillingUrl]
   );
-  const handleInlineSessionPatch = useCallback2(async (patch) => {
+  const handleInlineSessionPatch = useCallback3(async (patch) => {
     if (!hasInlineSessionPatchData(patch) || cardBootstrapPending) {
       return {
         sessionId: resolvedSessionId,
@@ -6279,7 +6864,7 @@ function FloPayCheckout({
     nonceProp,
     runSavedPaymentFlow
   ]);
-  const handleConfirmCheckout = useCallback2(async () => {
+  const handleConfirmCheckout = useCallback3(async () => {
     if (confirmProcessing || !session) return;
     setConfirmProcessing(true);
     setModeError(null);
@@ -6846,7 +7431,7 @@ function InterimButtonsView({
 // src/checkout-form.tsx
 import { PaymentAPI as PaymentAPI5 } from "@flopay/js";
 import { FloPayError as FloPayError6 } from "@flopay/shared";
-import { forwardRef as forwardRef2, useCallback as useCallback3, useEffect as useEffect7, useImperativeHandle as useImperativeHandle2, useState as useState5 } from "react";
+import { forwardRef as forwardRef2, useCallback as useCallback4, useEffect as useEffect7, useImperativeHandle as useImperativeHandle2, useState as useState5 } from "react";
 import { Fragment as Fragment4, jsx as jsx9, jsxs as jsxs6 } from "react/jsx-runtime";
 var WALLET_RESUME_KEY = "flopay_wallet_resume";
 var CheckoutForm = forwardRef2(
@@ -6888,20 +7473,20 @@ function CheckoutFormInner({
   const isSubmitting = externalProcessing ?? processing;
   const isSelfContained = !onTokenizedBody;
   const baseUrl = (billingApiUrl || contextBillingUrl).replace(/\/+$/, "");
-  const updateError = useCallback3(
+  const updateError = useCallback4(
     (err) => {
       setError(err);
       onErrorChange?.(err);
     },
     [onErrorChange]
   );
-  const emitDecline = useCallback3(
+  const emitDecline = useCallback4(
     (input, overrides) => {
       onDecline?.(buildDeclineEvent("card", input, overrides));
     },
     [onDecline]
   );
-  const processPaymentInternal = useCallback3(
+  const processPaymentInternal = useCallback4(
     async (tokenizedBody, completionPaymentMethodId) => {
       setProcessing(true);
       updateError(null);
@@ -7013,7 +7598,7 @@ function CheckoutFormInner({
     },
     [baseUrl, sessionId, nonce, userId, email, firstName, lastName, chv, flopay, paypalFlopay, onComplete, onError, onDecline, updateError, emitDecline]
   );
-  const dispatchTokenizedBody = useCallback3(
+  const dispatchTokenizedBody = useCallback4(
     (tokenizedBody) => {
       if (onTokenizedBody) {
         onTokenizedBody(tokenizedBody);
@@ -7068,7 +7653,7 @@ function CheckoutFormInner({
       localStorage.removeItem(WALLET_RESUME_KEY);
     }
   }, [sessionId, dispatchTokenizedBody]);
-  const handleSubmit = useCallback3(
+  const handleSubmit = useCallback4(
     async (e) => {
       e.preventDefault();
       if (!flopay || !elements || isSubmitting) return;
@@ -7191,7 +7776,7 @@ function CheckoutFormInner({
 // src/paypal-button.tsx
 import { PaymentAPI as PaymentAPI6 } from "@flopay/js";
 import { FloPayError as FloPayError7 } from "@flopay/shared";
-import { useCallback as useCallback4, useEffect as useEffect8, useRef as useRef6, useState as useState6 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect8, useRef as useRef6, useState as useState6 } from "react";
 import { Fragment as Fragment5, jsx as jsx10, jsxs as jsxs7 } from "react/jsx-runtime";
 function PayPalButton({
   sessionId,
@@ -7214,7 +7799,7 @@ function PayPalButton({
   const [submitting, setSubmitting] = useState6(false);
   const paypalResumeAttempted = useRef6(false);
   const baseUrl = (billingApiUrl || contextBillingUrl).replace(/\/+$/, "");
-  const processPaymentInternal = useCallback4(
+  const processPaymentInternal = useCallback5(
     async (tokenizedBody) => {
       try {
         const api = new PaymentAPI6(baseUrl);
@@ -7242,7 +7827,7 @@ function PayPalButton({
     },
     [baseUrl, sessionId, nonce, userId, email, firstName, lastName, chv, onComplete, onErrorChange]
   );
-  const dispatchTokenizedBody = useCallback4(
+  const dispatchTokenizedBody = useCallback5(
     (body) => {
       if (onTokenizedBody) {
         onTokenizedBody(body);
@@ -7300,7 +7885,7 @@ function PayPalButton({
       }
     })();
   }, [flopay, dispatchTokenizedBody, onErrorChange]);
-  const handlePayPalConfirm = useCallback4(async () => {
+  const handlePayPalConfirm = useCallback5(async () => {
     if (!flopay || !elements) return;
     try {
       setSubmitting(true);
@@ -7380,7 +7965,7 @@ function PayPalButton({
 }
 
 // src/automatic-payment-button.tsx
-import { useCallback as useCallback5, useEffect as useEffect9, useMemo as useMemo5, useRef as useRef7, useState as useState7 } from "react";
+import { useCallback as useCallback6, useEffect as useEffect9, useMemo as useMemo5, useRef as useRef7, useState as useState7 } from "react";
 import { PaymentAPI as PaymentAPI7 } from "@flopay/js";
 import { FloPayError as FloPayError8, resolveBillingApiUrl as resolveBillingApiUrl4, resolveButtonsLayoutTheme as resolveButtonsLayoutTheme3, resolveTheme as resolveTheme3 } from "@flopay/shared";
 import { Fragment as Fragment6, jsx as jsx11, jsxs as jsxs8 } from "react/jsx-runtime";
@@ -7538,13 +8123,13 @@ function FloPayAutomaticPaymentButton({
       window.removeEventListener("keydown", handleKeyDown);
     };
   }, [fallbackSession]);
-  const emitDecline = useCallback5((error, method = DEFAULT_SAVED_PAYMENT_DECLINE_METHOD) => {
+  const emitDecline = useCallback6((error, method = DEFAULT_SAVED_PAYMENT_DECLINE_METHOD) => {
     onDeclineRef.current?.(buildDeclineEvent(method, error, {
       code: error.code,
       declineCode: error.declineCode
     }));
   }, []);
-  const showSuccess = useCallback5(async (event) => {
+  const showSuccess = useCallback6(async (event) => {
     if (!isMountedRef.current) return;
     setOverlayError(null);
     setOverlayStatus("success");
@@ -7552,7 +8137,7 @@ function FloPayAutomaticPaymentButton({
     if (!isMountedRef.current) return;
     onSuccessRef.current?.(event);
   }, []);
-  const showError = useCallback5(async (error, options) => {
+  const showError = useCallback6(async (error, options) => {
     if (!isMountedRef.current) return;
     onErrorRef.current?.(error);
     if (options?.emitDecline) {
@@ -7562,7 +8147,7 @@ function FloPayAutomaticPaymentButton({
     setOverlayStatus("error");
     await sleep2(PROCESSING_OVERLAY_ERROR_DELAY_MS);
   }, [emitDecline]);
-  const processResolvedSession = useCallback5(async (apiResult, resolvedSessionId, options) => {
+  const processResolvedSession = useCallback6(async (apiResult, resolvedSessionId, options) => {
     const session = apiResult.data.session ?? null;
     if (!session) {
       throw new FloPayError8("No session data returned", "api_error");
@@ -7718,7 +8303,7 @@ function FloPayAutomaticPaymentButton({
     showError,
     showSuccess
   ]);
-  const handleButtonClick = useCallback5(async (event) => {
+  const handleButtonClick = useCallback6(async (event) => {
     buttonProps.onClick?.(event);
     if (event.defaultPrevented || disabled || isProcessing) {
       return;
@@ -7800,7 +8385,7 @@ function FloPayAutomaticPaymentButton({
     showError,
     showSuccess
   ]);
-  const handleFallbackComplete = useCallback5((result) => {
+  const handleFallbackComplete = useCallback6((result) => {
     const activeFallback = fallbackSessionRef.current;
     setFallbackSession(null);
     onSuccessRef.current?.({
@@ -7810,10 +8395,10 @@ function FloPayAutomaticPaymentButton({
       autoCompleted: false
     });
   }, []);
-  const handleFallbackError = useCallback5((error) => {
+  const handleFallbackError = useCallback6((error) => {
     onErrorRef.current?.(error);
   }, []);
-  const handleFallbackDecline = useCallback5((decline) => {
+  const handleFallbackDecline = useCallback6((decline) => {
     onDeclineRef.current?.(decline);
   }, []);
   const themeBundle = useMemo5(() => resolveTheme3(theme), [theme]);