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.

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.

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 both interoperability parameters in the Partner-facing checkout session API.
• Accept interoperability_token in client side javascript library.
  • interoperability_data should NOT be exposed client-side.
• Forward the interoperability parameters unmodified to Klarna’s Payment Authorization API.

Sample request

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

Parameter validation guidelines

As those parameters can change over time and are versioned so that the third party integration continues to work, Acquiring Partners need to respect these guidelines if they wish to validate parameters:

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.

When an interoperability_token is present, there are cases where the Partner has integrated with Klarna Express Checkout and the customer has already approved the payment. In this scenario, displaying the payment selector again results in a suboptimal user experience. Therefore, if the context allows the payment selector to be skipped, the Acquiring Partner must expedite the Klarna payment process and proceed directly to authorization.

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": ["PAY"], // optional, other values: "SUBSCRIBE" ||"SIGNUP" || "SIGNIN" || "DONATE" 
}

Read payment presentation 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:

{
  "instruction": "SHOW_KLARNA",
  "payment_status": "REQUIRES_CUSTOMER_ACTION",
  "payment_button": {
    "text": "Pay with Klarna"
  },
  "icon": {
    "badge_image_url": "https://s3.int.klarna.net/pre-purchase/library/global/images/badges/klarna_v2.svg",
    "rectangle_image_url": "https://s3.int.klarna.net/pre-purchase/library/global/images/badges/klarna_badge_rectangle.svg",
    "square_image_url": "https://s3.int.klarna.net/pre-purchase/library/global/images/badges/klarna_badge_square.svg",

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.

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

• The sdk_token is a single-use, browser-bound credential.
• It restores the customer's checkout context when loading Klarna’s Web SDK.
• The exchange should happen server-side before initializing the SDK and rendering the checkout page.

The Klarna Web SDK (klarna.mjs) follows 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

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 code

var paymentPresentation = await klarna.Payment.presentation({
  amount: 11800,
  currency: "USD",
  locale: "en-US",
  intents: ["PAY"], // optional, other values: "SUBSCRIBE" ||"SIGNUP" || "SIGNIN" || "DONATE" 
});

Read payment presentation response

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

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

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;

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 = `

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:

Mount additional messaging

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

Render 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.

Create a button configuration object

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

Sample code

const buttonConfig = {
  shape: "pill",        // Button shape ("pill", "rectangle", etc.)
  theme: "dark",        // Theme ("dark", "light", etc.)
  initiate: async () => {
    const response = await fetch('/your-api/create-payment');
    return await response.json();
  },
  initiationMode: "DEVICE_BEST",  // Device-optimized payment initiation
};

Render the payment button into the DOM

Finally, mount the button inside the appropriate container:

paymentPresentation
  .paymentButton
  .component(buttonConfig)
  .mount("#klarna-button-container");

• 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.