Load the Klarna web SDK in your own iframe

Configure your checkout when it loads the Klarna web SDK inside an iframe that you own, so the Klarna Purchase Journey can resize, redirect, and return correctly.

4 min read

Overview

Use this guide if your own checkout loads the Klarna web SDK inside an iframe that you control, for example a payment-method frame served from a separate origin inside your Hosted Checkout page. You own both the page with the iframe element and the document inside it, so every step on this page is yours.

Warning

Klarna recommends loading the Klarna web SDK in your top-level Hosted Checkout page, as described in Payment Presentation for Hosted Checkout integration. Framing Klarna is supported as a last resort when your checkout architecture can't load it at the top level. The iframe adds browser restrictions that the Klarna Purchase Journey has to work around, which lowers conversion.

If Partners also load your Hosted Checkout page inside their own iframe, follow Allow Partners to load your Hosted Checkout in an iframe as well.

What the customer experience must support

The four behaviors are the same as when a Partner frames your checkout: a redirect launch, the journey running inside the iframe, a fullscreen backdrop, and the checkout page URL for fraud assessment. The difference is that your own top-level page performs the resize and the navigation. See What the customer experience must support.

Configure the iframe and both pages

Apply the configuration in Iframe attributes to both sides:

On your top-level page: the iframe sandbox tokens and allow directives, Permissions-Policy, your framed origin in frame-src, and Cross-Origin-Opener-Policy: same-origin-allow-popups if you send that header. Browsers only apply Cross-Origin-Opener-Policy to the top-level page.
On your framed document: Content-Security-Policy, and frame-ancestors listing your top-level origin. Browsers check frame-ancestors against every page above the frame, not only its direct parent, so if Partners can frame your top-level page, list their origins too.

Serve the framed document from the same origin as your top-level page when you can. It keeps cookies and storage first-party, so browsers don't partition them.

Register the origin that loads the Klarna web SDK

Klarna checks the origin of the document that loads the Klarna web SDK against your allowed client origins. Here that's your framed document's origin. Register it, even if it differs from your top-level page origin.

When the two origins differ, send your top-level page URL as the first point_of_transaction.referrers entry when calling authorizePayment API

. If a Partner frames your top-level page, send the Partner's page URL instead, as described in Send the Partner page URL to Klarna.

Resize the iframe and handle redirects

Use the same postMessage handshake that a Partner uses around your framed checkout, with your own top-level page in the Partner's role:

In the framed document, register klarna.Payment.on("overlayopen", callback) and klarna.Payment.on("overlayclose", callback), and the same pair on klarna.Messaging when you mount messaging placements. Post klarna:flow-open from the open handler and klarna:flow-close from the close handler, as in Resize the iframe.
In the framed document, register klarna.Payment.on("redirect", callback), relay redirectUrl with klarna:flow-redirect, and resolve false, as in Handle redirects.
If a Partner frames your top-level page, that page is no longer top-level and can't navigate the browser itself. On klarna:flow-open and klarna:flow-close, resize your own iframe and forward the same message to the Partner's page. On klarna:flow-redirect, forward the message unchanged. The Partner's page runs the Partner handlers, validating your top-level page's origin.
On your top-level page, add the resize handler and the redirect handler. Validate your framed document's origin, and allow Klarna hosts plus your own returnUrl origin as redirect destinations.

Test the framed integration

Run the customer journey checks in the framed checkout tests, with your own top-level page in the Partner's role. In each check, also confirm that:

The framed document loads with the CSP and frame-ancestors headers, and your top-level page sends Cross-Origin-Opener-Policy: same-origin-allow-popups or no Cross-Origin-Opener-Policy header.
The Klarna pop-up can open and isn't restricted by the iframe sandbox.
Your top-level page expands and restores the iframe, and navigates the top-level page on klarna:flow-redirect.
Redirects to anything other than an HTTPS Klarna origin or your return URL origin are rejected.

Next steps

Payment Presentation for Hosted Checkout integration

Allow Partners to load your Hosted Checkout in an iframe

Browser security configuration for the Klarna web SDK

Manage allowed client origins for the Klarna Web SDK

Customer initiated Payment Authorization

Jump to section...