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 an example of how Acquiring Partners can accept the interoperability parameters in their Payment request API endpoint.

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.

Tokenization-specific supplementary purchase data

Payment Authorize

Copied

POST:/v2/accounts/{partner_account_id}/payment/authorize

Path ParametersRequest Body

Show recommended

Parameter	Required	Description
Copied partner_account_id	Yes	Unique account identifier assigned by Klarna to the onboarded merchant

Here you can find all required parameters for this operation authorizePayment

Before presenting the payment form, if an interoperability_token was shared by the Partner, the Acquiring Partner must check if Klarna payment should be fast-tracked. This typically happens when the Partner implements Klarna boost features such as Klarna Express Checkout and the customer has given the approval for payment.

Payment presentation request

Call the Payment Presentation API with interoperability_token and purchase details to evaluate if the payment could be fast-tracked.

Payment Presentation

Copied

GET:/v2/accounts/{partner_account_id}/payment/presentation

Request Headers

Show recommended

Parameter	Required	Description

Here you can find all required parameters for this operation getPresentationAPI

<br />Sample request:

curl -G 'https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/presentation' \ 
     --header 'Authorization: Basic <API key>' \ 
     --header 'Klarna-Interoperability-Token: eyJhbGciOiJIU...' \ 
     --data-urlencode 'locale=en-US' \ 
     --data-urlencode 'amount=11836' \ 
     --data-urlencode 'currency=USD' \ 
     --data-urlencode 'intents[]=SUBSCRIBE'

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:
{
...
"payment_status": "PENDING_PARTNER_AUTHORIZATION",
...
}

Using Klarna Web SDK, you can:

• Display Klarna dynamically alongside other payment options in your payment form.
• Embed Klarna’s UI elements directly in your frontend for a consistent and responsive design.
• Manage the interaction flow while offloading the rendering and logic to Klarna’s SDK.

Exchange the customer_token and/or interoperability_token for an sdk_token

The Acquiring Partner must exchange the acquired customer_token for a short-lived sdk_token using the Generate SDK Token API endpoint. If an interoperability_token was passed by the Partner in the charge call, both tokens should be used for the exchange.

Interoperability

Copied

POST:/v2/interoperability/sdk-tokens

Request Headers

Show recommended

Parameter	Required	Description
Copied Klarna-Interoperability-Token	Yes	The interoperability token enables continuity of customer journey across domains and services. If you are an Acquiring Partner, you receive this token from your merchant.

Here you can find all required parameters for this operation generateSdkToken

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. Here are the initialization parameters:

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

Sample code

Klarna payment presentation response

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.

Follow Klarna payment presentation instruction

This section explains how to handle Klarna’s payment presentation instructions, which define how Klarna should appear within the checkout form.

Adhering to these instructions is essential to maintain a consistent and optimized user experience—whether Klarna is displayed alongside other payment methods, preselected, or shown as the only available option.

Compliance with Klarna’s presentation instructions is especially important when integrating Klarna Conversion Boost features, such as Express Checkout or Sign in with Klarna, to ensure a seamless and unified customer experience.

The instruction attribute has the following values:

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: () => initiateKlarnaPayment()
  })