Skip to content
/
Client Side Events
Last updated

Client-side events

The KCO JavaScript API allows the parent page to invoke actions and receive events from the Checkout iFrame. It can be used to receive user information and refresh the iFrame when server-side updates have been processed.

How it’s done - Accessing the JavaScript API

The JavaScript API is available as an object retrieved via the window._klarnaCheckout method. It's accessible after the Checkout iframe is rendered.

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

Note: Data received from the JavaScript API should only be used for presentation or to trigger actions. Integrations should use the Checkout Backend API for fetching data.

Checkout actions

Two supported actions: suspend and resume.

Suspend and Resume

This enables the parent page to interact with the Checkout iframe. When a server-side Kustom call is in progress, suspend prevents the user from changing the order, making the iframe unresponsive. resume reactivates user interaction after the server call completes. suspend will automatically resume after 10 seconds, which is configurable.

Example usage (suspend and resume):

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

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

Disable Auto Resume

To prevent automatic resume after 10 seconds:

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

Checkout events

Registering listeners

Listeners are registered using api.on(). Each key is an event name, and the value is the callback function.

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

The "load" event

Triggered when the KCO iframe is rendered.

{
  "customer": {
    "type": "person"
  },
  "shipping_address": {
    "country": "swe",
    "postal_code": "16972"
  }
}
  • customer.type: "person" or "organization"
  • shipping_address.country: Alpha3 country code
  • shipping_address.postal_code: Postal code

The "user_interacted" event

Triggered when the user interacts with the KCO iframe.

{
  "type": "mousedown" // or "keydown"
}

The "customer" event

Triggered when KCO detects or changes customer type.

{
  "type": "person"
}

The "change" event

Triggered when the user changes billing address details (postal code, country, email, etc.) except in AT and DE.

{
  "email": "klara.joyce@klarna.com",
  "postal_code": "12345",
  "country": "deu"
}

Note: Customer data may not be fully populated in the data object. Some fields might be prefilled or obfuscated.

The "billing_address_change" event

Triggered when KCO detects a valid billing address.

{
  "postal_code": "75511",
  "country": "aut"
}

The "shipping_address_change" event

Triggered when a valid shipping address is detected. Shipping address is usually the same as the billing address unless specified otherwise.

{
  "postal_code": "75511",
  "country": "aut"
}

The "shipping_option_change" event

Triggered when a shipping option is selected. Data includes price, tax_amount, and tax_rate 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" event

Generic error event triggered when updating shipping.

{}

The "order_total_change" event

Triggered when the order total changes. Data includes the new total in minor units.

{
  "order_total": 6000
}

The "checkbox_change" event

Triggered when a checkbox is checked/unchecked.

{
  "key": "additional_merchant_terms_checkbox",
  "checked": true
}

The "can_not_complete_order" event

Triggered when the merchant needs to provide alternative payment options. (e.g. customer declined credit).

{}

The "network_error" event

Triggered if a network issue is detected.

{}

The "redirect_initiated" event

Triggered when the user is about to be redirected to the confirmation page.

true

The "load_confirmation" event

Triggered when the KCO confirmation page renders.

{}

The "validation_callback" event

Triggered when the user clicks Buy before the server request. Use this event to run client-side validations. You must call the provided callback with a should_proceed value (true or false) within 10 seconds.

Note: data is always an empty object in this event. It is included only to maintain the expected handler signature and will not contain any values.

For this feature to work, set options.require_client_validation to true when creating the checkout order. See the create checkout order documentation for details.

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