Offer Klarna Express Checkout by displaying the Klarna payment button on your product or cart page.

Klarna payment button featured in the Product detail page	Consumer confirms their payment and shipping details in one step	Consumer is redirected to merchant confirmation page after successful payment

This integration guide is only for implementation one-click purchase flow, which ensures the lowest friction to customers.

Before you integrate Express checkout, 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. Disclose Web SDK tracking in your site’s notices.

For a comprehensive, step-by-step walkthrough of these prerequisites, refer to the detailed integration guide.

Here's an overview of all the steps to add Klarna Express Checkout into your website:

• Initialize Klarna Web SDK using https://js.klarna.com/web-sdk/v2/klarna.mjs.
• Display Klarna payment button on relevant pages especially product and cart pages.
• Initiate the purchase flow by implementing the initiate callback to submit payment request data.
• Handle shipping details (optional): Use shippingConfig and handle shipping events (shippingaddresschange, shippingoptionselect).
• Use Klarna Webhooks to track payment status and retrieve the klarna_network_session_token.
• Authorize the payment with the Acquiring Partner by forwarding the klarna_network_session_token and purchase details.

The following diagram outlines the interactions among different components:

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>

Display Klarna payment button early in the shopping journey and provide customers with the option to skip ahead when they’re ready to purchase. High impact placements include the product detail page, cart page and checkout page.

Klarna payment button in product detail page	Klarna payment button in cart	Klarna payment button in checkout

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.

Create a button configuration object

The button() method can be configured with the following set of parameters:

Sample code

const buttonConfig = {
  id: "klarna-payment-button",
  shape: "pill", // "default" || "rect"
  theme: "default", // "dark" || "light" || "outlined"
  intents: ["PAY"],
  initiationMode: "DEVICE_BEST", // "ON_PAGE" || "REDIRECT"
  initiate: () => { /** Implement the initiate method **/ }
};

Mount Klarna payment button

Finally, mount the button inside the appropriate container:

klarna.Payment.button(buttonConfig).mount("#klarna-button-container");

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.

You can choose to either submit the data on the client side or creating a payment request on the backend side.

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

Create Klarna payment request on the server side

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: () => {
      // Collect any data you want to send to your server here:
      // const postData = { ... };
      // const resp = await fetch('/create-klarna-payment-request', {
      //   method: 'POST',
      //   headers: { 'Content-Type': 'application/json' },
      //   body: JSON.stringify(postData)
      // });
      // const data = await resp.json();
      return { paymentRequestId: data.paymentRequestId };
  }

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

Server code

// server.js
const express = require('express');
const axios = require('axios');
const bodyParser = require('body-parser');

// Klarna credentials (replace with your own, preferably load from env!)
const KLARNA_API_KEY = 'YOUR_API_KEY';
const KLARNA_BASE_URL = 'https://global-api.klarna.com'; // According to docs

const app = express();
app.use(bodyParser.json());

For the full API specifications, refer to the createPaymentRequest endpoint.

ALTERNATIVE: Create Klarna payment request on the client side

This approach allows you to conveniently send data to Klarna directly from the client. Return the payment request payload as follows:

const klarnaPaymentButton = klarna.Payment.button({
  initiate: () => {
    return {
      currency: "USD",
      amount: 1000,
      paymentRequestReference: "pay-ref-123",
      supplementaryPurchaseData: {
        purchaseReference: "pay-ref-123",
        lineItems: [],
        shipping: [],
        customer: {}
      },

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

OPTIONAL: Collect shipping details

Klarna Express Checkout allows customers to complete their purchase within Klarna’s interface, where they can select a payment method, enter their shipping address, and choose from available shipping options. This reduces the need for address collection on the merchant’s side and enables a more streamlined checkout experience, especially on mobile. Shipping methods can be dynamically calculated and returned based on the customer’s input, allowing for flexibility in delivery pricing and timing. This setup helps simplify integration while improving the overall user flow.

Display shipping banner	Display shipping options

Display shipping banner and collect shipping details

To enable the shipping banner and collect shipping details, include "shipping_config": { "mode": "EDITABLE" } in the payment request. The collected shipping details will be available under state_context.shipping after the customer approves the purchase.

If you need to restrict the countries to which you ship, include the supported_countries attribute with a list of permitted countries. By default, all Klarna-supported countries are available unless specified otherwise.

Update the server code as followed:

async function createKlarnaPaymentRequest(data) {
  const url = `${KLARNA_BASE_URL}/v2/payment/requests`;
  const payload = {
    currency: "USD",
    amount: 1000,
    payment_request_reference: "pay-ref-123",
    supplementary_purchase_data: {
      purchase_reference: "pay-ref-123",
      line_items: [],
      shipping: [],
      customer: {},
    },

In case the payment request was created on the client side, update the client code as followed:

const klarnaPaymentButton = klarna.Payment.button({
  initiate: () => {
    return {
      currency: "USD",
      amount: 1000,
      paymentRequestReference: "pay-ref-123",
      supplementaryPurchaseData: {
        purchaseReference: "pay-ref-123",
        lineItems: [],
        shipping: [],
        customer: {}
      },

The collected shipping data will be available when the payment request is completed.

See Monitor payment status section on this page for more information.

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

Validate shipping address and handle multiple shipping options

Customers easily select their shipping address and preferred shipping method directly within the Klarna review page, enabling the customer to checkout with one click.

To enable proper functionality of the shipping options integration, you, as the integrator, need to handle two event callbacks: shippingaddresschange and shippingoptionselect. These events allow you to communicate available shipping options after an address is selected, enabling the customer to choose from the provided options.

Handle shipping address change events

The shipping address changed event handler is triggered when the consumer changes their shipping address during the payment flow.

The shipping address returned has the following format:

{
  "city": "San Francisco",
  "postalCode": "94107",
  "region": "CA",
  "country": "US"
}

When the shippingaddresschange event is triggered, you are given the opportunity to accept or reject the shipping address. If you are able to deliver to the address, you should return the shipping options. It's recommended that you preselect a default shipping option for the provided address, you can do so by returning the shipping option in the selectedShippingOptionReference property. You should also update the amount and lineItems properties to reflect the selected shipping cost. Preselecting a shipping option skips the screen where the customer needs to select a shipping option and goes directly to the review screen. This will reduce the friction of the payment flow.

Handle shipping option selection events

When the customer selects a different shipping option, you will receive a shippingoptionselect event. Here you are supposed to return the updated the amount and lineItems properties to reflect the selected shipping cost. In some rare cases, if the shipping option is no longer available, you can reject the selection.

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

OPTIONAL: Request customer profile data to fulfill the purchase transaction

The SDK allows you to request necessary customer profile data to fulfill the purchase transaction such as email and phone number.

To enable this feature, include the collect_customer_profile with the list of required customer data values. The table below described the data that will be returned for following parameters:

Update the server code as followed:

async function createKlarnaPaymentRequest(data) {
  const url = `${KLARNA_BASE_URL}/v2/payment/requests`;
  const payload = {
    currency: "USD",
    amount: 1000,
    payment_request_reference: "pay-ref-123",
    supplementary_purchase_data: {
      purchase_reference: "pay-ref-123",
      line_items: [],
      shipping: [],
      customer: {},
    },

In case the payment request was created on the client side, update the client code as followed:

const klarnaPaymentButton = klarna.Payment.button({
  initiate: () => {
    return {
      currency: "USD",
      amount: 1000,
      paymentRequestReference: "pay-ref-123",
      supplementaryPurchaseData: {
        purchaseReference: "pay-ref-123",
        lineItems: [],
        shipping: [],
        customer: {}
      },

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

The collected customer profile data will be available when the payment request is completed. See next section, Monitor payment status, for more information.

Once the customer approves the request, the payment request will enter the COMPLETED state and you’ll receive an klarna_network_session_token which can be used to authorize the payment and complete the process. There are different ways to obtain the klarna_network_session_token. The recommended approach is to subscribe to Klarna Webhooks.

Subscribe to webhooks

Every successful approval will trigger the payment request to enter the COMPLETED state. Klarna will then trigger a payment request state change webhook to which you have to subscribe to:

From this request you will be able to retrieve the klarna_network_session_token which is needed to authorize the payment and complete the Express Checkout flow.

Once your webhooks are set up, you can manage them through API requests. Use these updateWebhook, deleteWebhook, and getWebhookById to update, delete, or retrieve details about your configurations.

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",
    "webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-8a90-dca726e639b5",
    "live": true

OPTIONAL: Listen to Web SDK events

On the frontend, you can listen for the complete event. When the customer successfully completes the purchase flow, the payment request’s status will change to COMPLETED, and y and you can then retrieve the interoperability token.

klarna.Payment.on("complete", async (paymentRequest) => {
  // The customer has successfully completed the payment flow and
  // the payment request can be confirmed using the interoperability token.
});

Sample paymentRequest callback

{
  "paymentRequestId": "krn:payment:eu1:request:64be490f...",
  "state": "COMPLETED",
  "stateContext": {
    "interoperabilityToken": "krn:network:eu1:klarna-network-session-token:e15432a5-ebcc-45bc-934c-e61399db597b",
    "shipping": {
      "recipient": {
        "givenName": "Klara",
        "familyName": "Test",
        "email": "recipient@email.us",
        "phone": "+18445527622"
      },

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

Make sure to add the klarna_network_session_token to the providerDetails.klarna.networkSessionToken field of Paytrail's /payments call.

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.

As an alternative to the /payments endpoint, Paytrail also offers two dedicated endpoints for Klarna: /payments/klarna/charge (for auto-capture) and /payments/klarna/authorization-hold (for manual capture). With these endpoints, you can use the same request body as you would with the /payments endpoint.

If you prefer to use /payments/klarna/authorization-hold;

• to capture the authorization, you need to call /payments/{transactionId}/klarna/commit
• to void (cancel) the authorization, you need to call /payments/{transactionId}/klarna/revert

For more details, check Paytrail's API documentation for Klarna.