For PartnersFor Acquiring Partners
Klarna

Express Checkout integration

Learn how to integrate Express Checkout in the Partner's store.
Offer Express Checkout by displaying the Klarna payment button on the product or cart page.
undefined
undefined
undefined
Klarna payment button featured in the Product detail pageCustomer confirms their payment and shipping details in one stepCustomer is redirected to the Partner's confirmation page after successful payment
This integration guide is only for implementing the one-click purchase flow, which ensures the lowest friction to customers.
Coming soon
Support for multi-step checkout will be added in a future release.

Prerequisites recap

Before integrating Express Checkout, ensure the following prerequisites are met:
  1. 1.
    A Klarna payment solution is in place.
  2. 2.
    Access to the Klarna Partner Portal is available.
  3. 3.
    Inside the Klarna Partner Portal:
    1. 3.1.
      A client identifier has been generated with the domain URL allowlisted.
    2. 3.2.
      An API key has been generated.
    3. 3.3.
      The client identifier, its allowed origins and the API key all come from the same environment (test or production).
  4. 4.
    Klarna webhooks are registered for payment.request.state-change.completed events, as described in Set up your webhooks.
  5. 5.
    The Web SDK's browser storage has been disclosed to customers.
For a comprehensive, step-by-step walkthrough of these prerequisites, refer to the Express Checkout integration prerequisites.

Integration overview

The following is an overview of all the steps to add Express Checkout to a website:
  • Initialize the Klarna Web SDK using https://js.klarna.com/web-sdk/v2/klarna.mjs.
  • Display the 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 by calling authorizePaymentAPI with the klarna_network_session_token and purchase details. The following diagram outlines the interactions among different components:
%%{ init: { "theme": "base", "themeVariables": { "background": "#F9F8F5", "mainBkg": "#FFFFFF", "lineColor": "#2C2242", "fontFamily": "arial", "fontSize": "12px", "primaryColor": "#FFA8CD", "primaryTextColor": "#0B051D", "primaryBorderColor": "#C4C3CA", "secondaryColor": "#FFE9F3", "secondaryBorderColor": "#C4C3CA", "secondaryTextColor": "#0B051D", "tertiaryColor": "#E6FFA9", "tertiaryBorderColor": "#C4C3CA", "tertiaryTextColor": "#0B051D", "noteBkgColor": "#FFE9F3", "noteBorderColor": "#FFE9F3", "noteTextColor": "#0B051D", "errorBkgColor": "#d38373", "errorTextColor": "#0B051D", "nodeBorder": "#E6FFA9", "actorBkg": "#FFA8CD", "actorBorder": "#C4C3CA", "actorTextColor": "#0B051D", "actorLineColor": "#C4C3CA", "signalColor": "#0B051D", "signalTextColor": "#0B051D", "labelBoxBkgColor": "#805467", "labelBoxBorderColor": "#805467", "labelTextColor": "#FFFFFF", "loopTextColor": "#0B051D", "activationBorderColor": "#805467", "activationBkgColor": "#E6FFA9", "sequenceNumberColor": "#F9F8F5" }, "sequence": { "messageFontSize": 10, "actorFontSize": 14, "noteFontSize": 9, "noteAlign": "left" } } }%% sequenceDiagram participant C as Customer participant P as Partner participant K as Klarna P->>K: Initialize Klarna SDK P->>C: Display Klarna payment button C->>K: Click Klarna payment button K->>P: Trigger initiate callback alt Server-side payment request (preferred) P->>K: POST /v2/payment/requests Note over P,K: amount<br/>currency<br/>supplementary purchase data (if applicable) K->>P: Return payment request id P->>K: Return payment request id to Klarna SDK else Client-side payment request P->>K: Send payment request via SDK Note over P,K: amount<br/>currency<br/>supplementary purchase data (if applicable) end K->>C: Start Klarna purchase journey C->>K: Enter Klarna purchase flow opt Collect shipping details: shippingConfig.mode="EDITABLE" C->>K: Select shipping address K->>P: shippingaddresschange event P->>K: Return a list of applicable shipping options K->>C: Display shipping options C->>K: Select shipping option K->>P: shippingoptionselect event P->>K: New purchase details (amount, line items) end C->>K: Reviews and approves the purchase K->>P: Payment request completed event Note over K,P: klarna_network_session_token, shipping opt Web SDK payment complete event K->>P: Payment request complete callback Note over P,K: klarna_network_session_token, shipping end P->>K: Authorize payment Note over P,K: klarna_network_session_token K->>C: Redirect customer to the returnUrl

Integration details

The Klarna Web SDK (klarna.mjs) follows the JavaScript module approach and should be included where a reference to the SDK is needed, such as while rendering any components or initiating a payment flow. Always load the Web SDK from https://js.klarna.com/web-sdk/v2/klarna.mjs to remain compliant. Avoid including the script in a bundle or hosting it independently. Use this same URL in both the test and the production environment: the Web SDK reads the client identifier, and with a test client identifier (starting with klarna_test_) it connects to the test environment and loads the rest of its files from js.playground.klarna.com.
Use the clientId to initialize the SDK.
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
ParameterPresenceDescription
clientIdrequiredA credential that identifies the Partner, acquired through Klarna Partner Portal.
productsoptionalArray to specify which products to load for optimal performance. This reduces the amount of data needed to download. For example, only loading PAYMENT will exclude the CUSTOMER product.
localeoptionalLanguage 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 the Klarna Web SDK reference.
Recommended for integration
Important implementation details
  • The script should always be loaded on the 1st-party context, never inside an iframe, to ensure the purchase flows work as expected.
  • Ensure the products are properly specified during initialization for the best performance outcome.
Integration requirement
Legal notice When using the Klarna Web SDK, the Partner is responsible for informing customers about the tracking technologies it uses. Learn more about how to disclose this on the site.
Display the Klarna payment button early in the shopping journey and provide customers with the option to skip ahead when they are ready to purchase. High-impact placements include the product detail page, cart page, and checkout page.
undefined
undefined
undefined
Klarna payment button in product detail pageKlarna payment button in cartKlarna payment button in checkout

Klarna payment button variants

Choose the theme and shape of the payment button to best fit the Partner's online store in a way that complements the 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:
ParameterDescription
idSets a custom DOM ID on the rendered button. Useful for testing or styling.
shapeDefines the button's shape. Possible values are:default, pill, rect
themeSets the visual theme of the button. Possible values are: default, light, dark, outlined
localeSets the language and region (for example, en-US). When this is not set, the value chosen during initial Web SDK setup is used automatically. When that is also not available, the browser's settings are used instead.
disabledDisables the button when set to true. Useful during form validation or async operations.
loadingForces the button into a loading state. Useful when awaiting async setup or validation.
intentSets the purpose of the payment (PAY, SUBSCRIBE, ADD_TO_WALLET). Used to personalize the button and flow if not set when creating the PaymentPresentation instance.
initiateFunction that returns a Promise resolving to either a PaymentRequestData, a paymentRequestUrl, a paymentRequestId, or a returnUrl. This will be handled differently depending on the integration path.
initiationModeDefines how Klarna launches the Klarna Purchase Journey. When a shippingaddresschange or shippingoptionselect handler is registered, REDIRECT is not supported and the Web SDK throws a validation error; with DEVICE_BEST (the default) the Web SDK opens the journey on the page instead of redirecting.
Sample code
JAVASCRIPT
1 2 3 4 5 6 7 8 9
const buttonConfig = { id: "klarna-payment-button", shape: "pill", // "default" || "rect" theme: "default", // "dark" || "light" || "outlined" intent: "PAY", initiationMode: "DEVICE_BEST", // "ON_PAGE" || "REDIRECT" initiate: () => { /** Implement the initiate method **/ } };

Mount Klarna payment button

Finally, mount the button inside the appropriate container:
JAVASCRIPT
1 2
klarna.Payment.button(buttonConfig).mount("#klarna-button-container");
Automatic button interaction
The button will automatically handle customer interaction and trigger the Klarna purchase flow via the initiate function.
To launch the purchase flow, the initiate callback on the Klarna payment button interface must be implemented. 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 the Klarna server.
The data can be submitted on the client side or by creating a Payment Request on the backend side.
Recommended for integration
Important Submitting Payment Request data on the client side introduces security risks, as updates originating from the client can be tampered with or spoofed. When this approach is used, ensure robust safeguards are in place (for example, validating the Payment Request data on the server before authorizing the payment).
For industries that require supplementary purchase data beyond standard fields (for example, airlines, lodging), a server-side submission approach is mandatory to ensure data integrity and compliance.
ParameterPresenceDescription
currencyrequiredCurrency in ISO 4217 format. Supported currencies: AUD, EUR, CAD, CZK, DKK, HUF, MXN, NZD, NOK, PLN, RON, SEK, CHF, GBP, USD.
amountrequiredTotal amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions.
supplementaryPurchaseDataoptionalAdditional details about the transaction that reduce fraud risk and improve transparency. Client-side (Web SDK) submission supports only purchaseReference, lineItems, shipping, customer, subscription, and ondemandService. Industry and regulated packages, such as travel_reservations, lodging_reservations, event_reservations, vouchers, insurances, and marketplace_seller_details, must be submitted server-side. See Supplementary purchase data.
For the full API specifications, refer to Payment.button in the Klarna Web SDK reference.

Create Klarna Payment Request on the server side

Creating a Payment Request on the server side is the recommended approach. After creation, return the Payment Request URL (paymentRequestUrl) from the initiate callback. Returning the Payment Request ID (paymentRequestId) also works.
Client code
JAVASCRIPT
1 2 3 4 5 6 7 8 9 10
const klarnaPaymentButton = klarna.Payment.button({ initiate: async () => { // Send whatever your server needs to build the payment request (cart ID, items, ...). 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();
For the full API specifications, refer to Payment.button in the Klarna Web SDK reference.
Server code
JAVASCRIPT
1 2 3 4 5 6 7 8 9 10
// 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'; // Test environment: https://api-global.test.klarna.com const KLARNA_BASE_URL = 'https://api-global.klarna.com';
For the full API specifications, refer to the API referenceAPI.
Avoid reusing payment requests
Create a new Payment Request on every button click instead of reusing Payment Requests.
ALTERNATIVE: Create Klarna Payment Request on the client side
This approach allows data to be sent to Klarna directly from the client. Return the Payment Request payload as follows:
TYPESCRIPT
1 2 3 4 5 6 7 8 9 10
const klarnaPaymentButton = klarna.Payment.button({ initiate: () => { return { currency: "USD", amount: 1000, paymentRequestReference: "pay-ref-123", supplementaryPurchaseData: { purchaseReference: "pay-ref-123", lineItems: [], shipping: [],
For the full API specifications, refer to Payment.button in the Klarna Web SDK reference.

OPTIONAL: Collect shipping details

Digital goods exception
This section can be ignored when selling digital goods.
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 Partner'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.
undefined
undefined
Display shipping bannerDisplay 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.
To restrict the countries to which shipping is offered, include the supported_countries attribute with a list of permitted countries. By default, all Klarna-supported countries are available unless specified otherwise.
When the Payment Request is created on the server (the recommended approach in Step 3), add shipping_config to it. The client code stays the same: the initiate callback still returns the paymentRequestUrl from the server.
JS
1 2 3 4 5 6 7 8 9 10
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: [],
The collected shipping data will be available when the Payment Request is completed. See Monitor payment status for more information.
ParameterPresenceDescription
shippingConfig.moderequiredValues: "EDITABLE", "READ_ONLY". Configure if the shipping details should be collected from the customer. If mode is set to EDITABLE then the shipping details will be collected from the customer and will be available under stateContext.shipping when the Payment Request is in state COMPLETED. If mode is set to READ_ONLY, dynamic shipping options and address validation are not available on that Payment Request.
shippingConfig.supportedCountriesoptionalPartner's supported shipping countries (ISO 3166-1 alpha-2)
For the full API specifications, refer to Payment.button in the Klarna Web SDK reference.
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.
Integration requirement
The shipping event handlers only work when the Klarna Purchase Journey opens on the Partner's page, because the page has to stay open to answer them. While a shippingaddresschange or shippingoptionselect handler is registered, initiationMode: "REDIRECT" is rejected with a validation error. With DEVICE_BEST (the default), the Web SDK opens the journey on the page instead of redirecting, including on mobile devices where it would otherwise redirect.
To enable proper functionality of the shipping options integration, the integrator must handle two event callbacks: shippingaddresschange and shippingoptionselect. These events allow the integrator to communicate available shipping options after an address is selected, enabling the customer to choose from the provided options.
Handle shipping address change events
ParameterPresenceDescription
cityrequiredCity/town
postalCoderequiredPostal code formatted according to country.
regionrequiredState/county/province/region formatted according to country. Mandatory for US and AU market. Validations according to ISO 3166-2 format, for example, US-OH, US-NJ, AU-ACT, etc.
countryrequiredCountry in ISO 3166-1 alpha-2 format.
The shipping address changed event handler is triggered when the customer changes their shipping address during the payment flow.
The shipping address returned has the following format:
JSON
1 2 3 4 5 6 7
{ "city": "San Francisco", "postalCode": "94107", "region": "CA", "country": "US" }
Limited address detail
The shipping address returned at this stage does not have specific address lines. It is only meant to allow the Partner to run validation logic. Detailed information will be returned after the customer approves the purchase.
When the shippingaddresschange event is triggered, the Partner is given the opportunity to accept or reject the shipping address. When delivery to the address is possible, return the shipping options. It is recommended to preselect a default shipping option for the provided address by returning the shipping option in the selectedShippingOptionReference property. The amount and lineItems properties should also be updated 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.
Response sample
JAVASCRIPT
1 2 3 4 5 6 7 8 9 10
klarna.Payment.on("shippingaddresschange", async (paymentRequest, shippingAddress) => { // Run validation logic to ensure you can deliver to the given address. // Return the shipping options, the default selected option and the updated order details. return { amount: 1500, lineItems: [ { name: 'Product 1', quantity: 1, totalAmount: 1000,
Integration requirement
The shippingaddresschange event is triggered immediately after the customer logs in to their account given they have an existing shipping address, and every time the customer updates the shipping address. The Partner should return the shipping options and updated payment data here. If nothing is returned within 10 seconds, the purchase flow ends in an error state.
For the full API specifications, refer to the shippingaddresschange event in the Klarna Web SDK reference.
Handle shipping option selection events
ParameterPresenceDescription
amountrequiredTotal amount of the shipping method selected by the customer. The value should be in non-negative minor units. Eg: 25 Euros should be 2500.
descriptionrequiredDescription of the type of shipping the customer has selected at the checkout. For example: "1 - 3 working days", "1 working day".
displayNamerequiredThe shipping option as selected by the customer at the Partner website.
shippingOptionReferencerequiredUnique reference to this shipping option. Required if the Payment Request contains multiple shipping objects. This can be any string, and does not have to correspond to a delivery or tracking number.
shippingTypeoptionalThe type of shipping option the customer selected. This can be:
  • TO_DOOR - Delivery to door
  • TO_CURB - Curb-side delivery
  • TO_MAILBOX - Best-effort mailbox delivery
  • PICKUP_BOX - Pickup at an unmanned designated pickup locker/box
  • PICKUP_POINT - Pickup at a manned pickup point
  • PICKUP_STORE - Pickup in-store
  • PICKUP_WAREHOUSE - Pickup at warehouse
  • DIGITAL_EMAIL - Digital delivery via email
  • DIGITAL_DOWNLOAD - Digital delivery via download
  • DIGITAL_OTHER - Other digital delivery
  • PHYSICAL_OTHER - Other physical delivery
When the customer selects a different shipping option, a shippingoptionselect event is received. The Partner is then expected to return the updated amount and lineItems properties to reflect the selected shipping cost. In rare cases when the shipping option is no longer available, the selection can be rejected.
JAVASCRIPT
1 2 3 4 5 6 7 8 9 10
klarna.Payment.on("shippingoptionselect", async (paymentRequest, shippingOption) => { // Update the payment request with new amount and line items for shipping return { amount: 1500, lineItems: [ // ...the order's other line items { name: 'shipping-option-1', quantity: 1, totalAmount: 500,
For the full API specifications, refer to the shippingoptionselect event in the Klarna Web SDK reference.
Integration requirement
The shippingoptionselect event is triggered every time a customer selects a different shipping option. The Partner should return updated payment data here. If nothing is returned within 10 seconds, the purchase flow ends in an error state.
Once the customer approves the request, the Payment Request enters the COMPLETED state and a klarna_network_session_token is delivered, 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 triggers the Payment Request to enter the COMPLETED state. Klarna then triggers a Payment Request state-change webhook to which the Partner must subscribe:
Event nameWhen
payment.request.state-change.completedTo track when Payment Requests reach the COMPLETED state.
From this request the klarna_network_session_token can be retrieved. It is needed to authorize the payment and complete the Express Checkout flow.
Once the webhooks are set up, they can be managed through API requests. Use these requests to update, delete, or retrieve details about the configurations.
Consult the API referenceAPI for comprehensive parameter information.
Shipping in the webhook payload
The shipping field is only included when the Payment Request asked Klarna to collect a shipping address.
Webhook payload sample
JSON
1 2 3 4 5 6 7 8 9 10
{ "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",

OPTIONAL: Listen to Web SDK events

On the frontend, the complete, abort and error events can be observed. When the customer successfully completes the purchase flow, the Payment Request's status changes to COMPLETED, and the Klarna Network Session Token can then be retrieved.
JAVASCRIPT
1 2 3 4 5 6 7 8 9 10
klarna.Payment.on("complete", async (paymentRequest) => { // The customer has successfully completed the payment flow and // the payment request can be confirmed using the Klarna Network Session Token. }); klarna.Payment.on("error", (error) => { // Starting the purchase flow failed, for example because the initiate callback // threw or the payment request could not be created. Not called when the // customer closes the purchase flow (that's "abort"). });
Sample paymentRequest callback
JSON
1 2 3 4 5 6 7 8 9 10
{ "paymentRequestId": "krn:payment:eu1:request:64be490f...", "state": "COMPLETED", "stateContext": { "klarnaNetworkSessionToken": "krn:network:eu1:live:session-token:e15432a5-ebcc-45bc-934c-e61399db597b", "shipping": { "recipient": { "givenName": "Klara", "familyName": "Test", "email": "recipient@email.us",
For the full API specifications, refer to the complete event in the Klarna Web SDK reference.
Integration requirement
Important Relying on Web SDK events alone leads to a high number of abandoned Payment Requests. Always use this approach in combination with the webhooks to ensure the best conversion rate.
Once the klarna_network_session_token is retrieved, call Klarna's authorizePaymentAPI to finalize the payment. Pass the token in the Klarna-Network-Session-Token header of the authorize request, along with the final amount, currency, and any supplementary purchase data.
For the full request and response specifications, refer to the authorizePayment API referenceAPI.
Send the final values on the authorize call: the final amount, line items and the shipping address the customer chose, which arrives as shipping on the completed Payment Request. When the amount differs from the Payment Request, Klarna asks for approval of the new amount, and sending the final values keeps the transaction eligible for the merchant protection program. Include step_up_config with customer_interaction_config.method = HANDOVER and a return_url. A step-up is unlikely after a completed Express Checkout, but the block lets Klarna recover the cases that need one.
Use the Express Checkout token
Authorize with the Klarna Network Session Token that Express Checkout issued. Don't discard it or create a new Payment Request for the same purchase: the token carries the customer's confirmation of payment and shipping, and authorizePaymentAPI is the only call that follows a completed one-step Express Checkout.
Related articles
Set up your webhooks
Express Checkout integration prerequisites
Web Sdk
1. General
Checkout Styling
API & SDK references
API
Support
Partner support•Service Status
Cookies|Terms & Conditions|Copyright Klarna AB 2026
Jump to section...