Build checkout form with Klarna Web SDK (Cybersource orchestrated)

Integrate Klarna's Web SDK and let Cybersource orchestrate the Klarna authorization. Initialize the SDK, present Klarna in the payment selector, and forward the `klarna_network_session_token` to Cybersource to complete the flow.

17 min read

Warning

The request example on this page is a simplified illustration of the call to Cybersource. Cybersource has confirmed the step-up link (processorInformation.paymentUrl) and the completion webhook (payments.payments.updated with payload.status of AUTHORIZED).

Prerequisites

Before you integrate, check that you meet the following prerequisites:

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

Info

In this flow, Cybersource orchestrates the Klarna authorization and subscribes to the payment.request.state-change.completed webhook on your behalf. You don't need to register webhooks with Klarna or call Klarna's Payment Request API directly.

Integration overview

Here's an overview of all the steps to display Klarna and initiate payments via the Web SDK in the Cybersource-orchestrated flow:

1.
Initialize Klarna Web SDK and present Klarna as a payment method in your payment form.
2.
Customer clicks the Klarna payment button in your checkout.
3.
The initiate callback is triggered and the Klarna Web SDK provides a klarna_network_session_token to your client.
4.
You forward the klarna_network_session_token together with the purchase details to Cybersource to create the payment session.
5.
If customer authentication is required, Cybersource returns the step-up link as processorInformation.paymentUrl:
- 5.1.
  Return that value as paymentRequestUrl from the initiate callback so the Klarna Web SDK launches the Klarna Purchase Journey. Klarna calls this link payment_request_url.
- 5.2.
  The customer completes the Klarna Purchase Journey.
6.
Cybersource notifies you when the order is completed.
7.
You redirect the customer to your confirmation page.

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna participant AP as Cybersource C->>P: Visit checkout page P->>K: Initialize Klarna Web SDK P->>K: Request presentation instructions K-->>P: Return presentation assets and instructions P->>P: Render Klarna in payment selector C->>P: Select Klarna P->>P: Update payment selector<br/>Show Klarna payment button C->>P: Click Klarna payment button K->>P: Trigger initiate callback Note over K,P: klarna_network_session_token P->>AP: Create payment session Note over P,AP: klarna_network_session_token alt If customer authentication is required AP-->>P: Return processorInformation.paymentUrl P->>K: Forward paymentRequestUrl to Klarna Web SDK K->>C: Launch Klarna purchase journey C->>K: Complete Klarna purchase journey end AP-->>P: Order completed notification P-->>C: Display confirmation message

Integration details

Present Klarna in the payment form

Presenting Klarna in the payment form involves retrieving the visual assets, localized text, and display instructions required to correctly render Klarna as a payment method 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 method(s) dynamically in the payment form according to the instructions.
4.
Allow the customer to select and deselect a Klarna payment method.
5.
Display the Klarna button and start the payment process when clicked.

The expected outcomes are as follows:


Initial presentation	When Klarna is selected

Success

Klarna's payment presentation best practice To ensure the best user experience and optimal conversion rates when presenting Klarna as a payment method, please apply the following recommendations:

Display Klarna descriptor dynamically alongside other payment methods in your payment form.
Embed Klarna's UI elements directly in your frontend for a consistent and responsive design.

The next sections in this guideline will walk through how this can be achieved using Klarna Web SDK.

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:

Parameter	Presence	Description
`clientId`	required	A credential used to identify the Partner, which can be obtained from the Klarna Partner Portal. To ensure the credential functions properly, make sure to register all domains where the Web SDK will be used.
`products`	optional	An array used to specify which products should be loaded to optimize performance by limiting the amount of data downloaded. If the `PAYMENT` product is included, only the `Klarna.Payment` package will be loaded. If the products array is omitted, all available packages will be loaded by default.
`locale`	optional	Language and region code (for example, `en-US`). If omitted, Klarna may default based on the customer's browser settings.

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

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: ["PAYMENT"],
    locale: "en-US", // optional
  })

  // Klarna SDK ready to be utilized

Error

If the domain is not registered, subsequent method calls will result in an error.

When loading the Web SDK, follow these practices:

Do	Don't
Load the Web SDK from `https://js.klarna.com/web-sdk/v2/klarna.mjs` to remain compliant.	Host the Web SDK yourself, whether bundled or served from your own server.
Keep the SDK in the top-level (first-party) browsing context.	Load the Web SDK inside an iframe.
Specify `products` for performance.	Omit `products`.
Disclose Web SDK tracking in your site's notices (learn more).	Use the Web SDK without disclosing tracking technologies.

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:

Parameter	Presence	Description
`amount`	conditional	The transaction amount in minor units following ISO 4217 exponents (for example, $118.00 = `11800`, ¥1400 = `1400`). This field is required if any of the intents include `PAY`, `SUBSCRIBE`, or `DONATE`; otherwise, it is optional.
`currency`	required	Three-letter ISO 4217 currency code (for example, `USD`, `EUR`).
`locale`	optional	Locale code to localize texts and formats (for example, `en-US`, `de-DE`). If you don't set this, it will automatically use the value chosen when you first set up the Web SDK. If that's not available, it will use your browser's settings instead.
`intents`	optional	Specify the intent of the checkout flow: `PAY`, `SUBSCRIBE`, `SIGNUP`, `SIGNIN`, `DONATE`, `ADD_TO_WALLET`. If omitted, `intents` defaults to `["PAY"]`.

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

Error

Performance optimization It is important to ensure that Klarna is displayed at roughly the same time as other payment methods, with an acceptable delay of less than 100 ms. To achieve this, begin initializing the Klarna Web SDK and invoke the payment presentation method concurrently while loading the list of all enabled payment methods from your server.

Sample code

JAVASCRIPT

1 2 3 4 5 6 7

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:

Attribute	Presence	Purpose
`instruction`	required	Specifies how Klarna as a payment method(s) should be displayed (for example, whether to show, preselect, or display as show-only). Adhering to these payment presentation instructions ensures customers have the best possible experience and optimizes conversion rates.
`paymentOption`	optional	Defines the default payment method applicable to all purchase types. This object includes the visual elements required to represent Klarna during checkout.

The paymentOption object structure is as follows:

Attribute	Presence	Purpose
`paymentOptionId`	required	The identifier of the payment method. The value is required to be sent to the Payment Authorize API or the Payment Request API when initiating the payment.
`icon`	required	Klarna badge/logo suitable for checkout forms.
`header`	required	The main descriptor that introduces Klarna in the payment form. The value will be dynamically adjusted based on the locale provided.
`subheader`	required	The descriptor subheader which must be loaded inline below the main descriptor header. Short and enriched descriptive texts. Provides transparency on available options like installments, pay later, etc.
`message`	optional	Enriched tailored description with link.
`badge`	optional	Badge used for saved options or promotions.
`terms`	optional	Defines terms/disclosures potentially with links.
`paymentButton`	required	Payment button that starts the Klarna Purchase Journey.

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 Express Checkout and Sign in with Klarna.

The instruction attribute has the following values:

Instruction	Description
`SHOW_KLARNA`	Show Klarna alongside other payment methods.
`PRESELECT_KLARNA`	Show Klarna pre-selected but still alongside others. This is returned when using the `customer_token` issued from the Sign in with Klarna feature or the tokenization flow.
`SHOW_ONLY_KLARNA`	Show Klarna as the only payment method. This is returned when the customer has finished the first step of Express Checkout multistep.

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

Info

Skip this section if you don't use any conversion features from Klarna such as Express Checkout, Sign-in with Klarna, Klarna Messaging or Klarna Prequalification.

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

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

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

Mount Klarna payment method components

Once an instance of PaymentPresentation is created, the Klarna payment method(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 method 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.

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

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

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

Handle Klarna payment method selection and deselection

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

1 2 3 4 5 6 7 8 9 10

/**
 * 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;
  }

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 the Klarna payment button

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

Parameter	Description
`id`	Sets a custom DOM ID on the rendered button. Useful for testing or styling.
`shape`	Defines the button's shape. Possible values are:`default`, `pill`, `rect`
`theme`	Sets the visual theme of the button. Possible values are: `default`, `light`, `dark`, `outlined`
`locale`	Sets the language and region (for example, `en-US`). If you don't set this, it will automatically use the value chosen when you first set up the Web SDK. If that's not available, it will use your browser's settings instead.
`disabled`	Disables the button when set to `true`. Useful during form validation or async operations.
`loading`	Forces the button into a loading state. Useful when awaiting async setup or validation.
`intents`	Sets the purpose of the payment. Used to personalize the button and flow if not set when creating the `PaymentPresentation` instance.
`initiate`	Function that returns a Promise resolving to either a `PaymentRequestData`, a `paymentRequestUrl`, or a `returnUrl`. This will be handled differently depending on the integration path.
`initiationMode`	Defines how Klarna launches the Klarna Purchase Journey.

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

Sample code

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

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: (klarnaNetworkSessionToken, paymentOptionId) => initiateKlarnaPayment(klarnaNetworkSessionToken, paymentOptionId)
  })

Info

The button will automatically handle customer interaction and trigger the Klarna purchase flow via the initiate function.

Forward the session token to Cybersource

In this flow, you don't call Klarna's Payment Request API directly. Instead, the initiate callback receives a klarnaNetworkSessionToken from the Klarna Web SDK. You forward this token to Cybersource together with the purchase details, and Cybersource performs the authorization with Klarna on your behalf.

The callback must return one of the following to the Web SDK:

Return value	When to return it
`undefined` or an empty object	Cybersource confirms the payment was approved without step-up. The Web SDK completes without launching a Klarna Purchase Journey.
`{ paymentRequestUrl }`	Cybersource indicates that customer authentication is required (`STEP_UP_REQUIRED`) and returns the step-up link as `processorInformation.paymentUrl`. Pass that value back as `paymentRequestUrl`. The Web SDK launches the Klarna Purchase Journey with this URL.

Info

A klarna_network_session_token is valid for 1 hour. Forward it to Cybersource as soon as you receive it.

Client code

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

const klarnaPaymentButton = klarna.Payment.button({
  initiate: async (klarnaNetworkSessionToken, paymentOptionId) => {
    const resp = await fetch('/create-payment-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        klarnaNetworkSessionToken,
        paymentOptionId,
        /* amount, currency, and purchase details */
      })

Server code

Your server endpoint forwards the klarna_network_session_token to Cybersource. When customer authentication is required, Cybersource returns the step-up link as processorInformation.paymentUrl. Pass that value back to the Klarna Web SDK as paymentRequestUrl.

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

// Server.js
// Simplified backend example: forward the Klarna token to Cybersource

const axios = require('axios');

const ACQUIRING_PARTNER_API_KEY = 'YOUR_API_KEY';
const CYBERSOURCE_API_BASE_URL = 'https://apitest.cybersource.com';

async function createPaymentSession({ klarnaNetworkSessionToken, paymentOptionId, order }) {
  const url = `${CYBERSOURCE_API_BASE_URL}/payment`;

For the full request/response schema, consult Cybersource's API reference.

Success

Create a new payment session on every button click instead of reusing tokens.

Handle step-up

If Cybersource returns STEP_UP_REQUIRED, read the step-up link from processorInformation.paymentUrl and return it as { paymentRequestUrl } from the initiate callback. The Klarna Web SDK launches the Klarna Purchase Journey, the customer completes the authentication, and Cybersource notifies you of the final result.

You don't need to subscribe to Klarna webhooks or monitor the Klarna payment request lifecycle yourself. Cybersource handles these on your behalf.

Receive the final order outcome

Once the payment is authorized, either directly or after a successful step-up, Cybersource sends a payments.payments.updated webhook. The first time Cybersource emits this event for a Klarna payment is when Klarna returns an approved result. Treat payload.status of AUTHORIZED as the signal to display the confirmation page.

Example webhook

JSON

1 2 3 4 5 6 7 8 9 10

{
  "eventType": "payments.payments.updated",
  "webhookId": "5b24f53f-627d-6ecf-e063-9e588e0a7028",
  "productId": "alternativePaymentMethods",
  "organizationId": "<cybersource_organization_id>",
  "eventDate": "2026-09-24T12:19:01",
  "transactionTraceId": "45f566c15536145328dfe9c426bcd0d1324553263b66f60fb656de6033162786",
  "retryNumber": 0,
  "payload": {
    "statusCode": "201",

In rare cases where there's a discrepancy between the amount and purchase details submitted by the Klarna Web SDK and the information submitted to Cybersource, the authorization may be rejected and the customer asked to approve the purchase again through the step-up journey.

Web Sdk

Jump to section...