Build checkout form with Klarna WebSDK (Worldpay orchestrated)

Before you integrate, check that you meet the following prerequisites:

1. 1.
   Ensure that you have Klarna enabled with Worldpay.
2. 2.
   Confirm you have access to the Klarna Partner Portal.
3. 3.
   Inside Klarna Partner Portal:

   1. 3.1.
      Confirm that you have generated a client identifier with your domain URL allowlisted.
4. 4.
   Add Terms and Conditions for Web SDK.

Here's an overview of all the steps to display Klarna and initiate payments via the Web SDK in the Worldpay-orchestrated flow:

1. 1.
   Initialize Klarna Web SDK and present Klarna as a payment option in your payment form.
2. 2.
   Customer clicks the Klarna payment button in your checkout.
3. 3.
   The initiate callback is triggered and the Klarna Web SDK provides a klarna_network_session_token to your client.
4. 4.
   You forward the klarna_network_session_token together with the purchase details to Worldpay to create the payment session.
5. 5.
   If customer authentication is required, Worldpay returns a payment_request_id:

   • 5.1.
     Return the payment_request_id from the initiate callback so the Klarna Web SDK launches the Klarna Purchase Journey.
   • 5.2.
     The customer completes the Klarna Purchase Journey.
6. 6.
   Worldpay notifies you when the order is completed.
7. 7.
   You redirect the customer to your confirmation page.

Presenting Klarna in the payment form involves retrieving the visual assets, localized text, and display instructions required to correctly render Klarna as a payment option and display the payment button. This dynamic presentation ensures a consistent customer experience, accurate localization, and optimized conversion performance, while adapting seamlessly to different checkout states.

On a high level, the process involves:

1. 1.
   Initialize Klarna Web SDK in your checkout experience.
2. 2.
   Request Klarna’s payment presentation for the current payment context.
3. 3.
   Render Klarna payment option(s) dynamically in the payment form according to the instructions.
4. 4.
   Allow the customer to select and deselect a Klarna payment option.
5. 5.
   Display the Klarna button and start the payment process when clicked.

The expected outcomes are as follows:

Initial presentation	When Klarna is selected

The Klarna Web SDK (klarna.mjs) follows the JavaScript module approach and should be included in places where you need to have a reference to the SDK such as while rendering any components or initiating a payment flow. Here are the initialization parameters:

For the full API specifications, refer to Klarna Web SDK. SDK initialization sample

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

  const Klarna = await KlarnaSDK({
    clientId: "[client-id]",
    products: ["PAYMENT"],
    locale: "en-US", // optional
  })

  // Klarna SDK ready to be utilized
  // Klarna.Payment.button().mount('#payment_container')
</script>

Klarna payment presentation provides all the visual assets, localized texts, and instructions needed to correctly display Klarna in your checkout form.

Use the initialized SDK instance to call the Klarna.Payment.presentation() method.

Basic checkout context parameters must be provided:

For the full API specifications, refer to Klarna Web SDK.

Sample code

const paymentPresentation = await klarna.Payment.presentation({
  amount: 11800,
  currency: "USD",
  locale: "en-US",
  intents: ["PAY"]
});

The PaymentPresentation interface provides the full Klarna branding package and instructions tailored to the customer's purchase:

The paymentOption object structure is as follows:

For the full API specifications, refer to Klarna Web SDK.

This section describes how to apply Klarna’s payment presentation instructions, which define how Klarna should appear in your checkout. Following these instructions ensures a consistent experience across payment states and is required for features like Klarna Express Checkout and Sign in with Klarna.

The instruction attribute has the following values:

For the full API specifications, refer to Klarna Web SDK.

Here are example outcomes illustrating how Klarna should be displayed for each instruction:

Show Klarna	Preselect Klarna	Show only Klarna

The presentation instructions are derived from possible customer purchase journeys described in the How to present Klarna article. Sample code:

function renderKlarna(paymentPresentation) {
  if (!paymentPresentation) return;

  const root = qs("#klarna-payment-method");
  if (!root) {
    console.error("Missing #klarna-payment-method container.");
    return;
  }

  root.innerHTML = `<div id="klarna-option-default" class="klarna-option default" style="display:none;">
</div>
`;

Once an instance of PaymentPresentation is created, the Klarna payment option(s) must be rendered dynamically in the payment selector according to Klarna’s presentation guidelines. The following diagram displays different visual components and how they are rendered in different selection states:

1. 1.
   Icon
2. 2.
   Badge
3. 3.
   Header
4. 4.
   Subheader
5. 5.
   Message
6. 6.
   Terms
7. 7.
   Button

Mount the Klarna payment option components within your designated Klarna payment method container to render them dynamically in the payment form. Ensure that all components—including those not immediately visible—are mounted during initialization, and manage their visibility through your own logic or UI controls.

function renderKlarnaOption(containerId, option) {
  const container = qs(`#${containerId}`);
  if (!container) {
    console.error(`Missing #${containerId} container.`);
    return;
  }

  const ids = {
    icon:    `${containerId}-icon`,
    header:  `${containerId}-header`,
    subhdr:  `${containerId}-subheader`,
    badge:   `${containerId}-badge`,

When a Klarna payment option is selected/deselected, ensure the additional visual components are shown/hidden properly.

/**
 * Toggle the Klarna payment option selected state.
 * Use for both SDK preselection (PRESELECT_KLARNA) and user interactions.
 */
function toggleKlarnaPaymentOptionSelection(containerId, isSelected) {
  const container = qs(`#${containerId}`);
  if (!container) {
    console.error(`Missing container #${containerId}.`);
    return;
  }

  const display = isSelected ? "block" : "none";

The payment presentation instance allows you to mount the prebuilt button component. The Klarna Payment Button is context-aware and dynamically adapts to your configuration.

[ Klarna payment button variants]

Choose the theme and shape of the payment button to best fit into your online store in a way that complements your brand and encourages user engagement. More details on the button styling can be found here.

[ Configure Klarna payment button]

The paymentButton.component() can be configured with the following set of parameters:

For the full API specifications, refer to Klarna Web SDK.

Sample code

option
  .paymentButton
  .component({
    id: "klarna-payment-button",  // optional test hook
    shape: "pill",                // "default" | "pill" | "rect"
    theme: "default",             // "default" | "light" | "dark" | "outlined"
    intents: ["PAY"],
    initiationMode: "DEVICE_BEST", // "DEVICE_BEST" | "ON_PAGE" | "REDIRECT"
    initiate: (klarnaNetworkSessionToken, paymentOptionId) => initiateKlarnaPayment(klarnaNetworkSessionToken, paymentOptionId)
  })
  .mount(`#${containerId}-payment-button`);

In this flow, you don’t call Klarna’s Payment Request API directly. Instead, the initiate callback receives a klarnaNetworkSessionToken from the Klarna Web SDK. You forward this token to Worldpay together with the purchase details, and Worldpay performs the authorization with Klarna on your behalf.

The callback must return one of the following to the Web SDK:

Client code

const klarnaPaymentButton = klarna.Payment.button({
  initiate: async (klarnaNetworkSessionToken, paymentOptionId) => {
    const resp = await fetch('/create-payment-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        klarnaNetworkSessionToken,
        paymentOptionId,
        /* amount, currency, and purchase details */
      })
    });

Server code

Your server endpoint forwards the klarna_network_session_token to Worldpay. Worldpay then calls Klarna’s Payment Authorize API and returns either an approval or a STEP_UP_REQUIRED response containing a payment_request_id.

// Server.js
// Simplified backend example: forward the Klarna token to [acquiring-partner]

const axios = require('axios');

const ACQUIRING_PARTNER_API_KEY = 'YOUR_API_KEY';
const ACQUIRING_PARTNER_BASE_URL = 'https://api.acquiring-partner.com';

async function createPaymentSession({ klarnaNetworkSessionToken, paymentOptionId, order }) {
  const url = `${ACQUIRING_PARTNER_BASE_URL}/payment`;
  const payload = {
    amount: order.amount,

For the full request/response schema, consult Worldpay’s API reference.

If Worldpay returns STEP_UP_REQUIRED with a payment_request_id, return { paymentRequestId } from the initiate callback. The Klarna Web SDK launches the Klarna Purchase Journey, the customer completes the authentication, and Worldpay notifies you of the final result.

You don’t need to subscribe to Klarna webhooks or monitor the Klarna payment request lifecycle yourself — Worldpay handles these on your behalf.

Once the payment is authorized — either directly or after a successful step-up — Worldpay notifies you that the order is completed. Display the confirmation page to the customer based on Worldpay’s notification.

In rare cases where there’s a discrepancy between the amount and purchase details submitted by the Klarna Web SDK and the information submitted to Worldpay, the authorization may be rejected and the customer asked to approve the purchase again through the step-up journey.