@easypayment/medusa-payment-paypal 0.9.18 → 0.9.19

package/src/admin/routes/settings/paypal/connection/page.tsx

@@ -36,47 +36,145 @@ declare global {
 
 
 const SERVICE_URL = "/admin/paypal/onboarding-link"
-const CACHE_KEY = "pp_onboard_cache"
+// The mini-browser popup is opened by us (see openOnboardingPopup). We give it a
+// stable window name so that, even if PayPal's partner.js *also* intercepts the
+// click, window.open() with the same name re-targets the one window instead of
+// spawning a second one.
+const POPUP_NAME = "PPMiniBrowser"
+const CACHE_PREFIX = "pp_onboard_cache"
 const CACHE_EXPIRY = 10 * 60 * 1000
 
 const ONBOARDING_COMPLETE_ENDPOINT = "/admin/paypal/onboard-complete"
 const STATUS_ENDPOINT = "/admin/paypal/status"
 const SAVE_CREDENTIALS_ENDPOINT = "/admin/paypal/save-credentials"
 const DISCONNECT_ENDPOINT = "/admin/paypal/disconnect"
+const ENVIRONMENT_ENDPOINT = "/admin/paypal/environment"
 
-let cachedUrl: string | null = null
-if (typeof window !== "undefined") {
+type Env = "sandbox" | "live"
+
+// Onboarding URLs are environment-specific and short-lived, so the cache must be
+// keyed per environment — a single shared key let a stale sandbox URL leak into
+// the live flow (and vice-versa) after a reload.
+const cacheKeyFor = (env: Env) => `${CACHE_PREFIX}_${env}`
+
+function readCachedUrl(env: Env): string | null {
+  if (typeof window === "undefined") return null
+  try {
+    const raw = localStorage.getItem(cacheKeyFor(env))
+    if (!raw) return null
+    const data = JSON.parse(raw)
+    if (
+      data &&
+      typeof data.url === "string" &&
+      Date.now() - (Number(data.ts) || 0) < CACHE_EXPIRY
+    ) {
+      return data.url
+    }
+  } catch {
+    /* ignore malformed cache */
+  }
+  return null
+}
+
+function writeCachedUrl(env: Env, url: string) {
   try {
-    const cached = localStorage.getItem(CACHE_KEY)
-    if (cached) {
-      const data = JSON.parse(cached)
-      if (new Date().getTime() - data.ts < CACHE_EXPIRY) {
-        cachedUrl = data.url
+    localStorage.setItem(cacheKeyFor(env), JSON.stringify({ url, ts: Date.now() }))
+  } catch {
+    /* ignore quota / disabled storage */
+  }
+}
+
+function clearCachedUrl(env?: Env) {
+  try {
+    if (env) {
+      localStorage.removeItem(cacheKeyFor(env))
+    } else {
+      localStorage.removeItem(cacheKeyFor("sandbox"))
+      localStorage.removeItem(cacheKeyFor("live"))
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+// PayPal delivers the seamless-onboarding result by posting a message to
+// window.opener. We validate the sender is actually a PayPal origin before
+// trusting authCode/sharedId.
+function isPayPalOrigin(origin: string): boolean {
+  try {
+    const host = new URL(origin).hostname.toLowerCase()
+    return (
+      host === "www.paypal.com" ||
+      host === "www.sandbox.paypal.com" ||
+      host.endsWith(".paypal.com") ||
+      host.endsWith(".paypalobjects.com")
+    )
+  } catch {
+    return false
+  }
+}
+
+// The completion message shape is not strongly documented, so extract
+// authCode/sharedId defensively from objects, JSON strings, or query strings.
+// We only ever act when BOTH values are present, which keeps the many unrelated
+// intermediate postMessages PayPal emits from triggering a false completion.
+function extractAuth(data: unknown): { authCode?: string; sharedId?: string } {
+  if (!data) return {}
+
+  if (typeof data === "object") {
+    const obj = data as Record<string, any>
+    const authCode = obj.authCode ?? obj.auth_code ?? obj.authcode
+    const sharedId = obj.sharedId ?? obj.shared_id ?? obj.sharedid
+    if (authCode && sharedId) {
+      return { authCode: String(authCode), sharedId: String(sharedId) }
+    }
+    for (const key of ["data", "payload", "message", "detail", "body"]) {
+      if (obj[key] && typeof obj[key] === "object") {
+        const inner = extractAuth(obj[key])
+        if (inner.authCode && inner.sharedId) return inner
+      }
+    }
+    return {}
+  }
+
+  if (typeof data === "string") {
+    const s = data.trim()
+    if (!s) return {}
+    if (s.startsWith("{")) {
+      try {
+        return extractAuth(JSON.parse(s))
+      } catch {
+        /* not JSON */
+      }
+    }
+    if (/auth_?code/i.test(s) && /shared_?id/i.test(s)) {
+      try {
+        const sp = new URLSearchParams(s.replace(/^[?#]/, ""))
+        const authCode = sp.get("authCode") || sp.get("auth_code") || undefined
+        const sharedId = sp.get("sharedId") || sp.get("shared_id") || undefined
+        if (authCode && sharedId) return { authCode, sharedId }
+      } catch {
+        /* not a query string */
       }
     }
-  } catch (e) {
-    console.error("Cache read error:", e)
   }
+
+  return {}
 }
 
 
 export default function PayPalConnectionPage() {
-  const [env, setEnv] = useState<"sandbox" | "live">("live")
-
-  useEffect(() => {
-    fetch("/admin/paypal/environment", { method: "GET", credentials: "include" })
-      .then((r) => r.json())
-      .then((d) => {
-        const v = d?.environment === "sandbox" ? "sandbox" : "live"
-        setEnv(v)
-      })
-      .catch(() => {})
-  }, [])
+  const [env, setEnv] = useState<Env>("live")
+  // We must not generate/fetch an onboarding link until we know which
+  // environment the server is actually on, otherwise the first fetch races the
+  // GET /environment response and can target the wrong environment.
+  const [envReady, setEnvReady] = useState(false)
 
   const [connState, setConnState] = useState<
     "loading" | "ready" | "connected" | "error"
   >("loading")
   const [error, setError] = useState<string | null>(null)
+  const [popupBlocked, setPopupBlocked] = useState(false)
   const [finalUrl, setFinalUrl] = useState<string>("")
   const [showManual, setShowManual] = useState(false)
   const [clientId, setClientId] = useState("")
@@ -95,6 +193,23 @@ export default function PayPalConnectionPage() {
   const runIdRef = useRef(0)
   const currentRunId = useRef(0)
 
+  // Live mirrors of state so the document-level capture click listener (set up
+  // once) and the stable completion callback always see current values.
+  const finalUrlRef = useRef(finalUrl)
+  finalUrlRef.current = finalUrl
+  const connStateRef = useRef(connState)
+  connStateRef.current = connState
+  const inProgressRef = useRef(onboardingInProgress)
+  inProgressRef.current = onboardingInProgress
+  const envRef = useRef<Env>(env)
+  envRef.current = env
+
+  const popupRef = useRef<Window | null>(null)
+  const popupPollRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  // Guards against the two redundant completion paths (our own message listener
+  // and partner.js's onboardingCallback bridge) both POSTing the same result.
+  const completedRef = useRef(false)
+
   const ppBtnMeasureRef = useRef<HTMLAnchorElement | null>(null)
   const [ppBtnWidth, setPpBtnWidth] = useState<number | null>(null)
 
@@ -107,8 +222,168 @@ export default function PayPalConnectionPage() {
     setError(msg)
   }, [])
 
+  const stopPopupPoll = useCallback(() => {
+    if (popupPollRef.current) {
+      clearInterval(popupPollRef.current)
+      popupPollRef.current = null
+    }
+  }, [])
+
+  // Open the PayPal mini-browser ourselves, synchronously, inside the click
+  // gesture. This is the crux of the fix: browsers only render window.open() as
+  // a real popup (instead of a tab — or blocking it) when it runs synchronously
+  // in a user gesture. Because finalUrl is already in state at click time, we
+  // never need an await before opening, and we never depend on winning a race
+  // with partner.js's asynchronous click binding.
+  const openOnboardingPopup = useCallback(
+    (url: string): Window | null => {
+      const w = 450
+      const h = 600
+      const baseLeft =
+        typeof window.screenX === "number" ? window.screenX : (window as any).screenLeft || 0
+      const baseTop =
+        typeof window.screenY === "number" ? window.screenY : (window as any).screenTop || 0
+      const outerW =
+        window.outerWidth || document.documentElement.clientWidth || 1024
+      const outerH =
+        window.outerHeight || document.documentElement.clientHeight || 768
+      const left = Math.round(baseLeft + Math.max(0, (outerW - w) / 2))
+      const top = Math.round(baseTop + Math.max(0, (outerH - h) / 2))
+      const features = `popup=yes,width=${w},height=${h},left=${left},top=${top},scrollbars=yes,resizable=yes`
+
+      let popup: Window | null = null
+      try {
+        popup = window.open(url, POPUP_NAME, features)
+      } catch {
+        popup = null
+      }
+
+      if (popup) {
+        popupRef.current = popup
+        try {
+          popup.focus()
+        } catch {
+          /* ignore */
+        }
+        stopPopupPoll()
+        popupPollRef.current = setInterval(() => {
+          if (!popupRef.current || popupRef.current.closed) {
+            stopPopupPoll()
+          }
+        }, 1000)
+      }
+
+      return popup
+    },
+    [stopPopupPoll]
+  )
+
+  // Single entry point for "Connect to PayPal". Hard-guards on a real, ready
+  // URL so a half-loaded button can never open anything.
+  const openConnect = useCallback(() => {
+    if (
+      connStateRef.current !== "ready" ||
+      !finalUrlRef.current ||
+      inProgressRef.current
+    ) {
+      return
+    }
+    completedRef.current = false
+    const popup = openOnboardingPopup(finalUrlRef.current)
+    if (!popup) {
+      setPopupBlocked(true)
+      return
+    }
+    setPopupBlocked(false)
+  }, [openOnboardingPopup])
+
+  // Exchange the seller authCode/sharedId for credentials. Reached from BOTH
+  // PayPal's partner.js bridge (window.onboardingCallback) and our own postMessage
+  // listener; completedRef makes it idempotent so we only POST once.
+  const completeOnboarding = useCallback(
+    async (authCode: string, sharedId: string) => {
+      if (!authCode || !sharedId) return
+      if (completedRef.current) return
+      completedRef.current = true
+
+      try {
+        window.onbeforeunload = null
+      } catch {
+        /* ignore */
+      }
+
+      const activeEnv: Env = envRef.current === "sandbox" ? "sandbox" : "live"
+
+      setOnboardingInProgress(true)
+      setConnState("loading")
+      setError(null)
+      setPopupBlocked(false)
+
+      try {
+        const res = await fetch(ONBOARDING_COMPLETE_ENDPOINT, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          credentials: "include",
+          body: JSON.stringify({ authCode, sharedId, env: activeEnv }),
+        })
+
+        if (!res.ok) {
+          const txt = await res.text().catch(() => "")
+          throw new Error(txt || `Onboarding exchange failed (${res.status})`)
+        }
+
+        // Close the popup we opened, plus any partner.js-managed flow.
+        try {
+          popupRef.current?.close()
+        } catch {
+          /* ignore */
+        }
+        stopPopupPoll()
+        try {
+          const close1 = window.PAYPAL?.apps?.Signup?.MiniBrowser?.closeFlow
+          if (typeof close1 === "function") close1()
+        } catch {
+          /* ignore */
+        }
+        try {
+          const close2 =
+            window.PAYPAL?.apps?.Signup?.miniBrowser &&
+            (window.PAYPAL.apps.Signup.miniBrowser as any).closeFlow
+          if (typeof close2 === "function") close2()
+        } catch {
+          /* ignore */
+        }
+
+        clearCachedUrl(activeEnv)
+
+        try {
+          const statusRes = await fetch(
+            `${STATUS_ENDPOINT}?environment=${activeEnv}`,
+            { method: "GET", credentials: "include" }
+          )
+          const refreshedStatus = await statusRes.json().catch(() => ({}))
+          setStatusInfo(refreshedStatus || null)
+        } catch {
+          /* ignore — still consider it connected below */
+        }
+
+        setConnState("connected")
+        setShowManual(false)
+      } catch (e: any) {
+        // Allow a retry after a failed exchange.
+        completedRef.current = false
+        console.error(e)
+        setConnState("error")
+        setError(e?.message || "Exchange failed while saving credentials.")
+      } finally {
+        setOnboardingInProgress(false)
+      }
+    },
+    [stopPopupPoll]
+  )
+
   const fetchFreshLink = useCallback(
-    (runId: number) => {
+    (runId: number, targetEnv: Env) => {
       if (initLoaderRef.current) {
         const loaderText = initLoaderRef.current.querySelector("#loader-text")
         if (loaderText)
@@ -121,6 +396,9 @@ export default function PayPalConnectionPage() {
         credentials: "include",
         body: JSON.stringify({
           products: ["PPCP"],
+          // Generate the link for the explicitly selected environment so it can
+          // never depend on a racing POST /environment having landed yet.
+          environment: targetEnv,
         }),
       })
         .then((r) => {
@@ -139,10 +417,7 @@ export default function PayPalConnectionPage() {
           const url =
             href + (href.includes("?") ? "&" : "?") + "displayMode=minibrowser"
 
-          localStorage.setItem(
-            CACHE_KEY,
-            JSON.stringify({ url, ts: Date.now() })
-          )
+          writeCachedUrl(targetEnv, url)
 
           setFinalUrl(url)
           setConnState("ready")
@@ -152,9 +427,35 @@ export default function PayPalConnectionPage() {
           showError("Unable to connect to service.")
         })
     },
-    [env, showError]
+    [showError]
   )
 
+  // Resolve the server's current environment before doing anything else.
+  useEffect(() => {
+    let alive = true
+    fetch(ENVIRONMENT_ENDPOINT, { method: "GET", credentials: "include" })
+      .then((r) => r.json())
+      .then((d) => {
+        if (!alive) return
+        setEnv(d?.environment === "sandbox" ? "sandbox" : "live")
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (alive) setEnvReady(true)
+      })
+    return () => {
+      alive = false
+    }
+  }, [])
+
+  // partner.js is loaded ONLY for its postMessage->callback bridge
+  // (window.onboardingCallback), as a redundant path next to our own message
+  // listener below. It is NO LONGER responsible for opening the window — we do
+  // that synchronously in the click handler. We still init it so its message
+  // bridge registers inside this React SPA (its own DOMContentLoaded hook fired
+  // long before this route mounted). If partner.js also intercepts the click,
+  // the shared POPUP_NAME means it re-targets our single popup rather than
+  // opening a second window.
   useEffect(() => {
     if (connState !== "ready" || !finalUrl) return
 
@@ -162,15 +463,6 @@ export default function PayPalConnectionPage() {
     let cancelled = false
     let pollTimer: ReturnType<typeof setTimeout> | undefined
 
-    // PayPal's partner.js wires the mini-browser handler to its own
-    // DOMContentLoaded listener. Inside the Medusa admin (a React SPA) that
-    // event fired long before this route mounted, so partner.js never scans the
-    // button and the click falls through to the plain target="_blank" anchor —
-    // which opens PayPal onboarding in a NEW TAB instead of the popup.
-    //
-    // To fix this we load partner.js only after the anchor exists with its real
-    // href, then explicitly run PayPal's initializer so it discovers the button
-    // and intercepts the click into the mini-browser popup.
     const initPartner = (attempt = 0) => {
       if (cancelled) return
 
@@ -200,23 +492,18 @@ export default function PayPalConnectionPage() {
         return
       }
 
-      // The namespace may not be populated the instant onload fires; retry
-      // briefly before giving up.
       if (attempt < 40) {
         pollTimer = setTimeout(() => initPartner(attempt + 1), 50)
         return
       }
 
-      // Last resort: partner.js exposed no initializer we recognise. Re-fire
-      // DOMContentLoaded so any listener it registered runs against the
-      // now-present button.
       try {
         document.dispatchEvent(new Event("DOMContentLoaded"))
       } catch {}
     }
 
-    // Remove any stale copy + namespace so the fresh load re-scans the current
-    // button (href/environment may have changed since the last render).
+    // Remove any stale copy + namespace so the fresh load re-registers against
+    // the current environment (sandbox vs live partner.js differ).
     const existingScript = document.getElementById("paypal-partner-js")
     if (existingScript) {
       existingScript.parentNode?.removeChild(existingScript)
@@ -245,15 +532,37 @@ export default function PayPalConnectionPage() {
     }
   }, [connState, finalUrl, env])
 
+  // Primary completion path: receive PayPal's seamless-onboarding postMessage
+  // ourselves. Independent of partner.js, so it works even when we opened the
+  // popup directly.
+  useEffect(() => {
+    const onMessage = (ev: MessageEvent) => {
+      if (!isPayPalOrigin(ev.origin)) return
+      const { authCode, sharedId } = extractAuth(ev.data)
+      if (authCode && sharedId) {
+        completeOnboarding(authCode, sharedId)
+      }
+    }
+    window.addEventListener("message", onMessage)
+    return () => window.removeEventListener("message", onMessage)
+  }, [completeOnboarding])
+
+  // Status check + link generation. Gated on envReady so we always use the
+  // correct environment. runId guards against a stale response from a previous
+  // environment overwriting the current one.
   useEffect(() => {
+    if (!envReady) return
+
     currentRunId.current = ++runIdRef.current
     const runId = currentRunId.current
 
     let cancelled = false
+    completedRef.current = false
 
     const run = async () => {
       setConnState("loading")
       setError(null)
+      setPopupBlocked(false)
       setFinalUrl("")
 
       try {
@@ -279,11 +588,14 @@ export default function PayPalConnectionPage() {
         console.error(e)
       }
 
-      if (cachedUrl) {
-        setFinalUrl(cachedUrl)
+      if (cancelled || runId !== currentRunId.current) return
+
+      const cached = readCachedUrl(env)
+      if (cached) {
+        setFinalUrl(cached)
         setConnState("ready")
       } else {
-        fetchFreshLink(runId)
+        fetchFreshLink(runId, env)
       }
     }
 
@@ -291,80 +603,46 @@ export default function PayPalConnectionPage() {
 
     return () => {
       cancelled = true
-      currentRunId.current = 0
     }
-  }, [env, fetchFreshLink])
+  }, [env, envReady, fetchFreshLink])
 
+  // Bridge partner.js's callback into our single idempotent completion handler.
   useLayoutEffect(() => {
-    window.onboardingCallback = async function (authCode: string, sharedId: string) {
-      try {
-        window.onbeforeunload = null
-      } catch {}
-
-      setOnboardingInProgress(true)
-      setConnState("loading")
-      setError(null)
-
-      const payload = {
-        authCode,
-        sharedId,
-        env: env === "sandbox" ? "sandbox" : "live",
-      }
-
-      try {
-        const res = await fetch(ONBOARDING_COMPLETE_ENDPOINT, {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          credentials: "include",
-          body: JSON.stringify(payload),
-        })
-
-        if (!res.ok) {
-          const txt = await res.text().catch(() => "")
-          throw new Error(txt || `Onboarding exchange failed (${res.status})`)
-        }
+    window.onboardingCallback = (authCode: string, sharedId: string) => {
+      completeOnboarding(authCode, sharedId)
+    }
+    return () => {
+      window.onboardingCallback = undefined
+    }
+  }, [completeOnboarding])
 
-        try {
-          const close1 = window.PAYPAL?.apps?.Signup?.MiniBrowser?.closeFlow
-          if (typeof close1 === "function") close1()
-        } catch {}
-        try {
-          const close2 =
-            window.PAYPAL?.apps?.Signup?.miniBrowser &&
-            (window.PAYPAL.apps.Signup.miniBrowser as any).closeFlow
-          if (typeof close2 === "function") close2()
-        } catch {}
+  // Clean up the popup poll on unmount.
+  useEffect(() => {
+    return () => {
+      stopPopupPoll()
+    }
+  }, [stopPopupPoll])
 
-        try {
-          localStorage.removeItem(CACHE_KEY)
-        } catch {}
+  // Capture-phase click interceptor: guarantees WE own the popup. Running in the
+  // capture phase on the document means we execute before partner.js's own click
+  // handler, so we can suppress it (no duplicate window) and open the popup
+  // ourselves within the same user gesture. This is what makes the first click
+  // after a cold load reliably open a popup instead of a new tab.
+  useEffect(() => {
+    const onCaptureClick = (e: MouseEvent) => {
+      const btn = paypalButtonRef.current
+      if (!btn) return
+      const target = e.target as Node | null
+      if (!target || !btn.contains(target)) return
 
-        try {
-          const statusRes = await fetch(`${STATUS_ENDPOINT}?environment=${env}`, {
-            method: "GET",
-            credentials: "include",
-          })
-          const refreshedStatus = await statusRes.json().catch(() => ({}))
-          setStatusInfo(refreshedStatus || null)
-          setConnState("connected")
-          setShowManual(false)
-        } catch {
-          setConnState("connected")
-          setShowManual(false)
-        }
-        setOnboardingInProgress(false)
-      } catch (e: any) {
-        console.error(e)
-        setConnState("error")
-        setError(e?.message || "Exchange failed while saving credentials.")
-        setOnboardingInProgress(false)
-      }
+      e.preventDefault()
+      e.stopImmediatePropagation()
+      openConnect()
     }
 
-    return () => {
-      window.onboardingCallback = undefined
-    }
-  }, [env])
+    document.addEventListener("click", onCaptureClick, true)
+    return () => document.removeEventListener("click", onCaptureClick, true)
+  }, [openConnect])
 
   useLayoutEffect(() => {
     const el = ppBtnMeasureRef.current
@@ -391,10 +669,12 @@ export default function PayPalConnectionPage() {
     }
   }, [connState, env, finalUrl])
 
+  // Defensive fallback: the capture listener above normally handles the click
+  // and stops propagation before React sees it. If for any reason it didn't, we
+  // still prevent the native target from opening a tab and open the popup here.
   const handleConnectClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
-    if (connState !== "ready" || !finalUrl || onboardingInProgress) {
-      e.preventDefault()
-    }
+    e.preventDefault()
+    openConnect()
   }
 
   const handleSaveManual = async () => {
@@ -430,9 +710,7 @@ export default function PayPalConnectionPage() {
       setStatusInfo(refreshedStatus || null)
       setShowManual(false)
 
-      try {
-        localStorage.removeItem(CACHE_KEY)
-      } catch {}
+      clearCachedUrl(env)
     } catch (e: any) {
       console.error(e)
       setConnState("error")
@@ -466,14 +744,12 @@ export default function PayPalConnectionPage() {
         throw new Error(t || `Disconnect failed (${res.status})`)
       }
 
-      try {
-        localStorage.removeItem(CACHE_KEY)
-
-      } catch {}
+      clearCachedUrl(env)
 
+      completedRef.current = false
       currentRunId.current = ++runIdRef.current
       const runId = currentRunId.current
-      fetchFreshLink(runId)
+      fetchFreshLink(runId, env)
     } catch (e: any) {
       console.error(e)
       setConnState("error")
@@ -484,22 +760,27 @@ export default function PayPalConnectionPage() {
   }
 
   const handleEnvChange = async (e: React.ChangeEvent<HTMLSelectElement>) => {
-    const next = e.target.value as "sandbox" | "live"
+    const next = e.target.value as Env
+
+    completedRef.current = false
+    setPopupBlocked(false)
+    // Drop both cached URLs so neither environment can serve a stale link.
+    clearCachedUrl()
+
+    // Update local state immediately (drives the status/link refetch with the
+    // explicit environment) and persist the choice. Because the link/status
+    // fetches are environment-explicit, correctness no longer depends on this
+    // POST winning a race.
     setEnv(next)
-    cachedUrl = null
 
     try {
-      await fetch("/admin/paypal/environment", {
+      await fetch(ENVIRONMENT_ENDPOINT, {
         method: "POST",
         headers: { "content-type": "application/json" },
         credentials: "include",
         body: JSON.stringify({ environment: next }),
       })
     } catch {}
-
-    try {
-      localStorage.removeItem(CACHE_KEY)
-    } catch {}
   }
 
   return (
@@ -584,7 +865,7 @@ export default function PayPalConnectionPage() {
                         ppBtnMeasureRef.current = node
                       }}
                       id="paypal-button"
-                      target="_blank"
+                      target={POPUP_NAME}
                       data-paypal-button="true"
                       href={finalUrl || "#"}
                       data-paypal-onboard-complete="onboardingCallback"
@@ -599,6 +880,13 @@ export default function PayPalConnectionPage() {
                       Connect to PayPal
                     </a>
 
+                    {popupBlocked && (
+                      <div className="mt-3 text-left text-xs bg-amber-50 text-amber-700 p-3 border border-amber-200 rounded">
+                        Your browser blocked the PayPal popup. Please allow popups
+                        for this site, then click “Connect to PayPal” again.
+                      </div>
+                    )}
+
                     <div
                       className="mt-2"
                       style={{