Klarna Docs - Load the Klarna widget

Load the Klarna widget

How to go forward with this implementation

Klarna uses a widget to display available Klarna payment options to the customer. To allow this, you will need to render it on your checkout page alongside any other payment methods you may offer. This is done by first initializing it and then loading the widget.

The Klarna widget is rendered using our JavaScript SDK. This SDK is documented in-depth in the JavaScript reference page.

Best practice: You are able to define what payment methods you want to display in the widget. Be sure to think of how to display them in a way that is aligned with the design of your checkout!

Add the Klarna JavaScript SDK by including the following script in the body section on your checkout page

window.klarnaAsyncCallback = function () {

  // This is where you start calling Klarna's JS SDK functions
  // Klarna.Payments.init({....})

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

The JavaScript SDK itself does not have to be installed beforehand. You just need to include the above script in your HTML that will load the SDK into your pages.

Initialize the JavaScript SDK by calling init, passing the client_token that was returned when you created the session in the previous step.

Note The client_token does not have any defined expiry time.

client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH'

To specify where to place the widget, add a page container on your checkout page.

Note: The Klarna widget requires a minimum width of 280px.

<div id="klarna-payments-container"></div>

You can get more insight in how the Klarna widget could be placed in the checkout at our demo store.

The name and the Klarna logo placement are managed outside of the Klarna widget. You can use the name and asset_urls provided with the create session response and follow the example shown above when adding the widget in your checkout.

Best practice: You are able to customize the look and feel of the widget according to your style guide. Read more about it here.

For more inspiration of how to use the widget in the right way for your shop, go to the get smoooth handbook.

Load the Klarna widget using the load call. Pass the id of the container you just added and specify payment_method_category. The payment_method_category specifies which of Klarna’s customer offerings (e.g. Pay now, Pay later or Slice it) that is being shown in the widget. See the JavaScript reference page for further details.

For a description of what categories that exist and what is included in them, please visit the payment method availability page.

The available payment_method_categories for the current session were provided in the response of the create session call.

  container: '#klarna-payments-container',
  payment_method_category: 'pay_later'
}, function (res) {

Best practice: The load function should be called when rendering your checkout page. That way you can ensure that the widget has loaded in full by the time the customer wants to interact with it or selects Klarna as a payment method.

When the JavaScript SDK has processed the load call, the provided callback will be invoked. The callback argument will be an object containing the following properties:

  • show_form:true/false indicates whether you should make the Klarna option available in your checkout or if this option should not be available for this order
  • error contains details of potential error messages

We know that you want to give customers a great checkout experience. Therefore we have created a functionality that quickly alerts your store when a customer cannot use any of the payment methods in the Klarna widget. This is done through the show_form:true/false field, which is used as a response flag to the load call.

The field indicates whether your store may show the Klarna option or not. This boolean is a part of all callbacks, except for re-authorize. Best practice is therefore that you listen to it all the time.

There are three potential cases that you need to handle based on these response flags:

  1. Positive response: Klarna Payments is offered
  2. Fixable error response: Adjust and try again
  3. Negative response: Klarna Payments not offered

If show_form: true, and there are no errors in the object returned, Klarna renders the payment options available to the customer in the widget.

This is the standard response, unless the customer is rejected.

show_form: true

If show_form: true is received together with an error, something fixable is wrong and the consumer needs to take action before moving forward. Klarna will inform the consumer about the details of the error in the widget. Optionally, you can interpret the invalid fields in the error message and take appropriate actions on your checkout page. See our JavaScript SDK reference page for further information.

show_form: true,
error: {
  invalid_fields: [
    billing_address.email	]

Example of adjustable error

If show_form: false, the payment method in the loaded widget will not be offered for this order based on Klarna’s pre-assessment. A rejection message is displayed to the consumer in the Widget.

show_form: false

When Klarna returns a show_form: false, your store cannot offer the selected payment method to this customer. You indicate that by setting up one of the following visual arrangements:

  1. Hide the Klarna option from the checkout.
  2. Grey out the Klarna option and disable clicking.
  3. Keep the Klarna option and accept an error message in the widget. Klarna will inform the consumer that this option is not available.

There are two ways of propagating cart updates to Klarna. The first is to update the session and the second is to do a load with new details. There is no difference in how the updates are treated, no matter what way you do it. Although the effects of the update is only shown to the consumer in the Klarna widget if a load is done.

Thus you may use load to pass any updates to the Klarna session that might have occurred since the session was created. In the following example, the order information has changed since the consumer has added an item to the cart.

container: "#klarna_container",
payment_method_category: 'pay_later'
}, {
  "purchase_country": "GB",
  "purchase_currency": "GBP",
  "locale": "en-GB",
  "order_amount": 20,
  "order_tax_amount": 0,
  "order_lines": [{