Payment Presentation for Hosted Checkout integration

Display one or multiple Klarna payment methods in your checkout and let customers select one to complete their purchase. This guide shows you how to integrate Klarna payment methods using the Klarna web SDK.

What you'll build:

• A payment form that dynamically displays Klarna payment methods
• Integration with Klarna web SDK for seamless customer experience
• Support for fast-track payments when the customer has authorized a transaction

Before building the payment form, ensure you have:

• A Partner Account onboarded with Klarna
• An API Key and a Client ID associated with your Partner Account
• Registered the domains your integration will use to load Klarna's web SDK
• A Partner-facing API allowing Partners to start a hosted checkout flow

The integration process consists of the following key steps:

1. 1.
   Gather and forward payment context data: Collect Klarna-specific parameters from Partners
2. 2.
   Fast-track Klarna Payment Authorization when applicable: Check if Payment Authorization should be auto-approved
3. 3.
   Initialize the Web SDK: Set up Klarna web SDK with proper configuration
4. 4.
   Present Klarna in the payment form: Display Klarna options dynamically using the SDK

Update the Partner-facing API to collect the following data points from the Partner for customer-initiated payment scenarios:

Requirements

• Use exact parameter names klarna_network_session_token and klarna_network_data in the Partner-facing API to ensure Partners can easily identify and use them.
• Forward all parameters unmodified to Klarna.
• Parameter validation must not be more restrictive than Klarna's authorizePayment.
• Support all printable UTF-8 characters.
• Supplementary purchase data handling:

  • Map your existing Partner-facing fields (line items, customer billing address, shipping, payment reference) into supplementary_purchase_data when calling Klarna
  • Don't add new Partner-facing fields "just for Klarna" if you already have equivalent fields in your existing schema. Avoid forcing Partners to submit the same data twice using parallel structures

Before presenting the payment form, if a Klarna Network Session Token (klarna_network_session_token) was shared by the Partner, the Acquiring Partner must check if Klarna Payment Authorization can be fast-tracked. This typically happens when the Partner implements Klarna Conversion features such as Klarna Express Checkout and the customer has authorized the transaction.

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

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",
  ...
}

When Klarna Payment Authorization was not fast-tracked, forward the Klarna Network Session Token (klarna_network_session_token) to the frontend and initialize the Klarna web SDK to display Klarna payment methods in your checkout.

Call [ generateKlarnaNetworkSessionToken] with the Customer Token in the Klarna-Customer-Token header. If the Partner has already provided a Klarna Network Session Token (for example, from an earlier browsing session), include it in the Klarna-Network-Session-Token header as well. When both headers are provided, Klarna attaches the customer token to the existing session instead of creating a new one, enabling a seamless transition from anonymous to authenticated context within the same shopping session.

Pass the returned Klarna Network Session Token to the Web SDK during initialization.

curl -X POST https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/network/session/tokens \
-H 'Authorization: Basic <API key>' \
-H 'Klarna-Customer-Token: krn:partner:us1:test:identity:customer-token:vVQGmYzlfsQ16dko3[...]' \
-H 'Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]' # optional, include if available

{
  "klarna_network_session_token": "krn:network:us1:test:session-token:eyJhbGciOiJIU[...]"
}

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.

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

<script type="module">
  try {
    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:test:***",
      klarnaNetworkSessionToken: "[klarna_network_session_token]", // retrieved from server or received from Partner
      locale: "en-US" // optional but recommended
    });

After initializing the Web SDK, request Klarna's Payment Presentation to retrieve the visual assets, localized text, and display instructions needed to render Klarna as a payment method. The Web SDK dynamically adapts the presentation based on the customer's context, ensuring a consistent experience across different checkout states.

The process involves:

1. 1.
   Request Klarna's Payment Presentation using the initialized Web SDK
2. 2.
   Mount Klarna payment method components dynamically in your payment form
3. 3.
   Handle customer interactions (selection, deselection)
4. 4.
   Configure and display the payment button
5. 5.
   Implement the initiate callback to authorize the Payment Transaction when the customer clicks the button

One payment method without preselection	One payment method selected	Saved payment method available and selected	Pick Plan option 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

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

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

paymentOption and savedPaymentOption share a similar object structure:

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

Apply Klarna's Payment Presentation instructions to control how Klarna appears in your checkout. Following these instructions ensures consistent customer experiences and enables features like Klarna Express Checkout and Sign in with Klarna.

Your implementation must handle both paymentOption (default) and savedPaymentOption (customer-specific). Prioritize savedPaymentOption when both are present.

The instruction attribute indicates how Klarna should be displayed:

For full API specifications, see Klarna web SDK.

The following examples show how to apply each instruction. Your implementation must prioritize savedPaymentOption over paymentOption when both are available:

	Show Klarna	Preselect Klarna	Show only Klarna	Hide Klarna
Without saved payment method
With saved payment method

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

  // Create containers for both saved and default payment options
  root.innerHTML = `     <div id="klarna-option-saved" class="klarna-option saved" style="display:none;">
</div>

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

Mount the Klarna payment method 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 method is selected/deselected, ensure the additional visual components are shown/hidden properly.

/**
- Toggle the Klarna payment method selected state.
- Use for both SDK preselection (PRESELECT_KLARNA) and customer 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 customer 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"
    intent: "PAY",
    initiationMode: "DEVICE_BEST", // "DEVICE_BEST" | "ON_PAGE" | "REDIRECT"
    initiate: (klarnaNetworkSessionToken, paymentOptionId) =>
      initiateKlarnaPayment(klarnaNetworkSessionToken, paymentOptionId)
  })
  .mount(`#${containerId}-payment-button`);

When using the Payment Authorize API, the Partner frontend implements the initiate callback to send the payment context to the Partner backend. The Partner backend then calls Klarna's authorizePayment action and returns the result.

The initiate callback receives two parameters from the Klarna web SDK:

• klarnaNetworkSessionToken — represents payment context, including the customer's authentication and consent state. Forward this to the Partner backend and include it in the Klarna-Network-Session-Token header when calling the Payment Authorize API.
• paymentOptionId — identifies which payment option the customer selected. Forward this to the Partner backend and include it as the payment_option_id field in the request body when calling the Payment Authorize API.

The callback must return a Promise that resolves to a returnUrl when Klarna returns STEP_UP_REQUIRED, or null if the authorization completes immediately (APPROVED or DECLINED).

Sample code

async function initiateKlarnaPayment(klarnaNetworkSessionToken, paymentOptionId) {
  // Partner-implemented backend endpoint that calls Klarna's authorizePayment
  const response = await fetch("/api/authorize-payment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      klarnaNetworkSessionToken,
      paymentOptionId,
      amount: 11800,
      currency: "USD"

After building the payment form, complete your integration:

• Authorize the payment transaction - Implement the backend endpoint to handle authorization requests from the frontend
• Handle post-purchase events - Manage captures, refunds, and cancellations