Before you integrate, 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. 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 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 your Acquiring Partner and share the required interoperability data points.
7. Acquiring Partner responds with an approval and order completion.
8. Customer is redirected to your confirmation page.

This guideline describes how Klarna should be presented in the payment form initially as well as when it's selected by the customer. The expected outcomes are as followed:

Initial presentation	When Klarna is selected

It's crucial that Klarna payment presentation is dynamic and not hardcoded on your server to deliver the best conversion outcome.

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 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

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

Klarna payment presentation response

The PaymentPresentation interface provides the full Klarna branding package and instructions tailored to the customer's purchase:

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

Follow Klarna payment presentation instruction

Klarna’s payment presentation instructions indicate whether a customer is ready to check out with a prepared payment via Klarna—for example, when Klarna Express Checkout or other Conversion Boost features are integrated. Partners are required to adhere to Klarna’s payment presentation instruction to achieve the best-in-class user experience.

The instruction attribute has the following values:

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

Here are the expected outcomes of the payment selector depending on the value of the payment presentation instruction:

Show Klarna	Preselect Klarna	Show only Klarna

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

Sample code:

if (paymentPresentation) {
  switch (paymentPresentation.instruction) {
    case "SHOW_KLARNA":
      console.log("Showing Klarna alongside other payment methods.");
      renderKlarnaOption(paymentPresentation);
      break;
    case "PRESELECT_KLARNA":
      console.log("Showing Klarna preselected alongside other payment methods.");
      renderKlarnaOption(paymentPresentation);
      break;

Display Klarna in the payment selector

Once an instance of PaymentPresentation is created, the Partner must dynamically render Klarna payment option in the payment selector according to Klarna’s presentation guidelines.

The following attributes from PaymentPresentation instance will be used when loading the payment selector initially:

1. Icon
2. Header
3. Subheader

Mount Klarna payment presentation icon, header and subheader to your Klarna payment method container to render the elements dynamically in your payment form.

function renderKlarnaOption(paymentPresentation) {
  const klarnaContainer = document.getElementById("klarna-option");

  if (!klarnaContainer) {
    console.error("Klarna container missing.");
    return;
  }

  // Clear the container first
  klarnaContainer.innerHTML = `

Handle Klarna payment method selection

After the customer selects Klarna in the payment selector (or if Klarna was pre-selected according to presentation instructions), the next step is to show:

• The Placement (more detailed messaging tailored to the customer and transaction).
• The Payment Button (to trigger Klarna’s Purchase Journey).

This step finalizes the presentation of Klarna's payment method before the customer proceeds to payment authorization.

1. Icon
2. Header
3. Subheader
4. Message
5. Payment Button

Display additional messaging

paymentPresentation
  .message
  .component()
  .mount("#klarna-message-container");

Display Klarna payment button

The payment presentation instance allows you to either mount the prebuilt button component or retrieve the button text asset. 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.

Mount 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

paymentPresentation
  .paymentButton
  .component({
    id: "klarna-payment-button",       // unique button/component ID
    shape: "pill",                     // "pill", "default", or "rect"
    theme: "default",                  // "default", "dark", "light", or "outlined"
    intents: ["PAY"],                  // defines payment intent, e.g., "PAY"
    initiationMode: "DEVICE_BEST",     // "DEVICE_BEST", "ON_PAGE", or "REDIRECT"
    initiate: () => {
      /** 

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 referenceAPI.

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

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

Once the customer approves the request, the payment request will enter the COMPLETED state and you’ll receive an interoperability_token which can be used to authorize the payment and complete the process. There are different ways to obtain the interoperability_token. The recommended approach is to listen to Klarna Webhook payment.request.state-change.completed events.

Webhook payload sample

{
  "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-a2c1-103dba3fc918",

Make sure to add the interoperability_token received via the webhook and the purchase details within the call to your Acquiring Partner. 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 the Acquiring Partner, Klarna may reject and ask the customer to approve the purchase again.