With this integration path, Partners are presenting a payment form generated by the Acquiring Partners:

• Customers are either redirected to a hosted checkout page or a checkout element embedded in the Partner website via a JavaScript library.
• Acquiring Partners must use Klarna's SDK to dynamically retrieve payment presentation assets (headers, icons, subheaders, button and instructions) and build the payment form.
• Klarna’s SDK keeps all elements up-to-date and optimized for the best conversion.

The following diagram gives an overview of the customer journey and the Acquiring Partner workflow.

On a high level, building the payment form requires the following actions:

• Accept interoperability_token in your checkout session API and JavaScript library.
• Accept interoperability_data in your checkout session API (server-side only).
• Forward both interoperability data points to Klarna exactly as received — do not modify.
• If interoperability_token is provided, exchange it server-side for an sdk_token.
• Load the Klarna SDK from the official URL — never bundle or self-host.
• Initialize the SDK with clientId, partnerAccountId, sdkToken, products and locale.
• Use Klarna.Payment.presentation() SDK method to dynamically retrieve personalized assets to build the payment selector
• Never hardcode Klarna logos, texts, or layout — always render via SDK components.
• Always follow the returned instruction (e.g., show, preselect Klarna).
• Mount the Payment Button only after Klarna is selected or preselected.

Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include interoperability parameters that preserve session context as well as supplementary purchase data which improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience.

Interoperability parameters

When Partners optimize their integration with Klarna, they are likely to have interoperability parameters to share with the Acquiring Partner.

These ensure consistent customer and transaction context throughout the payment flow and must be forwarded unaltered to Klarna.

Implementation requirements

• Accept the interoperability parameters in the Partner-facing payment request API.
• Forward the interoperability parameters unmodified to Klarna’s Payment Authorization API.
• Validation can and should be implemented, but it must not be more restrictive than what is specified in Klarna’s Payment Authorize API. Make sure that all special characters permitted by the API specification are accepted.

Sample request

Below are some examples of how Acquiring Partners can accept the interoperability parameters:

Supplementary Purchase Data

Supplementary purchase data improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience. It includes structured information such as line items, L2/L3 data for Card Network optimization and other transaction context.
Acquiring Partners may receive this data from the Partner in two ways:

1. Embedded in interoperability_data
   1. No parsing needed. Just forward it as-is.
2. As individual fields in the Acquiring Partner’s API
   1. The Acquiring Partner is responsible for mapping existing fields in their payment API with the fields defined in the supplementary_purchase_data object when calling the Payment Authorize API.

​

Read more about Supplementary Purchase Data here.

Request

To determine whether the payment should be fast-tracked, the Acquiring Partner should call our backend Payment Presentation API and verify the payment_status. Basic checkout context parameters must be provided:

Sample request payload:

{
  "amount": 11800,
  "currency": "USD",
  "locale": "en-US",
  "intents": ["SUBSCRIBE"], // optional, other values: "PAY" || "SIGNUP" || "SIGNIN" || "DONATE" || "ADD_TO_WALLET" 
}

Response

The PaymentPresentation interface provides the full Klarna branding package and instructions tailored to the customer's purchase. However, at this step, the only relevant information is payment_status.

Sample response payload:

{
  ...
  "payment_status": "REQUIRES_CUSTOMER_ACTION",
  ...
}

To integrate Klarna as a payment method into their payment form, the Acquiring Partner must initialize Klarna’s Web SDK using specific credentials and tokens.

Exchange the interoperability_token for an sdk_token

If a Partner provides an interoperability_token, the Acquiring Partner must exchange it for a short-lived sdk_token using the Generate SDK Token API endpoint.

The sdk_token is a single-use, browser-bound credential that restores the customer’s checkout context when Klarna’s Web SDK is loaded. This token should be exchanged server-side before initializing the SDK and displaying the checkout page to the customer.

Initialize the Klarna Web SDK

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. Always load the Web SDK from https://js.klarna.com/web-sdk/v2/klarna.mjs to remain compliant. Don’t include the script in a bundle or host it yourself.

SDK initialization sample

const klarna = await KlarnaSDK({
  clientId: "klarna_test_client_***",
  products: ["PAYMENT"],
  partnerAccountId: "krn:partner:global:account:***",
  sdkToken: "rxvqGi07j...", // retrieved from server
  locale: "en-US" // optional but recommended
});

// sdkToken can also be set after SDK initiation  
// klarna.Config.setSdkToken("rxvqGi07j...")

After initialization, the Klarna SDK instance is ready to retrieve payment presentation data and manage the checkout flow. For the full API specifications, refer to Klarna Web SDK.

This step describes how Klarna should be presented in the payment form initially as well as when it's selected by the customer. The expected outcomes are as followed:

Initial presentation	When Klarna is selected

It's crucial that Klarna payment presentation is dynamic and not hardcoded on your server to deliver the best conversion outcome.

Depending on your architecture and the level of performance optimization, you can choose one of the following options:

• Option 1: Standard Klarna Web SDK integration
• Option 2: Optimized integration with additional caching mechanism

Option 1: Standard Klarna Web SDK integration

Klarna payment presentation request

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:

Sample request payload:

Klarna payment presentation response

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

Follow Klarna payment presentation instruction

Following Klarna payment presentation instruction ensure consistent customer experience when the Partner is integrating with Klarna Conversion Boost features. The instruction attribute from the PaymentPresentation instance informs how Klarna should be displayed in the payment form:

The presentation instructions indicate Acquiring Partners how Klarna should be presented in the payment selector. Acquiring Partners are required to adhere to Klarna’s payment presentation instruction to achieve the best-in-class user experience.

Show Klarna	Preselect Klarna	Show only Klarna	Hide Klarna

The presentation instructions are derived from possible customer purchase journeys described in the following article.

Sample code:

if (paymentPresentation) {
  switch (paymentPresentation.instruction) {
    case "SHOW_KLARNA":
      console.log("Showing Klarna alongside other payment methods.");
      renderKlarnaOption(paymentPresentation);
      break;
    case "PRESELECT_KLARNA":
      console.log("Showing Klarna preselected alongside other payment methods.");
      renderKlarnaOption(paymentPresentation);
      break;

Display Klarna in the payment selector

Once an instance of PaymentPresentation is created, the Acquiring Partner must dynamically render Klarna payment option in the payment selector according to Klarna’s presentation guidelines.

The following attributes from PaymentPresentation instance will be used when loading the payment selector initially:

1. Icon
2. Header
3. Subheader

Mount Klarna payment presentation icon, header and subheader to your Klarna payment method container to render the elements dynamically in your payment form.

function renderKlarnaOption(paymentPresentation) {
  const klarnaContainer = document.getElementById("klarna-option");

  if (!klarnaContainer) {
    console.error("Klarna container missing.");
    return;
  }

  // Clear the container first
  klarnaContainer.innerHTML = `

Handle Klarna payment method selection

After the customer selects Klarna in the payment selector (or if Klarna was pre-selected according to presentation instructions), the next step is to show:

• The Message (more detailed messaging tailored to the customer and transaction).
• The Payment Button (to trigger Klarna’s Purchase Journey).

This step finalizes the presentation of Klarna's payment method before the customer proceeds to payment authorization.

1. Icon
2. Header
3. Subheader
4. Message
5. Payment Button

The remaining attributes from PaymentPresentation instance will be used when loading the payment selector:

Display additional messaging

paymentPresentation
  .message
  .component()
  .mount("#klarna-message-container");

Display Klarna payment button

The payment presentation instance allows you to either mount the prebuilt button component or retrieve the button text asset. 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.

Mount Klarna payment button

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

Sample code

paymentPresentation
  .paymentButton
  .component({
    id: "klarna-payment-button",       // unique button/component ID
    shape: "pill",                     // "pill", "default", or "rect"
    theme: "default",                  // "default", "dark", "light", or "outlined"
    intents: ["PAY"],                  // defines payment intent, e.g., "PAY"
    initiationMode: "DEVICE_BEST",     // "DEVICE_BEST", "ON_PAGE", or "REDIRECT"
    initiate: () => {
      /**