Authorize the purchase

The authorization of a purchase means that you will send in all necessary customer details for Klarna to make a decision about whether or not credit could be offered for the purchase.

Date: 11.07.2019

When the consumer has chosen a payment method and wants to complete the purchase, you will need to use our Javascript SDK to authorize the order. If successful, you will receive an authorization token in return which gives you the ability to place an order towards Klarna. During the authorize step Klarna takes all the order and customer data from the session and makes an assessment, to see if we could offer the selected payment method for this purchase.

Note: A successful authorization guarantees that the order can be created within 60 minutes.

Send the request

The authorization is made with a client side authorize()-call. The result of a successful authorization (approved: true) is an authorization_token. This is used when placing the order towards Klarna.

In the authorize() call you must pass the billing (and optionally shipping) address that has not been shared already. Please note that Klarna will use all information that has been collected throughout this session when authorizing the order.

For more information about what is needed per market and how to format it, please go to the consumer object article .

Note: If the shipping address is not added to the session, Klarna will duplicate the billing address and use it as shipping address.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
Klarna.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",
    region: "",
    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",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  billing_address: {
    given_name: "Omer",
    family_name: "Heberstreit",
    email: "omer@Heberstreit.com",
    title: "Herr",
    street_address: "Hermannstraße 64",
    street_address2: "",
    postal_code: "53225",
    city: "Bonn",
    region: "",
    phone: "+491522113356",
    country: "DE"
  },
  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",
    gender: "male"
  }
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  billing_address: {
    given_name: "Edwin",
    family_name: "Blochwitz",
    email: "edwin@blochwitz.com",
    title: "Herr",
    street_address: "Grünwaldweg 16",
    postal_code: "2283",
    city: "Obersiebenbrunn",
    region: "",
    phone: "+43 676 2600000",
    country: "AT"
    },
    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",
      gender: "male"
  }
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "NL",
  purchase_currency: "EUR",
  locale: "nl-NL",
  billing_address: {
    given_name: "Sander",
    family_name: "Dekker",
    email: "sander@dekker.com",
    title: "Dhr.",
    street_address: "Boerpark 742 II",
    postal_code: "7551 JI",
    city: "Enschede",
    region: "",
    phone: "06-14341727",
    country: "NL"
  },
  shipping_address: {
    given_name: "Sander",
    family_name: "Dekker",
    email: "sander@dekker.com",
    title: "Dhr.",
    street_address: "Boerpark 742 II",
    postal_code: "7551 JI",
    city: "Enschede",
    region: "",
    phone: "06-14341727",
    country: "NL"
  },
  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",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "DK",
  purchase_currency: "DKK",
  locale: "da-DK",
  billing_address: {
    given_name: "Michael",
    family_name: "Sorensen",
    email: "michael@sorensen.com",
    street_address: "Nygyde 8",
    postal_code: "2042",
    city: "MunkeRudvaerklose",
    region: "",
    phone: "29911076",
    country: "DK"
  },
  shipping_address: {
    given_name: "Michael",
    family_name: "Sorensen",
    email: "michael@sorensen.com",
    street_address: "Nygyde 8",
    postal_code: "2042",
    city: "MunkeRudvaerklose",
    region: "",
    phone: "29911076",
    country: "DK"
  },
  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: {
    national_identification_number: "3108971100",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "NO",
  purchase_currency: "NOK",
  locale: "nb-NO",
  billing_address: {
    given_name: "Marius",
    family_name: "Huseby",
    email: "marius@huseby.com",
    street_address: "Hagens Gate 53",
    postal_code: "2151",
    city: "Oslo",
    region: "",
    phone: "+45 40 123 456",
    country: "NO"
  },
  shipping_address: {
    given_name: "Marius",
    family_name: "Huseby",
    email: "marius@huseby.com",
    street_address: "Hagens Gate 53",
    postal_code: "2151",
    city: "Oslo",
    region: "",
    phone: "+45 40 123 456",
    country: "NO"
  },
  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: {
    national_identification_number: "01125637848",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "FI",
  purchase_currency: "EUR",
  locale: "fi-FI",
  billing_address: {
    given_name: "Saimi",
    family_name: "Pennanen",
    email: "saimi@pennanen.com",
    street_address: "Meriluotokatu 447",
    postal_code: "78164",
    city: "Helsinki",
    phone: "+358 401234567",
    country: "FI"
  },
  shipping_address: {
    given_name: "Saimi",
    family_name: "Pennanen",
    email: "saimi@pennanen.com",
    street_address: "Meriluotokatu 447",
    postal_code: "78164",
    city: "Helsinki",
    phone: "+358 401234567",
    country: "FI"
  },
  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: {
    national_identification_number: "070857-7573",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "SE",
  purchase_currency: "SEK",
  locale: "sv-SE",
  billing_address: {
    given_name: "Håkan",
    family_name: "Larsson",
    email: "hakan.larsson.test@klarna.com",
    street_address: "Lars Väg 399",
    postal_code: "11354",
    city: "Stockholm",
    phone: "0765260000",
    country: "SE"
  },
  shipping_address: {
    given_name: "Håkan",
    family_name: "Larsson",
    email: "hakan.larsson.test@klarna.com",
    street_address: "Lars Väg 399",
    postal_code: "11354",
    city: "Stockholm",
    phone: "0765260000",
    country: "SE"
  },
  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: {
    national_identification_number: "410321-9202",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
Klarna.Payments.authorize({
  payment_method_category: "pay_later"
}, {
  purchase_country: "CH",
  purchase_currency: "CHF",
  locale: "de-CH",
  billing_address: {
    given_name: "Roger",
    family_name: "Schmidt",
    email: "roger.Schmidt.test@klarna.com",
    street_address: "Bahnhofstrasse 4a",
    postal_code: "8001",
    city: "Zurich",
    phone: "0793123456",
    country: "CH"
  },
  shipping_address: {
    given_name: "Roger",
    family_name: "Schmidt",
    email: "roger.Schmidt.test@klarna.com",
    street_address: "Bahnhofstrasse 4a",
    postal_code: "8001",
    city: "Zurich",
    phone: "0793123456",
    country: "CH"
  },
  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",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
Klarna.Payments.authorize({
  payment_method_category: "pay_over_time"
}, {
  purchase_country: "US",
  purchase_currency: "USD",
  locale: "en-US",
  billing_address: {
    given_name: "John",
    family_name: "Doe",
    email: "john@doe.com",
    title: "Mr",
    street_address: "Lombard St 10",
    street_address2: "Apt 214",
    postal_code: "90210",
    city: "Beverly Hills",
    region: "CA",
    phone: "333444555",
    country: "US"
  },
  shipping_address: {
    given_name: "John",
    family_name: "Doe",
    email: "john@doe.com",
    title: "Mr",
    street_address: "Lombard St 10",
    street_address2: "Apt 214",
    postal_code: "90210",
    city: "Beverly Hills",
    region: "CA",
    phone: "333444555",
    country: "US"
  },
  order_amount: 10,
  order_tax_amount: 0,
  order_lines: [{
    type: "physical",
    reference: "19-402-USA",
    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",
    gender: "male"
  },
}, function(res) {
  console.debug(res);
})

Best practice: To ensure that customers understand that some processing is going on in the background, when authorize() is called, it should be visually shown that something is happening (e.g. a spinner in the button that triggered the authorize() call).

There is no need to provide fields that have already been provided previously during the session, unless the content in those fields has changed. That said, providing the same data again will not break anything. Best practice is to call authorize using a full request (like in the example above) to be sure the most up to date content is being authorized.

Note: You can also choose note to send in any customer details except for email. In this case Klarna will collect all necessary details to complete 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.

Act on the callback from the authorize call

When the widget has processed the authorization, the callback will be executed. The callback function parameter is an object containing the following properties

  • 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

Below is a quick guide of how to interpret the combination of these values

show_formapprovedAction
show_form
FALSE
approved
FALSE
Action
Disable Klarna’s widget and pre-select another payment method.
show_form
TRUE
approved
FALSE
Action
Display Klarna’s widget and show error message to customer. Let consumer change details and try again.
show_form
TRUE
approved
TRUE
Action
Create order and redirect customer

Order approved

If approved: true, then Klarna has approved the authorization of credit for this order.

1
2
3
4
5
{
authorization_token: "b4bd3423-24e3",
approved: true,
show_form: true
}

The authorization_token allows you to complete the order by the server side place order call. The token is valid for 60 minutes. During this time, the authorization is guaranteed. In case the place order is performed beyond the expiry, Klarna will try to re-authorize the order but cannot guarantee a successful outcome.

Best practice: You may store the authorization_token in a hidden form field and submit it to the backend with the “buy” / “Place order” form submit button.

Order not approved

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

Option 1 - Fixable error

Example of fixable error

1
2
3
4
5
6
7
8
9
10
11
12
13
{
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 ]
  }
}

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.

Best practice: You may use the error message in the callback object to highlight a particular entry field (in this case the customers email address) on your page.

It is also possible that you receive show_form: true and no error is included in the callback. If this happens, it means that the customer has aborted a required interaction in the widget. Including authentication or a potential credit signup flow. In this case you should continue to show Klarna’s options as the customer might want to make another attempt at completing the purchase with Klarna.

Option 2 - Purchase declined

Example purchase declined response

1
2
3
4
{
approved: false,
show_form: false
}

If show_form: false, the purchase is declined. The widget should be hidden and the user should select another payment method.

We will not share more information about why a certain purchase was rejected, as our risk and fraud policies are internal to Klarna.

Finalize the authorization

Please note that this step only applies to your integration if you offer payment methods where funds are drawn from the consumers directly, such as direct debit, bank transfer or Sofort, in a multi-step checkout.

Note: 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
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:

1
2
3
4
5
6
7
8
9
10
Klarna.Payments.finalize(
{payment_method_category: ‘pay_now’},
{},
function(res) {
// res = {
//   show_form: true,
//   approved: true,
//   authorization_token: ...
// }
})