Token creation - Build the payment form

With this integration path, Partners are presenting a payment form generated by the Acquiring Partners:

• Customers are either redirected to a hosted checkout page or a checkout element embedded in the Partner website via a JavaScript library.
• Acquiring Partners must use Klarna's SDK to dynamically retrieve payment presentation assets (headers, icons, subheaders, button and instructions) and build the payment form.
• Klarna’s SDK keeps all elements up-to-date and optimized for the best conversion.

The following diagram gives an overview of the customer journey and the Acquiring Partner workflow:

On a high level, building the payment form requires the following actions:

• Accept klarna_network_session_token in your checkout session API and JavaScript library.
• Accept klarna_network_data in your checkout session API (server-side only).
• Forward both Klarna Network data points to Klarna exactly as received — do not modify.
• If klarna_network_session_token is provided, exchange it server-side for an sdk_token.
• Load the Klarna SDK from the official URL — never bundle or self-host.
• Initialize the SDK with clientId, partnerAccountId, sdkToken, products and locale.
• Use Klarna.Payment.presentation() SDK method to dynamically retrieve personalized assets to build the payment selector
• Never hardcode Klarna logos, texts, or layout — always render via SDK components.
• Always follow the returned instruction (e.g., show, preselect Klarna).
• Mount the Payment Button only after Klarna is selected or preselected.

Before calling the Payment Authorization API, update the Partner-facing API to collect Klarna-specific context provided by the Partner. This data preserves session continuity, enables interoperability across Klarna Network features and improves risk assessment.

• klarna_network_session_token

  • Encodes Klarna session context, such as payment option preselection, prequalification results, or payment approval
  • May be present on the initial authorization request
  • Required when finalizing authorization after a step-up flow
• klarna_network_data

  • Encodes additional Klarna Network context supplied by the Partner, including supplementary purchase data
  • Must not be parsed, enriched, or transformed

Below is an example of how Acquiring Partners can accept the Klarna Network parameters in their Partner-facing APIs.

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "klarna_network_session_token": "eyJhbGciOiJ...",
      "klarna_network_data": "{\"content_type\":\"application/vnd.klarna.interoperability-data.v2+json\",\"content\":{\"payment_request\":{...}}}"
    }
  }
}

Requirements

• Accept the Klarna Network parameters in the Partner-facing APIs.
• Use the field names klarna_network_session_token/klarna_network_data, ensuring that it’s easy for any Partner to identify and use.
• Validation should be implemented, but it must not be more restrictive than what is specified in Klarna’s Payment Authorize API.
• All printable UTF-8 characters must be supported
• Forward the Klarna Network parameters unmodified to Klarna.

Supplementary purchase data improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience. It includes structured information such as line items, L2/L3 data for Card Network optimization and other transaction context. Acquiring Partners may receive this data from the Partner in two ways:

1. 1.
   Embedded in klarna_network_data

   • 1.1.
     No parsing needed. Just forward it as-is.
2. 2.
   As individual fields in the Acquiring Partner’s API

   • 2.1.
     The Acquiring Partner is responsible for mapping existing fields in their payment API with the fields defined in the supplementary_purchase_data object when calling the Payment Authorize API.

Read more about Supplementary Purchase Data here.

Before presenting the payment form, if an klarna_network_session_token was shared by the Partner, the Acquiring Partner must check if Klarna payment should be fast-tracked. This typically happens when the Partner implements Klarna boost features such as Klarna Express Checkout and the customer has given the approval for payment.

curl -G 'https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/presentation' \
     --header 'Authorization: Basic <API key>' \
     --header 'Klarna-Network-Session-Token: eyJhbGciOiJIU...' \
     --data-urlencode 'locale=en-US' \
     --data-urlencode 'amount=11836' \
     --data-urlencode 'currency=USD' \
     --data-urlencode 'intents[]=SUBSCRIBE'

The PaymentPresentation interface provides the full Klarna branding package and instructions tailored to the customer's purchase. However, at this step, the only relevant information is payment_status.

{
    ...
    "payment_status": "PENDING_PARTNER_AUTHORIZATION",
    ...
}

Using Klarna Web SDK, you can:

• Display Klarna dynamically alongside other payment options in your payment form.
• Embed Klarna’s UI elements directly in your frontend for a consistent and responsive design.
• Manage the interaction flow while offloading the rendering and logic to Klarna’s SDK.

The Acquiring Partner must exchange the acquired customer_token for a short-lived sdk_token using the Generate SDK Token API endpoint. If an klarna_network_session_token was passed by the Partner in the charge call, both tokens should be used for the exchange.

The sdk_token is a single-use, browser-bound credential that restores the customer’s checkout context when Klarna’s Web SDK is loaded. This token should be exchanged server-side before initializing the SDK and displaying the checkout page to the customer.

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: "klarna_test_client_***",
    products: ["PAYMENT"],
    partnerAccountId: "krn:partner:global:account:***",
    sdkToken: "rxvqGi07j...", // retrieved from server
    locale: "en-US" // optional but recommended
  });

  // sdkToken can also be set after SDK initiation

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

The expected outcomes are as follows:

Initial presentation	When Klarna is selected

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

{
  "amount": 11800, // subscription billing amount.
  "currency": "USD",
  "locale": "en-US",
  "intents": ["SUBSCRIBE"],
  "subscription_billing_interval": "MONTH",
  "subscription_billing_interval_frequency": 1
}

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.

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

The presentation instructions are derived from possible customer purchase journeys described in the following 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>
`;

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. 1.
   Icon
2. 2.
   Badge
3. 3.
   Header
4. 4.
   Subheader
5. 5.
   Message
6. 6.
   Terms
7. 7.
   Button

Mount the Klarna payment option components within your designated Klarna payment method to render them dynamically in the payment form. When defining the layout, allocate sufficient space for all components and choose the appropriate variants to match your payment form structure. The message component must always occupy a full row to ensure legibility, positioned directly beneath the header, sub-header, and logo, as illustrated above.

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

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

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.

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.

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`);