Integrate On-site messaging with Klarna webSDK

Enable Klarna payment messaging on your online store with Klarna WebSDK and boost transparency and conversion.


Messaging on the homepage	Messaging on the product detail page	Messaging in the checkout

Prerequisites recap

Before you integrate On-site messaging, check that you meet the following prerequisites:

1.
Ensure that you have Klarna enabled with your Acquiring Partner.
2.
Confirm you have access to the Klarna Portal.
3.
Inside Klarna Portal:
1. 3.1.
  Confirm that you have generated a client identifier with your domain URL allowlisted.
2. 3.2.
  Confirm that you have generated an API key.
4.
Add Terms and Conditions for Web SDK.

Integration overview

Here's an overview of all the steps to add On-site messaging into your website:

Initialize Klarna Web SDK using https://js.klarna.com/web-sdk/v2/klarna.mjs
Display Klarna On-site messaging on relevant pages.
Enable prequalification. The following diagram outlines the interactions among different components:

sequenceDiagram participant C as Customer participant P as Partner participant K as Klarna participant AP as Acquiring Partner P->>K: Initialize Klarna SDK P->>K: Get OSM placement K->>P: Return messaging/prequalification content P->>C: Display messaging/prequalification content alt Prequalification flow - Approved C->>P: Clicks to check purchase power P->>K: Create session ID & request interoperability token K->>P: Return session ID & interoperability token K->>C: Start prequalification journey C->>K: Completes prequalification K->>P: Send approval event & updated messaging P->>C: Update placement to show approval alt Partner builds checkout form K->>P: Prequalification state preserved else Checkout form via Acquiring Partner P->>K: Fetch interoperability token P->>AP: Share interoperability token end end

Integration details

Step 1: Initialize the Web SDK

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.

Use your clientId to initialize the SDK.

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

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

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

  // Klarna SDK ready to be utilized

Parameter	Presence	Description
`clientId`	required	A credential that identifies the Acquiring Partner (obtained via Klarna’s Credentials API). It is shared across all integrated Partners.
`products`	optional	Array to specify which products to load for optimal performance. This reduces the amount of data needed to download. For example, only loading `PAYMENT` will exclude the `CUSTOMER` product.
`locale`	required	Language and region code (e.g., `en-US`). If omitted, Klarna may default based on the customer’s browser settings.

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

Important implementation details

The script should always be loaded on the 1st-party context, never inside an iframe, to ensure the purchase flows work as expected.
Ensure the products are properly specified while initializing for the best performance outcome.

Legal notice When using the Klarna Web SDK, you are responsible for informing your users about the tracking technologies it uses. Learn more about how to disclose this on your site.

Step 2: Display Klarna On-site messaging

Web SDK provides the placement method that allows to create and mount the messaging placement programmatically.

Code example

HTML

1 2 3 4 5 6 7 8

klarna.Messaging.placement({
    key: 'credit-promotion-badge',
    amount: 20000,
    currency: "USD",
    locale: 'en-US',
    theme: 'light'
}).mount('#osm-placement');

Parameters

Parameter	Presence	Description
`key`	required	Placement type key. List of available keys
`currency`	required	Currency in ISO 4217 format. Supported currencies: AUD, EUR, CAD, CZK, DKK, HUF, MXN, NZD, NOK, PLN, RON, SEK, CHF, GBP, USD.
`amount`	required	Amount in minor units (e.g., $5.00 = 500) To populate `amount`: For static values, use the value instead of an empty string, for example, `amount=“12350”`. For dynamic values, use JavaScript. With a single placement on a page, you can use a query selector method, for example, `document.querySelector(‘klarna-placement’).dataset.purchaseAmount = 9999`. However, if you have multiple placements on one page, you have to use a more specific query selector.
`locale`	required	Locale for messaging ("en-AT", "de-AT", "nl-BE", "en-BE", "fr-BE", "en-CH", "de-CH", "it-CH", "fr-CH", "en-CZ", "cs-CZ", "de-DE", "en-DE", "da-DK", "en-DK", "es-ES", "en-ES", "fi-FI", "sv-FI", "en-FI", "fr-FR", "en-FR", "en-GB", "en-GR", "el-GR", "en-HU", "en-IE", "en-IT", "hu-HU", "it-IT", "nl-NL", "en-NL", "no-NO", "nb-NO", "en-NO", "en-PL", "pl-PL", "en-PT", "pt-PT", "en-RO", "ro-RO", "sv-SE", "en-SE", "sk-SK, "en-SK", en-CA", "fr-CA", "es-MX", "en-MX", "en-US", "es-US", "en-AU", "en-NZ")
`theme`	optional	Defines what the theme of the placement would be, which are `light` or `dark`
`intent`

Step 3: Enable pre-qualification

The pre-qualification feature allows customers to check their eligibility for Klarna financing before completing a payment request. This reduces friction and increases confidence, as customers know their options upfront.


Interact with Product or Cart On-site Messaging placement	Go through Klarna Pre-qualification flow	Checkout page reflects prequalified status using interoperability token.

Pre-qualification messaging can be shown in several ways:

Integrate with WebSDK : As part of a regular OSM placement (e.g., credit promotion auto size)

You build the payment form

If you load the WebSDK at the checkout, Klarna will preserved the Shopping session via the interoperability_token to reflect the pre-qualification in the checkout.

This will be stored for 48 hours. After this period the pre-qualification details will expire.

Acquiring Partner builds the payment form

When integrating On-site messaging (OSM) through the Klarna web SDK, Partners may need to retrieve an interoperability token and pass it to their Acquiring Partner for downstream processing or reporting.

Retrieve the Interoperability Token

After initializing the Klarna web SDK, use the provided API to obtain the interoperability token. This token is typically available via a callback or a dedicated method.

JAVASCRIPT

1 2 3

const interoperabilityToken = await Klarna.Messaging.getInteroperabilityToken();

Example: Integrate Presentation API using interoperability token

When initializing the Presentation API API

, it is important to give the api context on the customer to offer the personalised experience that Klarna tailors. This is done by adding the Interoperability token to the Klarna-Interoperability-Token header in the presentation api request.

Sample request body

SHELL

1 2 3 4 5 6 7 8 9 10

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/presentation \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Interoperability-Token: eyJhbGciOiJIU...' \
  -d '{
        "locale": "en-US",
        "amount": 11836,
        "currency": "USD",
        "intents": ["PAY"]
      }'

Web Sdk

API & SDK references

Payment Presentation API