Before you integrate, 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. Inside Klarna Portal:
   1. Confirm that you have generated a client identifier with your domain URL allowlisted.
   2. Confirm that you have generated an API key.
4. Confirm that you have registered webhooks for payment.request.state-change.completed events following Webhooks guidelines.
5. Add Terms and Conditions for Web SDK.

Here's an overview of all the steps to display Klarna and initiate payments via the WebSDK:

1. Present Klarna as a payment option in the payment form.
2. Customer clicks the Klarna payment button in your checkout.
3. You create a server-side payment request to Klarna and share available interoperability data points.
4. If customer interaction is required, Klarna returns a payment_request_id.
   1. The payment_request_id is used to initiate the purchase flow with Klarna’s WebSDK.
   2. The Klarna purchase journey is launched.
   3. The customer completes the Klarna purchase journey.
5. Klarna returns an interoperability_token via webhook.
6. You create an authorization request with Paytrail and share the required interoperability data points.
7. Paytrail responds with an approval and order completion.
8. Customer is redirected to your confirmation page.

Presenting Klarna in the payment form involves retrieving the visual assets, localized text, and display instructions required to correctly render Klarna as a payment option and display the payment button. This dynamic presentation ensures a consistent customer experience, accurate localization, and optimized conversion performance, while adapting seamlessly to different checkout states.

​On a high level, the process involves:

1. Initialize Klarna Web SDK in your checkout experience.
2. Request Klarna’s payment presentation for the current payment context.
3. Render Klarna payment option(s) dynamically in the payment form according to the instructions.
4. Allow the customer to select and deselect a Klarna payment option.
5. Display the Klarna button and start the payment process when clicked.

​The expected outcomes are as follows:
​

Initial presentation	When Klarna is selected

​

​

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.
SDK initialization sample

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

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

  // Klarna SDK ready to be utilized
  // Klarna.Payment.button().mount('#payment_container')
</script>

Klarna payment presentation request

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:

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

Sample code

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

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 describes how to apply Klarna’s payment presentation instructions, which define how Klarna should appear in your checkout. Following these instructions ensures a consistent experience across payment states and is required for features like Klarna Express Checkout and Sign in with Klarna.

The instruction attribute has the following values:

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

Here are example outcomes illustrating how Klarna should be displayed for each instruction:

Show Klarna	Preselect Klarna	Show only Klarna

The presentation instructions are derived from possible customer purchase journeys described in the How to present Klarna article.
Sample code:

function renderKlarna(paymentPresentation) {
  if (!paymentPresentation) return;

  const root = qs("#klarna-payment-method");
  if (!root) {
    console.error("Missing #klarna-payment-method container.");
    return;
  }

  root.innerHTML = `<div id="klarna-option-default" class="klarna-option default" style="display:none;">

</div>

Mount Klarna payment option components

Once an instance of PaymentPresentation is created, the Klarna payment option(s) must be rendered dynamically in the payment selector according to Klarna’s presentation guidelines. The following diagram displays different visual components and how they are rendered in different selection states:

1. Icon
2. Badge
3. Header
4. Subheader
5. Message
6. Terms
7. Button

Mount the Klarna payment option components within your designated Klarna payment method container to render them dynamically in the payment form. Ensure that all components—including those not immediately visible—are mounted during initialization, and manage their visibility through your own logic or UI controls.

function renderKlarnaOption(containerId, option) {
  const container = qs(`#${containerId}`);
  if (!container) {
    console.error(`Missing #${containerId} container.`);
    return;
  }

  const ids = {
    icon:    `${containerId}-icon`,
    header:  `${containerId}-header`,
    subhdr:  `${containerId}-subheader`,
    badge:   `${containerId}-badge`,

Handle Klarna payment option selection and deselection

When a Klarna payment option is selected/deselected, ensure the additional visual components are shown/hidden properly.

/**
 * Toggle the Klarna payment option selected state.
 * Use for both SDK preselection (PRESELECT_KLARNA) and user interactions.
 */
function toggleKlarnaPaymentOptionSelection(containerId, isSelected) {
  const container = qs(`#${containerId}`);
  if (!container) {
    console.error(`Missing container #${containerId}.`);
    return;
  }

  const display = isSelected ? "block" : "none";

Handle Klarna payment button styling and initiate callback

The payment presentation instance allows you to mount the prebuilt button component. The Klarna Payment Button is context-aware and dynamically adapts to your configuration.

Klarna payment button variants

Choose the theme and shape of the payment button to best fit into your online store in a way that complements your brand and encourages user engagement. More details on the button styling can be found here.

Configure Klarna payment button

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

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: (klarnaNetworkSesionToken, paymentOptionId) => initiateKlarnaPayment(klarnaNetworkSesionToken, paymentOptionId)
  })
  .mount(`#${containerId}-payment-button`);

Initiate the purchase journey

In order to launch the purchase flow, you need to implement the initiate callback on the Klarna payment button interface. The initiate callback is triggered when the customer clicks on the Klarna payment button, upon which, the payment request data such as amount and currency must be submitted to Klarna server.

For the full API specifications, refer to the API reference.

Create Klarna payment request on the server side and initiate the purchase flow using Klarna Web SDK

Create a payment request on the server side is the recommended approach to create the payment request, then share the payment request ID as response to the initiate callback.

Client code

const klarnaPaymentButton = klarna.Payment.button({
  initiate: async () => {
    const resp = await fetch('/create-klarna-payment-request', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ /* Your data here */ })
    });
    const data = await resp.json();
    return { paymentRequestId: data.paymentRequestId };
  }
});

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

Server code

// Server.js
// Simplified backend example for creating a Klarna payment request

const axios = require('axios');

// Klarna credentials and base URL (replace with your keys and consider loading from environment variables)
const KLARNA_API_KEY = 'YOUR_API_KEY';
const KLARNA_BASE_URL = 'https://global-api.klarna.com'; // According to docs

// Function to create a Klarna payment request
async function createKlarnaPaymentRequest(data) {
  const url = `${KLARNA_BASE_URL}/v2/payment/requests`;

For the full API specifications, refer to the API reference.

This guide outlines how to monitor the Klarna Payment Request as part of the step up scenario. On a high level:

• Understand payment request lifecycle in order to handle COMPLETED, CANCELED, DECLINED and EXPIRED states properly.
• Monitor and retrieve the klarna_network_session_token and/or customer_token by using one or a combination of the following methods:
  • Subscribing to payment.request.state-change.* webhook events (required)
  • Reading the payment request

Payment request lifecycle

During the checkout process, the Payment Request will transition to various states. Find below an overview of the possible payment request states together with a transition diagram:

<u>State transition diagram</u>

Monitor and retrieve interoperability_token

To retrieve the required token(s), Klarna provides multiple integration methods. Subscribing to Klarna webhook events is required and may be combined with additional methods to improve resilience.

Using webhooks ensures reliable completion handling, particularly when the customer closes the browser before returning, network interruptions occur during redirects, or post-processing is required before notifying the customer.

The klarna_network_session_token is issued by Klarna after the customer approves the purchase. Use this token to finalize the authorization and create the corresponding Klarna payment transaction.

Method: Subscribe to webhook events (required)

Subscribe to the payment.request.state-change.completed webhook event using the guidelines provided here. Klarna sends this event when the Payment Request reaches the COMPLETED state.

This event indicates that the customer has finished the step-up interaction and that the Acquiring Partner can proceed with finalizing the authorization.

Sample payload

{
  "metadata": {
    "event_type": "payment.request.state-change.completed",
    "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
    "event_version": "v2",
    "occurred_at": "2024-01-01T12:00:00Z",
    "correlation_id": "2d1557e8-17c3-466c-924a-bbc3e91c2a02",
    "subject_account_id": "krn:partner:global:account:live:HGBY07TR",
    "recipient_account_id": "krn:partner:global:account:live:LWT2XJSE",
    "product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-[...]",
    "webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-[...]",
    "live": false

Consult the API reference for a complete description of the webhook payload.

Method: Read the payment request

As an alternative method, retrieve the Klarna token(s) by calling the Read Payment Request API.

Once the Payment Request reaches the COMPLETED state, the token(s) are available in the state_context object of the Payment Request.

Sample payload

{
  "payment_request_id": "krn:payment:eu1:request:10be1d49-7beb-6b24-b9dd-8c14d0528503",
  "state": "COMPLETED",
  "previous_state": "IN_PROGRESS",
  "state_context": {
    "klarna_network_session_token":"krn:network:eu1:live:session-token:[...]"
  },
  "expires_at": "2025-02-26T17:25:34.534721775Z",
  "created_at": "2025-02-24T17:25:34.534721775Z",
  "updated_at": "2025-02-24T17:25:34.534721775Z",
  "payment_request_reference": "request-reference-1234",
  "amount": 11836,

Make sure to add the interoperability_token received via the webhook and the purchase details within the call to Paytrail. If everything is implemented correctly, Klarna will approve the payment transaction.

curl -X POST https://api.acquiring-partner.com/payment \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_methods": {
      "klarna": {
        "klarna_interoperability_token": ""
      }
    }
  }'

In rare cases where there's discrepancy between the amount and purchase details submitted in the original payment request and the information submitted to Paytrail, Klarna may reject and ask the customer to approve the purchase again.