@easypayment/medusa-payment-paypal 0.9.25 → 0.9.26

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

@@ -13,11 +13,16 @@ export const config = defineRouteConfig({
   label: "PayPal Connection",
 })
 
-
-const PARTNER_JS_URLS = {
-  sandbox: "https://www.sandbox.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js",
-  live: "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js",
-} as const
+// Let partner.js own the entire onboarding flow: it opens PayPal's mini-browser
+// itself (synchronously inside the click, so no new tab / no popup block), it
+// receives PayPal's completion postMessage, and it invokes the callback named in
+// `data-paypal-onboard-complete` with (authCode, sharedId). This is PayPal's
+// documented integration and matches the official @easypayment WooCommerce
+// plugin. Opening the popup ourselves (a previous attempt at fixing the "opens a
+// new tab" issue) stopped partner.js from receiving completion, which left the
+// popup stranded on PayPal's "isuDone" page and never saved credentials.
+const PARTNER_JS_URL =
+  "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js"
 
 declare global {
   interface Window {
@@ -26,7 +31,6 @@ declare global {
         Signup?: {
           miniBrowser?: { init?: () => void; closeFlow?: () => void }
           MiniBrowser?: { init?: () => void; closeFlow?: () => void }
-          render?: () => void
         }
       }
     }
@@ -34,13 +38,7 @@ declare global {
   }
 }
 
-
 const SERVICE_URL = "/admin/paypal/onboarding-link"
-// PayPal's conventional mini-browser window name (also the anchor target).
-const POPUP_NAME = "PPFrame"
-
-// The onboarding link is cached in the browser for 6 hours so it is always
-// present for the mini-browser flow without regenerating on every load.
 const CACHE_PREFIX = "pp_onboard_cache"
 const CACHE_EXPIRY = 6 * 60 * 60 * 1000 // 6 hours
 
@@ -73,12 +71,11 @@ function readCachedUrl(env: Env): string | null {
   return null
 }
 
-function writeCachedUrl(env: Env, url: string): boolean {
+function writeCachedUrl(env: Env, url: string) {
   try {
     localStorage.setItem(cacheKeyFor(env), JSON.stringify({ url, ts: Date.now() }))
-    return readCachedUrl(env) === url
   } catch {
-    return false
+    /* ignore */
   }
 }
 
@@ -95,73 +92,6 @@ function clearCachedUrl(env?: Env) {
   }
 }
 
-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
-  }
-}
-
-// Defensively pull authCode/sharedId out of whatever shape PayPal posts back
-// (object, JSON string, or query string; possibly nested). We only act when both
-// are present, which ignores the many unrelated intermediate messages PayPal
-// emits.
-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 ?? obj.code
-    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", "params"]) {
-      if (obj[key] && typeof obj[key] === "object") {
-        const inner = extractAuth(obj[key])
-        if (inner.authCode && inner.sharedId) return inner
-      }
-      if (typeof obj[key] === "string") {
-        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("{") || 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 */
-      }
-    }
-  }
-
-  return {}
-}
-
-
 export default function PayPalConnectionPage() {
   const [env, setEnv] = useState<Env>("live")
   const [envReady, setEnvReady] = useState(false)
@@ -170,7 +100,6 @@ export default function PayPalConnectionPage() {
     "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("")
@@ -188,19 +117,15 @@ export default function PayPalConnectionPage() {
   const errorLogRef = useRef<HTMLDivElement>(null)
   const runIdRef = useRef(0)
   const currentRunId = useRef(0)
+  const completedRef = useRef(false)
 
+  // Long-lived listeners/timers read the current env through a ref so they never
+  // capture a stale value from the render that registered them.
   const envRef = useRef<Env>(env)
   envRef.current = env
-  const finalUrlRef = useRef(finalUrl)
-  finalUrlRef.current = finalUrl
-  const connStateRef = useRef(connState)
-  connStateRef.current = connState
-  const inProgressRef = useRef(onboardingInProgress)
-  inProgressRef.current = onboardingInProgress
-
-  const popupRef = useRef<Window | null>(null)
-  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null)
-  const completedRef = useRef(false)
+
+  const pollTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const pollAttemptsRef = useRef(0)
 
   const ppBtnMeasureRef = useRef<HTMLAnchorElement | null>(null)
   const [ppBtnWidth, setPpBtnWidth] = useState<number | null>(null)
@@ -214,57 +139,89 @@ export default function PayPalConnectionPage() {
     setError(msg)
   }, [])
 
-  const stopPoll = useCallback(() => {
-    if (pollRef.current) {
-      clearInterval(pollRef.current)
-      pollRef.current = null
-    }
+  // Close PayPal's mini-browser via partner.js's API (works under both the
+  // `miniBrowser` and `MiniBrowser` casings PayPal has shipped over time).
+  const closeMiniBrowser = useCallback(() => {
+    try {
+      const close1 = window.PAYPAL?.apps?.Signup?.MiniBrowser?.closeFlow
+      if (typeof close1 === "function") close1()
+    } catch {}
+    try {
+      const close2 = window.PAYPAL?.apps?.Signup?.miniBrowser?.closeFlow
+      if (typeof close2 === "function") close2()
+    } catch {}
   }, [])
 
-  // Open PayPal's mini-browser ourselves, synchronously inside the click gesture.
-  // This is the only reliable way to get a popup (rather than a new tab, which is
-  // what happens when partner.js's asynchronous open misses the user-activation
-  // window). Named POPUP_NAME and sized like PayPal's mini-browser.
-  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
+  const stopStatusPolling = useCallback(() => {
+    if (pollTimerRef.current) {
+      clearTimeout(pollTimerRef.current)
+      pollTimerRef.current = null
     }
-    if (popup) {
-      popupRef.current = popup
+    pollAttemptsRef.current = 0
+  }, [])
+
+  // Fetch status for an env and, if the seller credentials are present, flip the
+  // UI to "connected" and close the PayPal popup. Returns true once connected.
+  const refreshStatusAndMaybeConnect = useCallback(
+    async (activeEnv: Env): Promise<boolean> => {
       try {
-        popup.focus()
+        const res = await fetch(`${STATUS_ENDPOINT}?environment=${activeEnv}`, {
+          method: "GET",
+          credentials: "include",
+        })
+        const st = await res.json().catch(() => ({}))
+        const connected =
+          st?.status === "connected" && st?.seller_client_id_present === true
+        if (connected) {
+          completedRef.current = true
+          setStatusInfo(st)
+          setConnState("connected")
+          setShowManual(false)
+          setOnboardingInProgress(false)
+          clearCachedUrl(activeEnv)
+          closeMiniBrowser()
+          stopStatusPolling()
+        }
+        return connected
       } catch {
-        /* ignore */
+        return false
+      }
+    },
+    [closeMiniBrowser, stopStatusPolling]
+  )
+
+  // While a connect attempt is in flight, the seller may complete onboarding via
+  // a path that never reaches the opener (e.g. partner.js fails to fire its
+  // callback, or the popup's completion message is blocked). The return_url
+  // bridge still saves credentials server-side, so poll status as the reliable
+  // fallback: the moment credentials land, this flips to "connected" and closes
+  // the stranded popup.
+  const startStatusPolling = useCallback(() => {
+    stopStatusPolling()
+    const MAX_ATTEMPTS = 100 // ~5 min at 3s intervals
+    const tick = async () => {
+      pollAttemptsRef.current += 1
+      const connected = await refreshStatusAndMaybeConnect(envRef.current)
+      if (connected || completedRef.current) return
+      if (pollAttemptsRef.current >= MAX_ATTEMPTS) {
+        stopStatusPolling()
+        return
       }
+      pollTimerRef.current = setTimeout(tick, 3000)
     }
-    return popup
-  }, [])
+    pollTimerRef.current = setTimeout(tick, 3000)
+  }, [refreshStatusAndMaybeConnect, stopStatusPolling])
 
-  // Exchange authCode/sharedId for seller credentials. Idempotent so the multiple
-  // completion signals (our message listener, partner.js's bridge, the status
-  // poll) only run it once.
+  // Shared completion: exchange authCode/sharedId for seller credentials, then
+  // close the popup and refresh status. Invoked by partner.js's onboardingCallback
+  // and by the return_url bridge's postMessage. Guarded + server-idempotent so
+  // redundant invocations are harmless.
   const completeOnboarding = useCallback(
     async (authCode: string, sharedId: string) => {
       if (!authCode || !sharedId) return
       if (completedRef.current) return
       completedRef.current = true
 
-      stopPoll()
       try {
         window.onbeforeunload = null
       } catch {}
@@ -274,7 +231,6 @@ export default function PayPalConnectionPage() {
       setOnboardingInProgress(true)
       setConnState("loading")
       setError(null)
-      setPopupBlocked(false)
 
       try {
         const res = await fetch(ONBOARDING_COMPLETE_ENDPOINT, {
@@ -289,82 +245,114 @@ export default function PayPalConnectionPage() {
           throw new Error(txt || `Onboarding exchange failed (${res.status})`)
         }
 
-        try {
-          popupRef.current?.close()
-        } catch {}
-        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 {}
-
+        closeMiniBrowser()
         clearCachedUrl(activeEnv)
 
         try {
-          const statusRes = await fetch(`${STATUS_ENDPOINT}?environment=${activeEnv}`, {
-            method: "GET",
-            credentials: "include",
-          })
+          const statusRes = await fetch(
+            `${STATUS_ENDPOINT}?environment=${activeEnv}`,
+            { method: "GET", credentials: "include" }
+          )
           const refreshedStatus = await statusRes.json().catch(() => ({}))
           setStatusInfo(refreshedStatus || null)
         } catch {}
 
         setConnState("connected")
         setShowManual(false)
+        stopStatusPolling()
       } catch (e: any) {
         completedRef.current = false
         console.error(e)
+        // The bridge may have already saved credentials server-side; if so the
+        // poll will surface "connected". Don't strand the user on an error.
         setConnState("error")
         setError(e?.message || "Exchange failed while saving credentials.")
       } finally {
         setOnboardingInProgress(false)
       }
     },
-    [stopPoll]
+    [closeMiniBrowser, stopStatusPolling]
   )
 
-  // After the popup is opened, poll the server. If the credentials get saved by
-  // any completion path, the status flips to "connected" and we sync the UI even
-  // if a message was missed.
-  const startStatusPoll = useCallback(() => {
-    stopPoll()
-    let ticks = 0
-    pollRef.current = setInterval(async () => {
-      ticks += 1
-      if (completedRef.current || ticks > 150 /* ~5 min */) {
-        stopPoll()
-        return
-      }
+  // Bind partner.js to the connect button once it has a real onboarding URL.
+  const initPartner = useCallback(() => {
+    const signup = window.PAYPAL?.apps?.Signup
+    const init =
+      (signup?.miniBrowser && signup.miniBrowser.init) ||
+      (signup?.MiniBrowser && signup.MiniBrowser.init)
+    if (typeof init === "function") {
       try {
-        const r = await fetch(`${STATUS_ENDPOINT}?environment=${envRef.current}`, {
-          method: "GET",
-          credentials: "include",
-        })
-        const st = await r.json().catch(() => ({}))
-        if (st?.status === "connected" && st?.seller_client_id_present === true) {
-          completedRef.current = true
-          stopPoll()
-          try {
-            popupRef.current?.close()
-          } catch {}
-          clearCachedUrl(envRef.current)
-          setStatusInfo(st)
-          setConnState("connected")
-          setShowManual(false)
-          setOnboardingInProgress(false)
+        init()
+      } catch (e) {
+        console.error("[paypal] partner.js init failed:", e)
+      }
+    }
+  }, [])
+
+  // Load partner.js once for the lifetime of the page.
+  useEffect(() => {
+    const existingScript = document.getElementById("paypal-partner-js")
+    if (existingScript) return
+
+    const preloadHref = PARTNER_JS_URL
+    let preloadLink: HTMLLinkElement | null = null
+    if (!document.head.querySelector(`link[rel="preload"][href="${preloadHref}"]`)) {
+      preloadLink = document.createElement("link")
+      preloadLink.rel = "preload"
+      preloadLink.href = preloadHref
+      preloadLink.as = "script"
+      document.head.appendChild(preloadLink)
+    }
+
+    const ppScript = document.createElement("script")
+    ppScript.id = "paypal-partner-js"
+    ppScript.src = preloadHref
+    ppScript.async = true
+    document.head.appendChild(ppScript)
+
+    return () => {
+      if (preloadLink?.parentNode) preloadLink.parentNode.removeChild(preloadLink)
+      if (ppScript.parentNode) ppScript.parentNode.removeChild(ppScript)
+    }
+  }, [])
+
+  // Put the (cached or freshly generated) onboarding URL on the button, then wait
+  // for partner.js to be present before showing the button + initializing it. The
+  // button is only revealed once partner.js is ready, which is what guarantees
+  // the first click opens the mini-browser popup (never a new tab).
+  const activatePayPal = useCallback(
+    (url: string, runId: number) => {
+      if (paypalButtonRef.current) {
+        paypalButtonRef.current.href = url
+      }
+      setFinalUrl(url)
+
+      let attempts = 0
+      const MAX_ATTEMPTS = 200 // ~10s
+
+      const tryInit = () => {
+        if (runId !== currentRunId.current) return
+        if (window.PAYPAL?.apps?.Signup) {
+          initPartner()
+          setConnState("ready")
+          return
         }
-      } catch {
-        /* keep polling */
+        attempts++
+        if (attempts >= MAX_ATTEMPTS) {
+          showError(
+            "PayPal partner script failed to load. Please refresh and try again."
+          )
+          return
+        }
+        setTimeout(tryInit, 50)
       }
-    }, 2000)
-  }, [stopPoll])
 
-  const generateLinkAndReload = useCallback(
+      tryInit()
+    },
+    [initPartner, showError]
+  )
+
+  const fetchFreshLink = useCallback(
     async (targetEnv: Env, runId: number) => {
       if (initLoaderRef.current) {
         const loaderText = initLoaderRef.current.querySelector("#loader-text")
@@ -393,20 +381,14 @@ export default function PayPalConnectionPage() {
         const url =
           href + (href.includes("?") ? "&" : "?") + "displayMode=minibrowser"
 
-        const persisted = writeCachedUrl(targetEnv, url)
-        if (persisted) {
-          window.location.reload()
-          return
-        }
-
-        setFinalUrl(url)
-        setConnState("ready")
+        writeCachedUrl(targetEnv, url)
+        activatePayPal(url, runId)
       } catch {
         if (runId !== currentRunId.current) return
         showError("Unable to connect to service.")
       }
     },
-    [showError]
+    [activatePayPal, showError]
   )
 
   // Resolve the server environment first.
@@ -427,7 +409,7 @@ export default function PayPalConnectionPage() {
     }
   }, [])
 
-  // Page-load flow: connected? -> cached link? -> else generate + cache + reload.
+  // Page-load flow: connected? -> cached link? -> else generate a fresh link.
   useEffect(() => {
     if (!envReady) return
 
@@ -440,7 +422,6 @@ export default function PayPalConnectionPage() {
     const run = async () => {
       setConnState("loading")
       setError(null)
-      setPopupBlocked(false)
       setFinalUrl("")
 
       try {
@@ -470,12 +451,11 @@ export default function PayPalConnectionPage() {
 
       const cached = readCachedUrl(env)
       if (cached) {
-        setFinalUrl(cached)
-        setConnState("ready")
+        activatePayPal(cached, runId)
         return
       }
 
-      await generateLinkAndReload(env, runId)
+      await fetchFreshLink(env, runId)
     }
 
     run()
@@ -483,198 +463,51 @@ export default function PayPalConnectionPage() {
     return () => {
       cancelled = true
     }
-  }, [env, envReady, generateLinkAndReload])
-
-  // Load partner.js + init for its postMessage->onboardingCallback bridge (a
-  // secondary completion path next to our own message listener). We open the
-  // popup ourselves, so partner.js is NOT relied on to open the window.
-  useEffect(() => {
-    if (connState !== "ready" || !finalUrl) return
-
-    const scriptUrl = PARTNER_JS_URLS[env]
-    let cancelled = false
-    let pollTimer: ReturnType<typeof setTimeout> | undefined
-
-    const initPartner = (attempt = 0) => {
-      if (cancelled) return
-
-      const signup = window.PAYPAL?.apps?.Signup
-      const target =
-        signup?.miniBrowser && typeof signup.miniBrowser.init === "function"
-          ? signup.miniBrowser
-          : signup?.MiniBrowser && typeof signup.MiniBrowser.init === "function"
-            ? signup.MiniBrowser
-            : null
-
-      if (target?.init) {
-        try {
-          target.init()
-        } catch (e) {
-          console.error("[paypal] partner.js init failed:", e)
-        }
-        return
-      }
-      if (typeof signup?.render === "function") {
-        try {
-          signup.render()
-        } catch (e) {
-          console.error("[paypal] partner.js render failed:", e)
-        }
-        return
-      }
-      if (attempt < 40) {
-        pollTimer = setTimeout(() => initPartner(attempt + 1), 50)
-        return
-      }
-      try {
-        document.dispatchEvent(new Event("DOMContentLoaded"))
-      } catch {}
-    }
-
-    const existingScript = document.getElementById("paypal-partner-js")
-    if (existingScript) {
-      existingScript.parentNode?.removeChild(existingScript)
-    }
-    if (window.PAYPAL?.apps?.Signup) {
-      try {
-        delete (window.PAYPAL.apps as any).Signup
-      } catch {}
-    }
-
-    const ppScript = document.createElement("script")
-    ppScript.id = "paypal-partner-js"
-    ppScript.src = scriptUrl
-    ppScript.async = true
-    ppScript.onload = () => initPartner()
-    document.body.appendChild(ppScript)
-
-    return () => {
-      cancelled = true
-      if (pollTimer) clearTimeout(pollTimer)
-      if (ppScript.parentNode) ppScript.parentNode.removeChild(ppScript)
-    }
-  }, [connState, finalUrl, env])
-
-  // PRIMARY completion path: receive PayPal's onboarding postMessage ourselves.
-  // The diagnostic log lets us confirm the exact origin/shape PayPal sends in a
-  // real run if a tweak to the parser is ever needed.
-  useEffect(() => {
-    const onMessage = (ev: MessageEvent) => {
-      let serialized = ""
-      try {
-        serialized =
-          typeof ev.data === "string" ? ev.data : JSON.stringify(ev.data)
-      } catch {
-        serialized = String(ev.data)
-      }
+  }, [env, envReady, fetchFreshLink, activatePayPal])
 
-      const looksRelevant =
-        isPayPalOrigin(ev.origin) ||
-        /auth_?code|shared_?id|onboard|merchantId/i.test(serialized || "")
-
-      if (looksRelevant) {
-        // eslint-disable-next-line no-console
-        console.info(
-          "[PayPal onboarding] message from",
-          ev.origin,
-          "·",
-          (serialized || "").slice(0, 500)
-        )
-      }
-
-      // TERTIARY completion path: our own return_url bridge page (served by
-      // GET /store/paypal/onboard-return) posts this from inside the popup when
-      // PayPal redirects there at the end of onboarding. It runs on our backend
-      // origin (not paypal.com), so it is handled before the PayPal-origin gate
-      // below. It guarantees the popup is closed and the status is re-checked even
-      // if every PayPal postMessage was missed.
-      const d = ev.data as any
-      if (d && typeof d === "object" && d.source === "paypal-onboarding-return") {
-        try {
-          popupRef.current?.close()
-        } catch {}
-        const fromReturn = extractAuth(d.params)
-        if (fromReturn.authCode && fromReturn.sharedId) {
-          completeOnboarding(fromReturn.authCode, fromReturn.sharedId)
-        } else if (!completedRef.current) {
-          // No authCode/sharedId on the return URL (the usual case): credentials
-          // are exchanged via the postMessage/onboardingCallback path. Poll the
-          // server so the UI flips to "connected" as soon as that lands.
-          startStatusPoll()
-        }
-        return
-      }
-
-      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, startStatusPoll])
-
-  // SECONDARY completion path: partner.js's bridge calls this by name.
+  // partner.js invokes this by name (data-paypal-onboard-complete) once PayPal
+  // returns the seller's authCode + sharedId.
   useLayoutEffect(() => {
     window.onboardingCallback = (authCode: string, sharedId: string) => {
-      completeOnboarding(authCode, sharedId)
+      void completeOnboarding(authCode, sharedId)
     }
+
     return () => {
       window.onboardingCallback = undefined
     }
   }, [completeOnboarding])
 
-  // Capture-phase opener: runs before partner.js and opens the popup
-  // synchronously inside the user gesture so the mini-browser reliably opens as a
-  // popup (never a blocked window or a new tab). We open it under PayPal's
-  // conventional window name (POPUP_NAME / "PPFrame"); because partner.js also
-  // targets that same name, letting its click handler run next makes it *adopt*
-  // this very window instead of opening a second one. That adoption is what lets
-  // partner.js receive PayPal's completion postMessage, invoke onboardingCallback
-  // and auto-close the popup.
-  //
-  // IMPORTANT: we only preventDefault() (to stop the native anchor from opening a
-  // new tab) and deliberately DO NOT stopImmediatePropagation(): stopping it was
-  // what previously prevented partner.js from tracking the window, which broke
-  // onboarding completion (the popup never closed and credentials were never
-  // exchanged).
+  // The return_url bridge (/store/paypal/onboard-return), which runs inside the
+  // popup after PayPal redirects to it, posts its params back here. The bridge has
+  // already exchanged credentials server-side, so we just refresh status to flip
+  // to "connected" and close the popup. If for some reason credentials aren't yet
+  // saved but PayPal forwarded an authCode/sharedId, complete it from here too.
   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
-
-      // Stop the native anchor navigation only. Let the event keep propagating so
-      // partner.js's own click handler still runs and adopts our popup window.
-      e.preventDefault()
-
-      if (
-        connStateRef.current !== "ready" ||
-        !finalUrlRef.current ||
-        inProgressRef.current
-      ) {
-        return
-      }
-
-      completedRef.current = false
-      const popup = openOnboardingPopup(finalUrlRef.current)
-      if (!popup) {
-        setPopupBlocked(true)
-        return
-      }
-      setPopupBlocked(false)
-      startStatusPoll()
+    const onMessage = (event: MessageEvent) => {
+      const data = event?.data as
+        | { source?: string; params?: Record<string, string> }
+        | undefined
+      if (!data || data.source !== "paypal-onboarding-return") return
+
+      const params = data.params || {}
+      const authCode = params.authCode || params.auth_code
+      const sharedId = params.sharedId || params.shared_id
+      const activeEnv = envRef.current
+
+      void (async () => {
+        const connected = await refreshStatusAndMaybeConnect(activeEnv)
+        if (!connected && authCode && sharedId) {
+          await completeOnboarding(authCode, sharedId)
+        }
+      })()
     }
 
-    document.addEventListener("click", onCaptureClick, true)
-    return () => document.removeEventListener("click", onCaptureClick, true)
-  }, [openOnboardingPopup, startStatusPoll])
+    window.addEventListener("message", onMessage)
+    return () => window.removeEventListener("message", onMessage)
+  }, [completeOnboarding, refreshStatusAndMaybeConnect])
 
-  useEffect(() => {
-    return () => stopPoll()
-  }, [stopPoll])
+  // Always stop polling when the component unmounts.
+  useEffect(() => stopStatusPolling, [stopStatusPolling])
 
   useLayoutEffect(() => {
     const el = ppBtnMeasureRef.current
@@ -701,10 +534,17 @@ export default function PayPalConnectionPage() {
     }
   }, [connState, env, finalUrl])
 
-  // Defensive: the capture listener handles the click; this just guarantees the
-  // native href can never navigate.
+  // Only block the click while we are not ready; when ready, let the native click
+  // through so partner.js can open the mini-browser. Start polling status so we
+  // detect completion (and close the popup) even if no completion message reaches
+  // this page.
   const handleConnectClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
-    e.preventDefault()
+    if (connState !== "ready" || !finalUrl || onboardingInProgress) {
+      e.preventDefault()
+      return
+    }
+    completedRef.current = false
+    startStatusPolling()
   }
 
   const handleSaveManual = async () => {
@@ -754,6 +594,7 @@ export default function PayPalConnectionPage() {
     if (onboardingInProgress) return
     if (!window.confirm("Disconnect PayPal for this environment?")) return
 
+    stopStatusPolling()
     setOnboardingInProgress(true)
     setConnState("loading")
     setError(null)
@@ -778,7 +619,7 @@ export default function PayPalConnectionPage() {
       completedRef.current = false
 
       currentRunId.current = ++runIdRef.current
-      await generateLinkAndReload(env, currentRunId.current)
+      await fetchFreshLink(env, currentRunId.current)
     } catch (e: any) {
       console.error(e)
       setConnState("error")
@@ -792,9 +633,9 @@ export default function PayPalConnectionPage() {
     const next = e.target.value as Env
     if (next === env || onboardingInProgress) return
 
+    stopStatusPolling()
     completedRef.current = false
     clearCachedUrl()
-    setPopupBlocked(false)
     setConnState("loading")
 
     try {
@@ -844,6 +685,14 @@ export default function PayPalConnectionPage() {
                 <div>
                   <div className="text-sm text-green-600 bg-green-50 p-3 rounded border border-green-200">
                     ✅ Successfully connected to PayPal!
+                    <a
+                      data-paypal-button="true"
+                      data-paypal-onboard-complete="onboardingCallback"
+                      href="#"
+                      style={{ display: "none" }}
+                    >
+                      PayPal
+                    </a>
                   </div>
                   <div className="mt-3 rounded-md border border-ui-border-base bg-ui-bg-subtle p-3 text-xs text-ui-fg-subtle">
                     <div className="font-medium text-ui-fg-base">
@@ -891,7 +740,6 @@ export default function PayPalConnectionPage() {
                         ppBtnMeasureRef.current = node
                       }}
                       id="paypal-button"
-                      target={POPUP_NAME}
                       data-paypal-button="true"
                       href={finalUrl || "#"}
                       data-paypal-onboard-complete="onboardingCallback"
@@ -906,13 +754,6 @@ 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={{