Checkout JavaScript API

The Klarna Checkout JavaScript API allows the parent page to invoke actions and to receive events from the Checkout iFrame. It can be used to receive user information for retargeting purposes and refreshing the iFrame when server side updates have been processed.

Note that the data recieved from the JavaScript API should only be used for presentational purposes or to trigger other actions. Integrations should only be done with data fetched from the Checkout Backend API.

Accessing the JavaScript API

The JavaScript API is provided in an object that is retrieved via the method window._klarnaCheckout, registered on the page where the snippet is loaded. The API is accessible once the Checkout iframe has been rendered in the user’s browser.

1
2
3
window._klarnaCheckout(function(api) {
  // Invoke method or register listener
});

Checkout actions

There are only two supported actions on Klarna Checkout. Suspend, and resume.

Suspend and Resume

This functionality enables the parent page to interact with the Checkout iframe. When a server side call to Klarna is being processed, to prevent the user/customer from altering the state of their Checkout order, the parent page can trigger the suspend action. The suspend action will turn the checkout iframe unresponsive to user interractions.

After the server side call to Klarna has been processed, the parent page is required to trigger resume to once again let the user to interact with Klarna Checkout. As a safe-guard a suspend will automatically resume after 10 seconds. This can be overridden, see below.

A use case for this feature is when the user wants to add more items to the cart. This requires a server side call to Klarna to update the items in the order. While the server side request is being sent and processed the checkout should be suspended.

1
2
3
4
5
6
7
8
9
// Suspending the checkout
window._klarnaCheckout(function (api) {
  api.suspend();
});

// Resuming the checkout
window._klarnaCheckout(function (api) {
  api.resume();
});

Disable Auto Resume

If you do not want the api.resume call to automatically be made after 10 seconds:

1
2
3
4
5
6
7
window._klarnaCheckout(function (api) {
  api.suspend({ 
    autoResume: {
      enabled: false
    }
  });
});

Checkout events

Registering listeners

Listeners are registered by passing an object to the api.on() method on the api object. Each key corresponds to an event name and the value should be the callback function. Only one listener can be registered for each event. Registering a new listener will overwrite the old.

1
2
3
4
5
6
7
window._klarnaCheckout(function(api) {
  api.on({
    'change': function(data) {
    // Do something
    }
  });
});

The “load” event

The load event is triggered whenever Klarna Checkout has rendered for a customer within its iFrame.

1
2
3
4
5
6
7
8
9
{
  "customer": {
    "type": "person",
  },
  "shipping_address": {
    "country": "swe",
    "postal_code": "16972"
  }
}

customer.type: Either string “person” or “organization” shipping_address.country: Country identifier in Alpha3 format shipping_address.postal_code: Postal code without whitespaces

The “customer” event

The customer event is triggered whenever Klarna Checkout has detected the customer type or a customer type change. Currently “organization” and “person” are the two supported types.

1
2
3
{
  "type": "person"
}

The “change” event

The change event is triggered when the user changes postal code or country in their billing address.

1
2
3
4
5
{
  "email": "klara.joyce@klarna.com",
  "postal_code": "12345",
  "country": "deu"
}
1
2
3
4
5
6
7
{
  "email": "klara.joyce@klarna.com",
  "postal_code": "16972"
  "country": "swe",
  "given_name": "Klara",
  "family_name": "Joyce",
}

The data returned is not guaranteed to be in the data object. As an example, customer gets prefilled by Klarna and some data gets obfuscated. Obfuscated data is not sent through the API.

The “billing_address_change” event

The billing_address_change event is triggered when Checkout has detected a complete and valid billing address for the customer.

1
2
3
4
{
  "postal_code": "75511",
  "country": "aut"
}
1
2
3
4
5
6
7
{
  "given_name": "Klara",
  "family_name": "Joyce",
  "email": "klara.joyce@klarna.com",
  "postal_code": "12345",
  "country": "usa"
}

The data returned is not guaranteed to be in the data object. As an example, customer gets prefilled by Klarna and some data gets obfuscated. Obfuscated data is not sent through the API.

The “shipping_address_change” event

The shipping_address_change event is triggered when Checkout has detected a complete and valid shipping address for the customer. The shipping address will always be the same as billing address, unless a separate shipping address has been provided by the customer.

1
2
3
4
{
  "postal_code": "75511",
  "country": "aut"
}
1
2
3
4
5
6
7
{
  "given_name": "Klara",
  "family_name": "Joyce",
  "email": "klara.joyce@klarna.com",
  "postal_code": "12345",
  "country": "usa"
}

The data returned is not guaranteed to be in the data object. As an example, customer gets prefilled by Klarna and some data gets obfuscated. Obfuscated data is not sent through the API.

The “shipping_option_change” event

The shipping_option_change event is triggered when the customer has selected a new shipping option.

The event data contains an shipping options object with price, tax_amount, and tax_rate is expressed in minor units (e.g. cents).

1
2
3
4
5
6
7
8
9
{
    description: "We will send you a ticket to travel around the world with your goods",
    id: "crazydeal",
    name: "Around the World",
    price: 99999, // cent
    promo: "TODAY ONLY! Fly around the world for FREE* *not actually free",
    tax_amount: 7621, // cent
    tax_rate: 825 // cent
}

The “order_total_change” event

The order_total_change event is triggered when the order total has changed.

The event data contains an object with the order total, expressed in minor units (e.g. cents).

1
2
3
{
  "order_total": 6000
}

The “can_not_complete_order” event

The can_not_complete_order event is triggered when the merchant has to provide other means of paying. A normal case when this happens is when only Credit payment options are available but the customer was refused credit.

The event data is an empty object.

1
{}

The “network_error” event

The network_error event is triggered when a network issue has been detected, which could basically mean that the customer has lost internet connection.

The event data is an empty object.

1
{}