Recommended pattern for Express Checkout Element (Apple Pay/Google Pay) in Facebook/Instagram in-app browsers + "Unhandled expressCheckout Element confirm event"

[sbenodiz]

Hi all - looking for the recommended pattern, and to confirm whether one error is expected behavior. This is a client-side Elements question (@stripe/stripe-js / @stripe/react-stripe-js); posting here since stripe-js discussions are disabled - happy to move it if there's a better home.

Setup

• @stripe/react-stripe-js@6.2.0, @stripe/stripe-js@9.2.0, Next.js 15.5, React 19
• Paywall using ExpressCheckoutElement (Apple Pay / Google Pay / Link) with a PaymentElement card form as fallback
• Confirming via stripe.confirmPayment({ elements, confirmParams: { return_url }, redirect: "if_required" })
• Most traffic arrives from Meta (Facebook/Instagram) ads, so a large share of sessions open inside the Facebook/Instagram in-app browser (WebView)

Problem 1 - wallets don't render in the in-app browser

Inside the FB/IG in-app browser, the Apple Pay / Google Pay buttons don't appear at all (consistent with stripe-payments-demo#84). Users fall back to typing card details, which hurts conversion on a flow that should be one-tap.

• Is there an officially recommended pattern? Is detecting the in-app browser (via User-Agent) and prompting the user to open in Safari/Chrome the intended approach, or does Stripe recommend something else?
• Is onAvailablePaymentMethodsChange (hide the element when paymentMethods is null) the correct way to avoid an empty/dead wallet region? Any edge cases?

Problem 2 - "Unhandled expressCheckout Element confirm event" despite a registered handler

We see this reported to Sentry, originating inside stripe.js, from Facebook iOS in-app browser sessions:

IntegrationError: Unhandled expressCheckout Element confirm event. Make sure to register a confirm handler.

We do register onConfirm and wrap confirmPayment in try/catch. Our read is that in a slow/torn-down WebView, Stripe.js emits this as a global unhandled rejection from its own confirm dispatch, so our try/catch can't intercept it. Simplified handler:

<ExpressCheckoutElement onConfirm={onConfirm} />

async function onConfirm(event) {
  if (!stripe || !elements) {
    event.paymentFailed({ reason: "fail" }); // only before confirmPayment
    return;
  }
  try {
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: { return_url },
      redirect: "if_required",
    });
    if (error) { /* show message; do NOT call paymentFailed here */ }
  } catch (err) {
    /* confirmPayment rejected (flaky WebView) - surface error, reset */
  }
}

• Is this expected in unstable WebView environments, or a bug we can avoid?
• Is calling event.paymentFailed({ reason: "fail" }) only before confirmPayment (to avoid "Unexpected call to paymentFailed()") the correct contract?

Thanks!

[MrTONYCHAN]

These are two separate conditions.

For the wallet buttons, an embedded Facebook/Instagram WebView may not satisfy the browser/platform requirements for Apple Pay or Google Pay. You cannot make that WebView wallet-capable from Stripe.js. The robust flow is:

1. Treat onAvailablePaymentMethodsChange as the source of truth and hide the Express Checkout region when no methods are returned.
2. Keep Payment Element/card as the fallback.
3. Optionally show “Open in Safari/Chrome to use Apple Pay/Google Pay” for an in-app browser. UA detection should only drive that explanation/open-browser UX, not decide wallet availability.

For the “Unhandled ... confirm event” error, first make sure the Express Checkout Element is not being remounted between render and confirm (changing key, conditional Elements providers, or recreating options/clientSecret can do this) and that onConfirm is present on every render. Keep the handler stable and return/await stripe.confirmPayment(...).

If those are stable and it occurs only while the WebView is being torn down, it is likely an SDK/WebView race rather than an error your handler can catch. Capture Stripe.js version, iOS/FB version, UA, and a minimal reproduction and report it to Stripe support; a global unhandledrejection suppressor would hide unrelated payment failures and is not a safe workaround.