Skip to content
Swingback, home

BlogEngineering

Stripe customer portal in an iframe: what to build instead

Stripe's customer portal can't be framed. Redirect to it, or rebuild its pages on Stripe's API, with the pitfalls of checkout, invoices, switches and wallets.

By Elie Baier · · Updated · 5 min read

You can't put Stripe's customer portal in an iframe. Stripe's documentation says so in one line, and the portal's pages back it up: billing.stripe.com answers with frame-ancestors 'none', so the browser shows an empty frame or an error, whatever your own page allows. You have two ways out: send people to the portal and bring them back, or build its pages yourself on Stripe's API. I wanted owners to pay and manage billing without leaving the dashboard, so I built the second. This post weighs what each takes, and what Stripe's docs don't warn you about.

Why the frame stays empty#

A page decides who may frame it, and Stripe's portal allows nobody. That's deliberate: a page that handles cards and cancellations is exactly what clickjacking goes after. Stripe's hosted Checkout page behaves the same way.

There is no embeddable component for it either. Stripe's embedded components are Connect's, for a platform and its connected accounts, not for a business billing its own customers. What Stripe does let you embed is payment: Embedded Checkout (Stripe's whole form in a frame on your page) or the Payment Element (its fields inside your own form).

Option 1: redirect, and come back#

For most products, this is the right answer. Your server creates a portal session for the customer, and the browser goes there:

TypeScript
// The owner clicked "Manage billing".
const session = await stripe.billingPortal.sessions.create({
  customer: workspace.stripeCustomerId,
  return_url: "https://app.example.com/settings/billing",
});
return Response.redirect(session.url, 303);

Stripe keeps the pages up to date, translated and accessible, and you write a dozen lines. The cost is the trip: a new look, a new address, and a "Return to…" link people don't always find.

Option 2: the portal's pages, on Stripe's API#

Everything the portal does is in the API. Here is the map I worked from:

What the portal doesWhat to call
Subscribe and payA Checkout Session with ui_mode: "elements", its Payment Element mounted by Stripe.js on your page
List the invoicesThe customer's invoices, read when the page is shown
Replace the cardA SetupIntent, confirmed by Stripe.js, then made the customer's and the subscription's default
Switch monthly ↔ yearlyPOST /v1/invoices/create_preview, then the subscription's update
Cancel and resumecancel_at_period_end on the subscription
Billing detailsThe customer's email, name, address, tax IDs and preferred_locales

In elements mode, the session stays a Checkout Session: Stripe still makes the subscription, sends the same webhook, and handles 3-D Secure. The difference is that the form is in your page, in your styles. On the client, Stripe.js builds the fields from the session's client secret and confirms there:

TypeScript
const checkout = stripe.initCheckoutElementsSdk({ clientSecret });
checkout.createPaymentElement().mount("#payment");
const { actions } = await checkout.loadActions(); // check its `type` for an error first

// The owner pressed "Pay".
const result = await actions.confirm({ redirect: "if_required" });

redirect: "if_required" keeps the page where it is unless a payment method has to leave it, so no secret ends up in an address. Client secrets are the only Stripe values besides the publishable key that the browser holds, and each confirms one session or intent and nothing else.

What Stripe's docs don't warn you about#

Each of these came up while I built it, most of them in Stripe's sandbox.

Two tabs make two subscriptions. Hosted Checkout has the same hole: a reload, a double click or two owners at once each start a session, and each can be paid. So creating one takes a lock on the workspace, lists the customer's open sessions at Stripe, reuses the open session for the same price, and expires the others. Expiring a session that was paid in the meantime fails, and that failure tells you to read its subscription.

Don't wait for the webhook to show the plan. It usually arrives within seconds, and the page after a payment loads faster than that. After confirm, the server reads the session and its subscription from Stripe, as the webhook's job would, under the same lock. The webhook stays the source of truth. When it arrives, there's nothing left for it to change.

Invoice links expire. An invoice's invoice_pdf and hosted_invoice_url need no sign-in, and Stripe expires them 30 days after the invoice is due (120 days at most). Store the invoice's id, never its links. The dashboard's invoice page links a route of its own, which asks Stripe for the invoice when the link is followed and redirects to the PDF.

A 402 is an answer, not an error. Paying an open invoice answers 402 both for a decline and for a payment the bank wants to confirm (invoice_payment_intent_requires_action). Turn both into outcomes: succeeded, requires action (with a client secret for Stripe.js), or failed (with the decline code). And send no idempotency key of your own: retried with a new card, a key would get the first attempt's 402 back. Stripe never pays an invoice twice anyway.

A switch that isn't paid shouldn't apply. Update the subscription with payment_behavior: "pending_if_incomplete". Paid at once, the switch applies. Otherwise Stripe keeps it in the subscription's pending_update, a declined card included, which in my sandbox came back without a 402. The switch then waits on its open invoice: paid later, it applies. Left unpaid, Stripe voids the invoice and drops the switch after 23 hours, or sooner if the trial or the current period ends first. One more case: before you cancel a subscription with a switch pending, void that invoice yourself. Paid later, it would start a new period for a subscription that is ending.

Preview and switch can't share a proration date. The natural plan is to preview with a proration_date and switch with the same one, so the charge equals the preview. But a monthly-to-yearly switch needs billing_cycle_anchor=now to start its year at once: in flexible billing mode, the default from API version 2025-09-30.clover, a new interval keeps the old anchor. And with it, Stripe refuses the date: "You cannot specify proration_date when billing_cycle_anchor=now". So each prorates when it's made, and the two differ by what the seconds between them are worth. In the sandbox that was nothing, to the cent.

Wallets need your domain registered. Hosted pages get wallets for free. In your page, Stripe shows Apple Pay and Google Pay only on a registered payment method domain, over HTTPS, so never on localhost. In my tests on desktop, the Payment Element offered Apple Pay only in Safari and Google Pay only in Chrome. The Express Checkout Element, with Apple Pay set to always, offers it in other desktop browsers too (Stripe's table lists them), where the owner confirms on their iPhone. That opens Apple's window, which talks to your page by postMessage, so an opener policy of same-origin leaves it spinning. The billing pages need same-origin-allow-popups.

Resuming has two shapes. A subscription canceled through the dashboard has cancel_at_period_end set. One that Stripe's own portal canceled may carry a cancel_at date instead. Resuming clears whichever is set.

When it's worth it#

It's more code than a redirect, and you take on what Stripe did for you: the pages' words, their states, tests against a fake Stripe.js, and a check against Stripe's sandbox for what a fake can't prove. If owners visit billing twice a year, keep the redirect.

I rebuilt it because paying is the first thing a new workspace does, and a trip to another site at that moment loses people. Keep a way back, though: without JavaScript, or when Stripe.js doesn't load, the dashboard still offers Stripe's own page.

In Swingback, owners pay and manage the subscription under Settings → Billing: the card, the invoices, switching and canceling. Plans and billing says what each does.