Klarna Docs - Client-side events

Client-side events

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 some user information and refreshing the iFrame when server side updates have been processed.

How it’s done - 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.

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

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.

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.

JAVASCRIPT
// 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:

JAVASCRIPT
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.

JAVASCRIPT
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.

JSON
{
  "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 “user_interacted” event

The user_interacted event is triggered whenever the user interacts with the KCO iframe either by clicking or typing.

JSON
{
  "type": "mousedown" // or "keydown" depending on the user interaction
}

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.

JSON
{
  "type": "person"
}

The “change” event

The change event is triggered when the user changes postal code, country or email in their billing address. It is also triggered for given/family name except in the AT & DE markets.

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.

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.

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 a shipping options object with price, tax_amount, and tax_rate is expressed in minor units (e.g. cents).

JSON
{
    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).

JSON
{
  "order_total": 6000
}

The “checkbox_change” event

The checkbox_change event is triggered everytime a checkbox is checked/unchecked.

The event data contains an object with the checkbox key and if the checkbox was checked or unchecked.

JSON
{
  "key": "additional_merchant_terms_checkbox", // the same the merchant sends to KCO on the id property for the [additional checkboxes](https://developers.klarna.com/api/#checkout-api__create-a-new-orderoptions__additional_checkbox)
  "checked": true // or false depending if the checkbox has been checked or unchecked
}

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.

JSON
{}

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.

JSON
{}

The “redirect_initiated” event

The redirect_initiated event is triggered after the user has completed all the required steps to complete the purchase and is about to get redirected to the confirmation page.

The event data is always true.

JSON
true

The “load_confirmation” event

The load_confirmation event is triggered whenever Klarna confirmation page has rendered for a customer within its iFrame.

The event data is an empty object.

JSON
{}

The “validation_callback” event

If you send this property options.require_client_validation as true while creating the order, the client will give you the chance to do some client validations after the validation_callback event is triggered.

The validation_callback event is triggered when the user clicks the buy button and before the client requests the server to process the purchase.

The event data is an empty object:

JSON
{}

You will also receive a callback function as a second parameter in the event function, as you can see in the example below.

After the validation_callback event, you should do your validations and then execute the callback function received as a second parameter, telling us if we should proceed with the purchase or not by sending should_proceed: true or should_proceed: false.

If you don’t execute the callback within 10 seconds, we will continue with the purchase either way.

JAVASCRIPT
api.on({ 'validation_callback': function (data, callback) {
    callback({ should_proceed: true, message: 'Sorry, your shipping address is not supported.' })
}})

The message attribute is optional. If it is provided, KCO will render it in a dialog.

In case an order update is required, you should respond with should_proceed: false and do as usual; suspend, update & resume. Otherwise purchase flow will be broken, creating a not so good user experience.

Be careful not to create an infinite loop. E.g. If you are taking update decisions based on a field that can't be changed, you might create a loop of denying the validation, executing updates, and denying the validation again as your update was not effective.

If you need to force the client to wait for your answer instead of continuing with the purchase after 10 seconds, then you also need to pass options.require_client_validation_callback_response as true while creating the order.

Use options.require_client_validation_callback_response with caution, if your webpage never execute the callback the user will be stuck with a loading checkout screen.