With this integration path, Partners are presenting a payment form generated by the Acquiring Partners, whether by redirecting their customers to a hosted checkout page from the Acquiring Partner or using a javascript library from the Acquiring Partners to load an embedded element containing the checkout form.

The Acquiring Partner in this case owns the payment selector displayed in the checkout form and must follow the Klarna Payment Presentation requirements when adding Klarna. To include Klarna in the payment selector, Acquiring Partners must dynamically retrieve payment presentation assets from Klarna. Klarna provides SDKs to ensure all components are up-to-date and optimized for conversion.

By leveraging Klarna’s SDK, Acquiring Partners automate the retrieval of Klarna elements, reducing manual updates and ensuring compliance with Klarna’s branding guidelines. A correctly implemented Klarna integration enhances trust and scalability, minimizes friction, and improves conversion rates by providing a clear, predictable, and intuitive checkout flow.

In this type of integration, usually the Partner starts by creating a checkout session with the Acquiring Partner’s API when the customer decides to proceed to the checkout page. The Partner may then either use some type of secret to load a specific element, or redirect the customer to a hosted experience.

It is required to receive certain data points from the Partner to ensure a full end-to-end integration between the Partner's checkout flow and Klarna's Purchase Journey. Acquiring Partners must accept these data points in their respective API endpoints and javascript library which allows their Partners to load an embedded checkout element or redirect to a hosted checkout page.

The interoperability data points (interoperability_token and interoperability_data) ensure all information and context associated with a payment transaction is preserved throughout the journey of a customer.

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

Acquiring Partners must accept the interoperability_token and interoperability_data parameters in their respective APIs in order to forward them when calling Klarna’s APIs:

• Klarna's interoperability_token and interoperability_data must be accepted through server-side API endpoints used to initiate the checkout session.
• In cases where Acquiring Partner offers checkout initiation flow using a client-side integration (e.g. javascript library), Acquiring Partner must also accept Klarna’s interoperability_token in client side methods. As Interoperability Data may contain information that should not be forwarded to the client-side, Acquiring Partners should not expose it on their Javascript libraries.

Below an example of how Acquiring Partners can accept the interoperability data points in their Checkout API endpoint.

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "interoperability_token": "...",
      "interoperability_data": "..."
    }
  }
}

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 consists of  datapoints associated with the payment that helps Klarna optimize the Purchase Journey and improve acceptance rate. These datapoints can be forwarded to Klarna through:

• The interoperability_data field mentioned previously
• The Acquiring Partner's own API

When Acquiring Partners allow Partners to provide additional data points directly through their APIs, such as line items or L2/L3 data for Card Network optimization, they must forward the same data to Klarna using supplementary_purchase_data object of the Payment Authorization API.

​Read more about Supplementary Purchase Data here.

To add Klarna as a payment method to the checkout form Acquiring Partners will have to integrate and use Klarna’s SDK. The SDK will be used to retrieve the presentation instruction, accurately display the Klarna to improve conversion and hand over the customer to the Klarna Purchase Journey.

To initialize the Klarna Web SDK, it is required to:

• Handover the interoperability status from the server to the client using the interoperability token
• Load the Web SDK Javascript Library
• Initialize the Web SDK with the appropriate credentials

Before proceeding with the loading and initialization of the Klarna SDK, the Acquiring Partner would need to request an SDK token in case their Partners provided an interoperability_token previously.

This step is mandatory as soon as an Interoperability Token was provided by the Partner, highlighting the Partner objective to improve their checkout experience by using Klarna's Product Suite. The exchange should be triggered when the embedded checkout element or hosted checkout page from the Acquiring Partner is loaded, as long as it is done before the payment selector is displayed to the customer.

Exchange the Interoperability Token for an SDK Token

The SDK Token is a Token that can be loaded on the client-side using the Web SDK and will restore on the customer browser the state they had when leaving the Partner's website. If the Acquiring Partner receives an interoperability_token from the Partner they must use it to request an sdk_token for SDK initiation.''

The sdk_token is short-lived, single-customer-use token that allows the Klarna SDK to resume a customer’s shopping journey based on the data encoded in the interoperability_token. Once loaded on a customer's browser through Klarna's SDK, it will only work on the same customer browser.

To retrieve a sdk_token, the Acquiring Partners must call the Create SDK token endpoints and pass the interoperability_token provided by the Partner as HTTP header in the request.

Below an example response body for the Create SDK token API endpoint.

{
  sdk_token: "rxvqGi07j..."
}

Loading and initialization of the Klarna SDK should be triggered when the embedded checkout element or hosted checkout page from the Acquiring Partner is loaded by the customer browser.
The Klarna SDK follows the JavaScript module approach and should be included in places where the Acquiring Partner needs to have a reference to the SDK such as rendering any components or initiating a payment flow.

To initiate the SDK, the Acquiring Partner will need the following credentials:

• clientId generated via the credentials API, this credential is linked to the Acquiring Partner and can be used across all onboarded Partners.
• partnerAccountId corresponding to the onboarded Partner.
• sdkToken requested by the Acquiring Partner using the interoperability_token provided by the Partner.

Sample code

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

const klarna = await KlarnaSDK({
  clientId: "klarna_test_client_RThZIWNpI...",
  partnerAccountId: "krn:partner:global:account:test:LZ4ARBQJ",
  sdkToken: "rxvqGi07j...",
  locale: "en-US"
})

// sdkToken can also be set after SDK initiation  

Now that the Web SDK is loaded and the customer state has been restored from the Partner's side, it is possible to retrieve the Payment Presentation element. It contains everything needed to add Klarna as an option to a payment form.

All required elements are properly contextualized with the purchase but also make sure it is personalized towards the customer. The Acquiring Partner first needs to get the payment presentation element using the Klarna.Payment.presentation() method.

The required parameters for this method are the currency, amount and locale for the ongoing checkout session:

Sample code:

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

The Payment Presentation element then exposes various methods to be called to respect Klarna's interoperability and render Klarna's assets. The paymentPresentation variable defined will then respect the following interface:

interface PaymentPresentation {
    header: { 
        component: (divID: string) => void; 
        text: string 
    };
    icon: { 
        alt: string; 
        imageUrl: string 
    };
    instruction: PaymentPresentationInstruction;

With the paymentPresentation element created, the Acquiring Partner must use the instruction attribute to dynamically build the payment selector. The instruction attribute will contain one of the following values:

• SHOW_KLARNA
• PRESELECT_KLARNA
• SHOW_ONLY_KLARNA
• HIDE_KLARNA

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.

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

Now that Presentation Instructions have been retrieved and all assets are ready, the Payment Selector can be adapted to the instructions and Klarna can be added as an option to it. The Payment Presentation SDK interface allows the Acquiring Partner to retrieve the visual assets and presentation instructions needed to build the payment selector.

In this step it is needed to present to the customer Klarna as an available payment method and initially only 3 elements should be presented to the customer:

1. Icon
2. Header
3. Short Subheader

With the PaymentPresentation interface, the Acquiring Partner can retrieve the URL to the Klarna Payment badge using the payment presentation icon attribute while adapting to the look and feel of the page.

// retrieve the payment descriptor icon
const klarnaIcon = paymentPresentation.icon({
  type: "badge|square|card-mark"
}).imageUrl;

With the PaymentPresentation interface, the Acquiring Partner can retrieve descriptor header using the header attribute of the presentation method.

The Acquiring Partner can either retrieve the header text or render the header element in a specified container id .

//The function should locate the element with the provided container id and render the header content there.
paymentPresentation.header.component().mount("#header-container");

// Alternatively retrieve the payment descriptor header text
const descriptorHeader = paymentPresentation.header.text;

With the PaymentPresentation interface, the Acquiring Partner can retrieve the subheader attribute from the payment presentation sdk instance to load the corresponding Klarna subheader component in a container, or alternatively to retrieve the raw assets needed to build the subheader.

The SDK enables Acquiring Partner to render the Klarna subheader component in a specified container id (recommended)

//Mount the short descriptor subheader
paymentPresentation.subheader.short.component().mount("#subheader-short-container");

Alternatively, it is also possible to retrieve the subheader raw assets needed to build the placement

// retrieve the short subheader text
const descriptorSubheaderShortText = paymentPresentation.subheader.short.text;

The following sample code shows how Acquiring Partners can render Klarna in the payment selector according to payment presentation instruction.

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

function renderKlarnaPaymentDescriptor(paymentPresentation) {
  //get reference to Klarna container

Once the customer has decided to proceed to the Payment using Klarna, or if Klarna was pre-selected due to the presentation instruction seen above, Acquiring Partners have to refresh the layout presenting Klarna Enriched Subheader as well as loading the Payment Button.

1. Icon
2. Header
3. Short Subheader
4. Enriched Subheader
5. Payment Button

Similarly than in the previous step, with the PaymentPresentation interface, is possible to retrieve the enriched subheader attribute from the payment presentation sdk instance to load the corresponding Klarna subheader component in a container, or alternatively to retrieve the raw assets needed to build the subheader.

The SDK enables Acquiring Partner to render the Klarna subheader component in a specified container id (recommended)

//Mount the enriched descriptor subheader
paymentPresentation.subheader.enriched.component().mount("#subheader-enriched-container");

Alternatively, it is also possible to retrieve the subheader raw assets needed to build the placement

// retrieve the enriched subheader text and link elements
const descriptorSubheaderEnrichedText = paymentPresentation.subheader.enriched.text;
const descriptorSubheaderEnrichedLink = paymentPresentation.subheader.enriched.link.href;
const descriptorSubheaderEnrichedlinkText = paymentPresentation.subheader.enriched.link.linkText;

The previously described Payment Presentation element exposes the Payment Button Interface that can be used to display Klarna's Payment Button. It will require a Button Configuration that will define what experience to trigger and a mount method to render the button inside the DOM.

// Klarna Payment Presentation instance declared to build the payment selector
var paymentPresentation = Klarna.Payment.Presentation({
  currency: "USD",
  amount: 11800,
  locale: "en-US",
  intents: ["PAY"]
});

// Configure the paymentButton of the Payment Presentation instance and specify the attributes of the authorize button click handler. The data attribute is a function that returns a Promise resolving to an object containing the results of a call to the Payment Authorize API.