Create a New Session

The first step is to setup a new checkout session by sending a genericpayment-request to our server API as listed below. This step is a pre-condition for loading the Klarna widget.

Please make sure to send the customer data within this request as it is needed to initiate a new session. A session will remain valid for 48 hours after the last update.

→ Genericpayment start_session

Optional - Update the Session

If the customer leaves the checkout page and returns at a later point in time, you can update the created session and change for example the address data.

→ Genericpayment update_session

Handle Token

Part of the response is a client token. This token needs to be passed to the Klarna Widget. This Widget sends the client token together with the selected payment method (e.g. "Klarna Pay Later") to Klarna to get a authorization token.

→ Widget

Finalize the Checkout ((Pre-)Authorization)

In the last step, you need to send the authorization token received by Klarna widget as part of the (pre-)authorization request to our server api.

→ Preauthorization/Authorization

Add SDK to your page (insert in body)

<script>
  window.klarnaAsyncCallback = function () {

    // This is where you start calling Klarna's JS SDK functions
    // 
    // Klarna.Payments.init({....})

  };
</script>
<script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>

Initialize SDK and place a container on your page. Please note that the Klarna widget requires a minimum width of 280px.

Klarna.Payments.init({
  client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH'
})

<div id="klarna_container"></div>

Load Klarna Widget

When loading the Klarna widget, one needs to peovide the container ID established in the previous step and specify the payment_method_category. The payment_method_category specifies which of Klarna´s customer offerings (e.g. Pay now, Pay later, or Slice it) will be shown in the widget.

Klarna.Payments.load({
    container: '#klarna-payments-container',
    payment_method_category: 'pay_later'
  }, function (res) {
    console.debug(res);
})

Receive Response from load call

Klarna’s widget uses the show_form:true/false field as a response flag to load and to authorize calls in the Javascript SDK. In addition the object "error" can be retrieved to receive further information about potential problems. The response information enables you to display to your customer Klarna as a payment method only when it can actually be utilised by your customer. In summary, there are three situations deriving from the "Receive Response" call.

Positive Response

If show_form: true, and there are no errors in the object returned, Klarna renders the payment options available to the customer in the widget.

{
show_form: true
}

Adjust and Try Again

If show_form: true, but an error is returned as well, then something is wrong and the consumer needs to take action before moving forward. Klarna will inform the consumer about the details of the error in the widget. Optionally, you can interpret the invalid fields in the error message and take appropriate actions on your checkout page. See the  JavaScript SDK reference page for further information.

{
show_form: true,
error: {
  invalid_fields: [
    billing_address.street_address
    billing_address.city
    billing_address.given_name
    billing_address.postal_code
    billing_address.family_name
    billing_address.email	]
  }
}

Negative Response

If show_form: false, the payment method chosen by the customer will not be offered for this order based on Klarna’s evaluation. A message is displayed to the consumer in the Widget.

When Klarna returns a show_form: false, your store cannot offer the selected payment method to this customer. You need to present other payment methods to the customer and hide the option of Klarna payment.

{
show_form: false
}

Authorise the Purchase

Once the customer has successfully selected Klarna as payment method in the checkoucheckout, the purchase can be authorised by using the Klarna JavaScript SDK. In this step all necessary customer details are transmitted to Klarna for taking a decision about whether or not to offer credit for the purchase. As a result of the authorisation you will receive a token enabling you to place an order towards Klarna. A successful authoirsation guarantees that the order can be generated within 60 minutes.

Sending the Request

The Authorisation is initiated by a client-side call which will provide you with a token for the order once successfully completed.

Here is an example request for an authorisation call. In the call one must provide the billing and optionally the shipping address.

KKlarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "GB",
  purchase_currency: "GBP",
  locale: "en-GB",
  billing_address: {
    given_name: "John",
    family_name: "Doe",
    email: "john@doe.com",
    title: "Mr",
    street_address: "13 New Burlington St",
    street_address2: "Apt 214",
    postal_code: "W13 3BG",
    city: "London",
    region: "",
    phone: "01895808221",
    country: "GB"
  },
  shipping_address: {
    given_name: "John",
    family_name: "Doe",
    email: "john@doe.com",
    title: "Mr",
    street_address: "13 New Burlington St",
    street_address2: "Apt 214",
    postal_code: "W13 3BG",
    city: "London",
    phone: "01895808221",
    country: "GB"
  },
  order_amount: 10,
  order_tax_amount: 0,
  order_lines: [{
    type: "physical",
    reference: "19-402",
    name: "Battery Power Pack",
    quantity: 1,
    unit_price: 10,
    tax_rate: 0,
    total_amount: 10,
    total_discount_amount: 0,
    total_tax_amount: 0,
    product_url: "https://www.estore.com/products/f2a8d7e34",
    image_url: "https://www.exampleobjects.com/logo.png"
  }],
  customer: {
    date_of_birth: "1970-01-01",
  },
}, function(res) {
  console.debug(res);
})

According to Klarna documentation (Klarna Docs - Authorize the purchase):

User interaction during the authorize call

When authorizing the order, Klarna conducts a full risk assessment. Therefore, from the point where you call authorize until you receive the callback you must:

1. Avoid sending another authorize call (e.g. disable the buy button from being clicked again)
2. Show to the consumer that the order is being processed (e.g. by showing a loading spinner)
3. Prevent consumer from changing order or billing details (e.g. lock the input fields on your page)

The callback is typically received within seconds, but may take up to a minute or so in case a consumer sign-up is required when the user interacts with the widget.

Process callback from authorise call

Once the wigdet has processes the autorisation a callback is performed providing an object with one of the following parameter:

• approved (true/false) - the authorization result, approved or denied
• show_form (true/false) - whether the Klarna Widget should be displayed or hidden
• authorization_token - a token which allows you to place the order via a server side call, only returned if the authorization was approved
• error - contains details of potential error messages

Order approved

If approved carries the value "true", Klarna has approved the authorisation of credit for this order. With the authorisation_token the order can be completed using a server side pace order call. The token is valid for 60 minutes during which the authorisation is guaranteed.

{
authorization_token: "b4bd3423-24e3",
approved: true,
show_form: true
}

Order not approved

If approved: false, Klarna cannot approve the purchase. There are now two options:

Option 1 - Fixable error

In the case of an adjustable error, you will receive show_form: true and a specification about what fields that are invalid, e.g. error: { invalid_fields: ["billing_address.email"] } }. The widget will also display an error message to the consumer, asking them to correct it before you re-authorize the order. This error message will also clarify which specific field that is incorrect.

{
approved: false,
show_form: true,
error: {
  invalid_fields: [
              billing_address.street_address
              billing_address.city
              billing_address.given_name
              billing_address.postal_code
              billing_address.family_name
              billing_address.email ]
  }
}

Option 2 - Order declined

If show_form: false, the order is declined and the Klanra widget should be hidden requesting the customer to select a different method of payment.

{
approved: false,
show_form: false
}