Klarna Docs - Integrate multistep Express checkout

Integrate multistep Express checkout

Learn how to integrate the multistep Express checkout to support more robust checkout options.

Follow the web integration guide to add the multistep Express checkout to your website.

Not sure if the multistep checkout is the best option for your store? Refer to the Before you start article to make sure you offer your customers the best checkout experience.

The process of creating a multistep Express checkout consists of six main steps:

  1. Initializing and display the Express checkout button
  2. Handling the authorization response
  3. Initializing Klarna payments JavaScript SDK in checkout
  4. Finalizing the authorization
  5. Handling finalization callback
  6. Creating an order

Load the Klarna payments JavaScript library when the cart page or a product detail page is loaded. Ensure the library is included only once to prevent conflicts.

HTML
<script defer
  src="https://x.klarnacdn.net/kp/lib/v1/api.js">
</script>

Then, implement the klarnaAsyncCallback function where you initialize the Express checkout. Implement the klarnaAsyncCallback before importing the library. This way you ensure it will be invoked when the library is loaded. Within klarnaAsyncCallback, include the logic to: 

  1. Initialize Klarna’s JavaScript SDK providing your client identifier as client_id, get your client_id from the Merchant portal. Refer to the Before you start article for instructions on how to generate your client_id .
  2. Load the button in a chosen container using a load() function. To help debug any issues that occur when loading the button, implement the load() callback.
  3. Handle the on_click event, in which you start the payment authorization process by calling the authorize() function. Keep the following best practices in mind:
  • When initiating the authorization, make sure that the format of the orderPayload is the same as the body of the request to create a Klarna payments session. 
  • Avoid having multiple nested asynchronous calls before invoking authorization.

The orderPayload object can contain all information allowed in the Klarna payments API, for example, merchant references, merchant URLs, or extra merchant data. 

Here’s an example of code that initializes the Klarna JavaScript library and renders the Express checkout button on a cart or a product detail page:

HTML
<script defer
  src="https://x.klarnacdn.net/kp/lib/v1/api.js">
</script>

<script>
  window.klarnaAsyncCallback = function () {
    window.Klarna.Payments.Buttons.init({
      client_id: 'klarna_client_test...',
    }).load(
    {

The table below lists the attributes of the load() function’s configuration object.

AttributeRequiredDescription
containerYescontainer represents the location where you want the Express checkout button to be displayed.
In this attribute, you can specify either:
  • a CSS selector, for example, #my-component-id, .my-component-class
  • an element-type object directly, for example, document.createElement('div')
on_clickYesThe function passed in this attribute will be executed when the Express checkout button is clicked. It will receive the authorize() function, which has to be invoked to start the Express checkout flow.
The authorize() function acts similarly to authorize() in a standard Klarna payments integration.
themeNoThe color theme of the button.
The possible values are default, light, and dark. If the value isn't specified, default is used.
shapeNoThe shape of the button.
The possible values are default, rect, and pill. If the value isn't specified, default is used.
localeNoThe language of the button text. If not specified, the browser's language will be used. 

The value of locale passed in the authorize() function’s configuration object defines the language of the button text. On the other hand, the value of locale passed to authorize() inside the orderPayload defines the language of the purchase flow. Learn more about locale formats in Klarna APIs.

The table below lists the attributes for the authorize() function’s configuration object.

AttributeRequiredDescription
collect_shipping_addressYesInforms Express checkout whether you need the customer's shipping address from Klarna. 
The default value is false.
auto_finalizeNoAllows you to specify whether the authorization should automatically be finalized when the user clicks the Express button.
In multistep Express checkout, make sure to always set auto_finalize to false to keep the authorization process open until the purchase is finalized. The default value is true.

In the multistep checkout, after the customer completes the first step, you’ll receive the authorize() call response with the finalize_required flag set to true and the client_token necessary to resume the authorization at checkout. 

Redirect the customer to the checkout and pre-fill all necessary fields with the customer data returned in the authorize() response call.

JAVASCRIPT
{
  "show_form": true,
  "approved": true,
  "finalize_required": true,
  "client_token": "1eddf502-f3a0-45bf-b1fd-f2e3a2758200",
  "session_id": "e4b81ca2-0aae-4c16-bcb2-29a0a088a35b", 
  "collected_shipping_address": { // if collect_shipping_address was set to true
    "attention": "Attn",
    "city": "London",
    "country": "GB",

An example of a response from the client-side authorize() call.

When the customer navigates to another page or reloads the current one, you need to initialize the Klarna payments library with the client_token you got from the authorization response. This will keep the authorized session open.

JAVASCRIPT
<script>
  window.klarnaAsyncCallback = function () {
// Here is where you start calling Klarna's JavaScript SDK functions
Klarna.Payments.init({
       	client_token: "your-client-token",
});
// Here is where you start calling Klarna.Payments.finalize({}
</script> 
<script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>

An example of Klarna's JavaScript SDK and a call that initializes the SDK on the checkout page.

To authorize the purchase, you need the authorization_token. To get the authorization_token, call the Klarna.Payments.finalize() function during the final purchase step. 

If changes were made in the order payload, for example, to the order amount or shipping address, you have to submit them when calling Klarna.Payments.finalize().

JAVASCRIPT
Klarna.Payments.finalize({}, orderPayload, function (res) {
          // res = {
          //   show_form: true,
          //   approved: true,
          //   authorization_token: "b4bd3423-24e3",
          //   collected_shipping_address: {...}
          // }
        });

An example of a Klarna.Payments.finalize() call.

If the purchase is authorized successfully, you’ll receive the authorization_token in the client-side finalize() response, the authorization callback, or by getting the payment details from Klarna payments API. You need the authorization_token to create an order in the final step.

Here’s an example of a response from the client-side authorize() function:

JAVASCRIPT
{ 
"show_form": true, 
"approved": true, 
"finalize_required": false, 
"authorization_token": "0eb73d2c-d55a-5358-9080-ddc3903e3941",
"session_id": "e4b81ca2-0aae-4c16-bcb2-29a0a088a35b", 
}

Here’s an example of a response from the authorization callback:

JAVASCRIPT
{
  "authorization_token": "1eddf502-f3a0-45bf-b1fd-f2e3a2758200",
  "session_id": "e4b81ca2-0aae-4c16-bcb2-29a0a088a35b",
}

Once you have the authorization_token, create the order. When creating the order, make sure the order payload is the same as the one sent in the finalize() call.