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 they're 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 comes back laterreturns at a later point in time, you can update the created session and change for example the address data.

add_paydata[action]=start_session
aid=111111
amount=2222
api_version=1.00
birthday=1958101
city=Neuss
clearingtype=fnc
country=DE
currency=EUR
de[1]=for
ocean use only
email=klarna@approved.de
encoding=UTF-8
financingtype=KLS
firstname=Testperson-de
gender=m
id[1]=boat66
it[1]=goods
key=e10adc3949ba59abbe56e057f20f883e
language=de
lastname=Approved
mid=11111
mode=test
no[1]=1
portalid=2011111
pr[1]=8540
request=genericpayment
salutation=Herr
street=Hellersbergstraße 14
telephonenumber=01522113356
va[1]=1900
zip=41460

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 checkout, 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
}

Finalize the authorisaton

According to Klarna documentation (Klarna Docs - Authorize the purchase) the following steps on client side are optional.

Finalising an authorisation only applies to your integration if you offer payment methods where funds are drawn from the consumers directly, such as bank transfer or Sofort, in a multi-step checkout. If you integrate a multi-step checkout, you may call authorize() with the auto_finalize: false property set in order to indicate that there is a finalization step. In this case the response may differ.

In a multi-step checkout scenario the authorize() call can be triggered when the consumer selects the payment method and then presses the “continue” button to go to the next step of the checkout. With Pay Now as payment method category however transferring the funds should only happen once the consumer has pressed the “buy” button to finalize the purchase.

To cater for such a scenario authorize() can still be called when the consumer has selected the payment method, but with the auto_finalize property set to false. authorize() example:

Klarna.Payments.authorize(
{ payment_method_category: ‘pay_now’, auto_finalize: false},
{},
function(res) {
// proceed to next checkout page. The finalize_required property in the response indicates
// if finalize is needed or not.
//
// res = {
//   show_form: true,
//   approved: false,
//   finalize_required: true
// }
})

Now when the consumer reached the last page in the checkout and can finalize the purchase finalize() is called. This will then trigger the transfer of funds and return the authorization token in the finalize callback. The flow is transparent to all payment method categories. That means if finalization was not needed in the authorize() call (e.g. for pay later) finalize()can be still be called and will return the authorization_token so that the implementation remains the same for all payment method categories. finalize() example:

Klarna.Payments.finalize(
{payment_method_category: ‘pay_now’},
{},
function(res) {
// res = {
//   show_form: true,
//   approved: true,
//   authorization_token: ...
// }
})