Integrate On-site messaging with Klarna webSDK
Enable Klarna payment messaging on your online store with Klarna WebSDK.
5 min read
 |  |  |
| 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 Paytrail.
- 2.Confirm you have access to the Klarna Portal.
- 3.Confirm that you have generated a client identifier with your domain URL allowlisted.
- 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.
- Ensure session continuity through Klarna Network Session Token.
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 you (the Partner), which is obtained via Klarna’s Partner Portal |
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 MESSAGING will exclude the PAYMENT product. |
locale | optional | 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
productsare properly specified while initializing for the best performance outcome, by providing only the products that will be used by your web application. For On-Site Messaging to function theMESSAGINGproduct must be provided.
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
JAVASCRIPT
1
2
3
4
5
6
7
klarna.Messaging.placement({
key: 'credit-promotion-badge',
amount: 20000,
locale: 'en-US',
theme: 'light'
}).mount('#osm-placement');
The code example above will render the
credit-promotion-badge placement, check the placements page for the full selection of placements.Parameters
| Parameter | Presence | Description |
|---|---|---|
key | required | Placement type key. List of available keys |
amount | optional | Amount in minor units (e.g., $5.00 = 500), required for credit-promotion-* placements and optional for top-strip-promotion-*. To populate amount:
|
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 |
Some placement types come with the pre-qualification feature enabled. 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. Placements that support pre-qualifcation are:
top-strip-promotion-* and credit-promotion-*. |  |  |
| Interact with Product or Cart On-site Messaging placement | Go through Klarna Pre-qualification flow | Checkout page reflects prequalified status |
Step 3: Ensure session continuity through Klarna Network Session Token
Regardless of which placement type you use, any customer interaction with a placement can start a Klarna Network Session for that customer.
To keep the information Klarna shows the customer consistent for the rest of their journey, request the Klarna Network Session Token from the Web SDK and forward it to Paytrail when you initiate a payment.
For example, going through pre-qualification will inform the customer about their eligibility and forwarding this Klarna Network Session Token ensures the same pre-qualification outcome is communicated to the customer at every stage of checkout.
JAVASCRIPT
1
const klarnaNetworkSessionToken = klarna.Network.Session.token();For the exact field to forward
klarna_network_session_token to when you initiate a payment, refer to Paytrail's integration checklist.Related articles
Jump to section...