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.

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

There are only two supported actions on KCO. 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 KCO. 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.

// Suspending the checkout
window._klarnaCheckout(function (api) {
  api.suspend();
});

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

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

window._klarnaCheckout(function (api) {
  api.suspend({ 
    autoResume: {
      enabled: false
    }
  });
});

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.

window._klarnaCheckout(function(api) {
  api.on({
    'change': function(data) {
    // Do something
    }
  });
});

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

{
  "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 is triggered whenever the user interacts with the KCO iframe either by clicking or typing. This event will only be triggered for the first interaction.

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

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

{
  "type": "person"
}

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 KCO and some data gets obfuscated. Obfuscated data is not sent through the API.

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 KCO and some data gets obfuscated. Obfuscated data is not sent through the API.

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 KCO and some data gets obfuscated. Obfuscated data is not sent through the API.

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

{
    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 shipping_address_update_error is a generic error that is triggered whenever something goes wrong when updating shipping methods/options.

The event data is an empty object.

{}

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

{
  "order_total": 6000
}

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.

{
  "key": "additional_merchant_terms_checkbox", // the same the merchant sends to KCO on the id property for the [additional checkboxes](https://docs.klarna.com/api/api-urls/#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 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.

{}

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.

{}

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.

true

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

The event data is an empty object.

{}

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:

{}

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.

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

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.

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.