API and SDKsSupport
WebSDK Best practices

Integrate Klarna’s Web SDK using best practices for loading and payment initiation to ensure seamless checkout and avoid issues like popup blocks across devices.

This page outlines best practices for integrating the Klarna Web SDK, helping Partners and Acquiring Partners deliver a seamless, secure, and high-performing checkout experience. It covers essential guidance on SDK loading, initialization, and payment flow configuration. Following these recommendations ensures interoperability, improves customer experience, and supports successful implementation across all integration types.

Do

Load the script directly from the official source. This ensures you automatically receive the latest security and bug fixes for the SDK.

JAVASCRIPT
<script type="module">
  const { KlarnaSDK } = await import("https://js.klarna.com/web-sdk/v2/klarna.mjs");

  const Klarna = await KlarnaSDK({
    clientId: "[client-id]",
    partnerAccountId: "[partner-account-id]",
  });
</script>
Don't

Include the script url in the src attribute of a script tag. Klarna SDK does not support global exports to mitigate conflict between multiple instances.

JAVASCRIPT
// Wrong integration pattern
<script type="module" src="https://js.klarna.com/web-sdk/v2/klarna.mjs"></script>
Don't
  • Include the Web SDK script in your own bundle or host it on your server. This practice can lead to using outdated versions and missing important updates and fixes.
  • Embed the Web SDK within an iframe. This can interfere with its proper functioning, leading to unexpected behavior. For example, payment backdrops will not be displayed, popups can be blocked due to browser restrictions on iframe elements, all leading to poor user experience.
JAVASCRIPT
// Wrong integration pattern
<iframe src="https://payment-provider-iframe.merchantdomain.com"></iframe>

// payment-provider-iframe.merchantdomain.com
<script type="module">
  const { KlarnaSDK } = await import("https://js.klarna.com/web-sdk/v2/klarna.mjs");
</script>
Don't

Do not run asynchronous requests before triggering the payment initiation flow when using a custom button click handler. Delays between the click and popup trigger can cause the browser to block the Klarna payment popup, as it must open immediately after a user interaction.

Instead, use the callback provided in Klarna.Payment.initiate() to handle any asynchronous logic before launching the popup safely.

JAVASCRIPT
<script type="module">
  const { KlarnaSDK } = await import("https://js.klarna.com/web-sdk/v2/klarna.mjs");
  const Klarna = await KlarnaSDK({
    clientId: "[client-id]",
    partnerAccountId: "[partner-account-id]",
  });

  // Wrong integration pattern
  const customButtonElement = document.getElementById("payment-button");
  customButtonElement.addEventListener("click", async (event) => {
Do

Configure payment initiation directly within the button configuration when using paymentRequest or authorize.

JAVASCRIPT
Klarna.Payment.button({
  // Button configuration
})
Don't

Call Klarna.Payment.initiate() or Klarna.Payment.authorize() within the Klarna.Payment.on() function if you have already used paymentRequest or authorize in the button configuration. The button handles the payment flow when clicked, making redundant calls unnecessary and conflicting.

JAVASCRIPT
Klarna.Payment.button({
 id: "klarna-payment-button",
 locale: "en-US",
 shape: "pill",
 label: "Pay",
 theme: "default",
 paymentRequest: { data: "<client_secret>" | PaymentRequestData | () => {
   // call to their server to create a payment request 
   return "<client_secret>" | PaymentRequestData;
 }, options: {
Do

Use the initiationMode: DEVICE_BEST to trigger the Klarna pop up. The SDK will automatically selects the best way to launch the Klarna Purchase Journey depending on the device - this is the default and recommended value:

  • Mobile: Always redirect.
  • Desktop: pop-up if possible, fallback to redirect.
  • Native webview: Always redirect.
JAVASCRIPT
<script type="module">
  const { KlarnaSDK } = await import("https://js.klarna.com/web-sdk/v2/klarna.mjs");

  const Klarna = await KlarnaSDK({
    clientId: "[client-id]",
    partnerAccountId: "[partner-account-id]",
  });

  const paymentPresentation = await klarna.Payment.presentation({
    amount: 1000,
Don't

Use the initiationMode “ON_PAGE” in a mobile environment because the Klarna pop up could be blocked.