Web SDK integration

The simplest and fastest way to start using Sign in with Klarna is to use the minimal template below.

Please refer to the Before you start article for instructions on how to obtain your CLIENT_ID .

Sign in with Klarna ideally will start in a Popup window to avoid users leaving the merchant's website. However, due to various reasons popup window can be blocked. Thus, having a redirect callback page is REQUIRED to allow users to continue their sign in flow in case their popup is blocked. You can use the callback.html template provided in the example above.

The Sign in with Klarna flow can be initiated in two main modes: DEVICE_BEST or REDIRECT .

DEVICE_BEST (default)

DEVICE_BEST allows Web SDK to automatically decide the most suitable mode, based on user's device configurations. For instance, Web SDK may opt for a REDIRECT if popup blockers are enabled or the page is loaded in an web frame.

By default, DEVICE_BEST mode starts the flow in a popup window for web browsers. This is ideal for merchants who don't want their customers to leave their website. However, if the popup is blocked, Web SDK will switch to REDIRECT mode and the user will be redirected to the login page on the current tab.

REDIRECT

REDIRECT mode redirects the user to the login page on the current tab. However, user will be redirected back to the merchant's redirect callback page at the end of the sign in flow with Authorization tokens or OAuth2Error parameters.

Please note that you can also just load the Web SDK script without the dataset attributes and use the init method to initialise the Web SDK.

<script defer src="https://js.klarna.com/web-sdk/v1/klarna.js"></script>
<script>
  window.onload = async function () {
    const klarna = await Klarna.init({
      clientId: "<YOUR CLIENT ID>",
      locale: "en-GB"
    });
  };
</script>

After initialising the Web SDK, all Sign in with Klarna related API can be found under the Identity namespace.

interface Identity {
  /**
   * Returns the button with given id
   *
   * If id is not provided, returns the first button instance
   *
   * If no button instance found returns undefined
   */
  button(id?: string): KlarnaIdentityButton | undefined;

Web SDK provides a flexible API that allows merchants to integrate Sign in with Klarna based on their preference.

Web SDK provides a default button that has all functionalities built-in and styled based on official Klarna design guidelines.

1.1. Using <klarna-identity-button /> element

Web SDK registers a custom web component klarna-identity-button, that renders the Sign in with Klarna button where it is mounted.

<klarna-identity-button
  id="klarna-identity-button"
  data-scope="openid offline_access payment:request:create profile:name"
  data-redirect-uri="http://localhost:3000/callback.html"
  ></klarna-identity-button>

1.2. Creating the button programmatically

Web SDK provides the button method that allows to create and mount the Sign in with Klarna button programmatically.

window.KlarnaSDKCallback = function (klarna) {
  const siwkButton = klarna.Identity.button({
    id: "klarna-identity-button",
    scope: "openid offline_access payment:request:create profile:name",
    redirectUri: "http://localhost:3000/callback.html"
  });

  siwkButton.mount("#button-container");
};

If a merchant wants to use a custom button matching with Klarna's but also with their own design guidelines, they can use the attach method that is provided by Web SDK. The attach method will register the necessary event handlers to start the sign in flow.

window.KlarnaSDKCallback = function (klarna) {
  const siwkButton = klarna.Identity.button({
    id: "klarna-identity-button",
    scope: "openid offline_access payment:request:create profile:name",
    redirectUri: "http://localhost:3000/callback.html"
  });

  // notice, we are using the `attach` method
  // and providing a button id instead of a container id
  siwkButton.attach("#merchants-custom-button-id");

Web SDK Identity API can emit two events: signin and error which can be handled as below:

window.KlarnaSDKCallback = function (klarna) {
  // 1. Listen for `signin` event to receive signin response object
  klarna.Identity.on("signin", async (signinResponse) => {
    console.log(signinResponse);
  });

  // 2. Listen for `error` event to handle error object
  klarna.Identity.on("error", async (error) => {
    console.log(error);
  });

Sign in with Klarna buttons can emit two events: ready and clicked.

window.KlarnaSDKCallback = function (klarna) {
  // Please notice that we can retrieve the button instance,
  // by providing the button instance id to the button method
  const siwkButton = klarna.Identity.button("klarna-identity-button");

  siwkButton.on('ready', async () => {
    // handle ready event
  })

  siwkButton.on('clicked', async () => {

The table below lists the available scopes and how they correspond to claims and permissions. 

The mock-ups below show how users will see required versus optional scopes when entering the Sign in with Klarna flow.   

Before using data from the id_token, it needs to be validated. More about it under Token Validation.

Upon completing the sign-in process, utilise a specific claim (such as phone, email, or national identification number for Sweden) as a unique customer identifier. 

Make sure you are handling the following scenarios to ensure seamless integration:

• New Users: If the identifier does not match any existing user in your database, check if the consumer consented to share all the data you requested. If additional information is required, remember to show your onboarding UI after Sign in with Klarna flow. Once onboarding is complete, create a new user account using the data returned from Klarna and store the user_account_linking_refresh_token within that record.
• Existing Klarna Users: In cases where the identifier is already linked to a Klarna account, Sign in with Klarna always returns fresh customer data. Update your user record with this data to ensure that the information in your database remains current.
• Existing Users: For users already in your database but not connected to Klarna, consider these approaches:
  

By carefully managing these scenarios, you can provide a fluid and integrated user experience, leveraging the comprehensive data and functionality offered through the Sign in with Klarna.

For those who have already integrated Klarna Payments or Klarna Checkout, Sign in with Klarna enhances user experience by enabling automatic login within these products. To achieve this, simply pass the access_token, obtained from a token refresh call (see Refresh Token), to your existing integrations. You can find examples below depending if you have Klarna Payment or Klarna Checkout. 

For Klarna Payments 

Include the access_token in the POST create a payment session request to the Klarna payments API. Add the key to the customer object as klarna_access_token key as shown in the example below.

fetch("https://api.klarna.com/payments/v1/sessions", {
	method: "POST",
	headers: {
		"Content-Type": "application/json"
	},
	body: {
	  ...
  	  "customer": {
    	    ...
    	    "klarna_access_token": "access_token",

For Klarna Checkout 

Include the access_token in the POST create order request to the Klarna checkout API. Add the key to the customer object as klarna_access_token key as shown in the example below.

fetch("https://api.klarna.com/checkout/v3/orders", {
	method: "POST",
	headers: {
		"Content-Type": "application/json"
	},
	body: {
	  ...
  	  "customer": {
    	    ...
    	    "klarna_access_token": "access_token",