Render checkout

This tutorial starts after the customer has selected their product(s) on your site, and wants to proceed to checkout.

In the steps below, you will be guided in how to render the Klarna Checkout HTML snippet on your checkout page. The Checkout snippet will load the Checkout application which is where the customer enters their address details and completes their payment with one of the payment methods offered within the checkout.

Authentication

Klarna uses HTTP Basic Auth for authentication. Use the API credentials provided to you to authenticate with Klarna. The credentials consists of two elements:

  • Username: a username linked to your Merchant ID at Klarna
  • Password: a unique password that is associated with the username

Authentication: Base64(username:password)

Endpoints (URLs)

Klarna’s European and North American environments have different endpoints (URLs) for testing and for live purchases. All requests to Klarna go through HTTPS. Read more here.

Create a Checkout Order

1. Configure the Checkout Order

In order for Klarna to construct a checkout order, we require that you provide some configurations which describes your website endpoints. These are the items that you should pass:

  • Merchant ID and API Credentials provided to you by Klarna.
  • Currency, language (locale) and country to be used.
  • Endpoints to be used by Klarna Checkout:
    • Terms: URL for your terms and conditions. Mandatory.
    • Checkout: URL to your checkout page. Mandatory.
    • Confirmation: URL to your confirmation page. This is where customers will be redirected after completing their purchase. Mandatory.
    • Push: URL to which Klarna will send an HTTP post request to confirm the order. Mandatory.
    • Order validation, Tax & Shipping changes and other order notifications. Learn more about Tax & Shipping click
    • (Only DE, AT) Cancellation: URL of merchant cancellation terms. Optional.
This section only applies to the regions:
Finland
If you are working with the **SmartPost** delivery option in Finland, then the Phone number entered in Klarna checkout needs to be used for sending the SmartPost SMS PIN. The SmartPost address shall be sent to Klarna as a “shipping option”

Find out more in the API reference on the Merchant Urls Object.

Note:

  • Use the locale and purchase country/currency to match the customer experience you want to render.
  • If a checkout order already exists for a customer session, the same order should be used throughout the customer’s session.
  • It is extremely important that a checkout order is only used for one customer session, reusing order is strictly forbidden.

Optimize the Checkout for Returning Customers

When you create the order you may choose to add data about the customer. We recommended this feature for customers who have already registered with your website and provided auxiliary data about themselves. If you choose to add customer data, a lot of the customer-defined fields on the checkout form will be pre-populated, which will increase your conversion. To find more about this feature visit the API Reference.

2. Create a Checkout Order

Once all configurations and cart items have been set, it’s time to create an order in Klarna’s system.

Create Order 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
55
56
57
58
59
60
61
62
63
POST /checkout/v3/orders
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
"purchase_country": "se",
"purchase_currency": "sek",
"locale": "en-GB",
"billing_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"order_amount": 503341,
"order_tax_amount": 100668,
"order_lines": [
  {
    "type": "physical",
    "reference": "19-402-SWE",
    "name": "Camera Travel Set",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 603341,
    "tax_rate": 2500,
    "total_amount": 503341,
    "total_discount_amount": 100000,
    "total_tax_amount": 100668,
    "image_url": "http://merchant.com/logo.png"
  }
],
"merchant_urls": {
  "terms": "http://merchant.com/tac.php",
  "checkout": "http://merchant.com/checkout.php?sid={checkout.order.id}",
  "confirmation": "http://merchant.com/thankyou.php?sid={checkout.order.id}",
  "push": "http://localhost/kco/push.php?sid={checkout.order.id}"
},
"shipping_options": [
  {
    "id": "free_shipping",
    "name": "Free Shipping",
    "description": "Delivers in 5-7 days",
    "price": 0,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": true,
    "shipping_method": "Home"
  },
  {
    "id": "pick_up_store",
    "name": "Pick up at closest store",
    "price": 399,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": false,
    "shipping_method": "PickUpStore"
  }
]
}

Note: The numeric values in the create checkout order request are 1/100-eds (e.g. 100 = 1.00 SEK and tax rate 2500 = 25.00%).

Create Order Response

The JSON response from the create checkout order call contains a unique order_id generated by Klarna which you need to keep track of since it is a reference to the order you created. The JSON response payload also contains the HTML snippet that you need to include on your page to render the checkout.

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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
{
"order_id": "1203c28c-f101-765f-bed8-f57a2d5e83e0",
"status": "checkout_incomplete",
"purchase_country": "se",
"purchase_currency": "sek",
"locale": "en-GB",
"billing_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"customer": {},
"shipping_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"order_amount": 503341,
"order_tax_amount": 100668,
"order_lines": [
  {
    "type": "physical",
    "reference": "19-402-SWE",
    "name": "Camera Travel Set",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 603341,
    "tax_rate": 2500,
    "total_amount": 503341,
    "total_discount_amount": 100000,
    "total_tax_amount": 100668,
    "image_url": "http://merchant.com/logo.png"
  }
],
"merchant_urls": {
  "terms": "http://merchant.com/tac.php",
  "checkout": "http://merchant.com/checkout.php?sid={checkout.order.id}",
  "confirmation": "http://merchant.com/thankyou.php?sid={checkout.order.id}",
  "push": "http://localhost/kco/push.php?sid={checkout.order.id}"
},
"html_snippet": "<div id=\"klarna-checkout-container\".................",
"started_at": "2018-01-24T14:21:55Z",
"last_modified_at": "2018-01-24T14:21:55Z",
"options": {
  "allow_separate_shipping_address": false,
  "date_of_birth_mandatory": false,
  "require_validate_callback_success": false
},
"external_payment_methods": [],
"external_checkouts": [],
"shipping_options": [
  {
    "id": "free_shipping",
    "name": "Free Shipping",
    "description": "Delivers in 5-7 days",
    "price": 0,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": true,
    "shipping_method": "Home"
  },
  {
    "id": "pick_up_store",
    "name": "Pick up at closest store",
    "price": 399,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": false,
    "shipping_method": "PickUpStore"
  }
],
"selected_shipping_option": {
  "id": "free_shipping",
  "name": "Free Shipping",
  "description": "Delivers in 5-7 days",
  "price": 0,
  "tax_amount": 0,
  "tax_rate": 0,
  "preselected": true,
  "shipping_method": "Home"
}
}

3. Render the Snippet in Your Checkout Page

It’s now time to render the checkout snippet.

Get the value of the html_snippet from the create checkout order call response and embed it into your page where you would like the Klarna Checkout to be rendered. You can either:

  • Embed the HTML snippet in your page served by your backend from an endpoint
1
2
3
4
5
6
7
8
<html>
  <head><!-- ... --></head>
  <body>
    <!-- Your checkout page html -->
    {{klarna_order.html_snippet}}
    <!-- More of your checkout page html -->
  </body>
</html>
  • Get the snippet via an ajax call from you server and inject it dynamically, using javascript, into your page. In this case, we should be sure that the script tag(s) are parsed and evaluated, which means inserting the snippet. Using innerHTML is not going to work.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
getSnippet(/* Your backend endpoint URL */).then(function renderSnippet(htmlSnippet) {
  var checkoutContainer = document.getElementById('my-checkout-container')
  checkoutContainer.innerHTML = htmlSnippet
  var scriptsTags = checkoutContainer.getElementsByTagName('script')
  // This is necessary otherwise the scripts tags are not going to be evaluated
  for (var i = 0; i < scriptsTags.length; i++) {
      var parentNode = scriptsTags[i].parentNode
      var newScriptTag = document.createElement('script')
      newScriptTag.type = 'text/javascript'
      newScriptTag.text = scriptsTags[i].text
      parentNode.removeChild(scriptsTags[i])
      parentNode.appendChild(newScriptTag)
  }
}).catch(renderError)

Note: The most straightforward approach for rendering the checkout page is to include the snippet via server side.

The snipet will render the checkout application so this is what you should see in your browser:

Example Image. This can be different dependent on the region you are in.

Handling an Existing Order

You should keep track of the Klarna order_id associated with the current customer to avoid creating a new order every time the customer loads the checkout page. This will allow the customer to reload the checkout page without having to re-enter any information they have already provided.

When the customer loads the checkout page and have a Klarna order_id associated with their session you should fetch the order from Klarna. If the order contents have changed you should make an update to the order.

1. Retrieve the Order

Use the checkout order_id to fetch the order from Klarna.

Get Order Request

1
2
3
GET /checkout/v3/orders/<order_id>
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

Get Order Response

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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
{
"order_id": "1203c28c-f101-765f-bed8-f57a2d5e83e0",
"status": "checkout_incomplete",
"purchase_country": "se",
"purchase_currency": "sek",
"locale": "en-GB",
"billing_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"customer": {},
"shipping_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"order_amount": 503341,
"order_tax_amount": 100668,
"order_lines": [
  {
    "type": "physical",
    "reference": "19-402-SWE",
    "name": "Camera Travel Set",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 603341,
    "tax_rate": 2500,
    "total_amount": 503341,
    "total_discount_amount": 100000,
    "total_tax_amount": 100668,
    "image_url": "http://merchant.com/logo.png"
  }
],
"merchant_urls": {
  "terms": "http://merchant.com/tac.php",
  "checkout": "http://merchant.com/checkout.php?sid={checkout.order.id}",
  "confirmation": "http://merchant.com/thankyou.php?sid={checkout.order.id}",
  "push": "http://localhost/kco/push.php?sid={checkout.order.id}"
},
"html_snippet": "<div id=\"klarna-checkout-container\"...................",
"started_at": "2018-01-24T14:21:55Z",
"last_modified_at": "2018-01-24T14:21:55Z",
"options": {
  "allow_separate_shipping_address": false,
  "date_of_birth_mandatory": false,
  "require_validate_callback_success": false
},
"external_payment_methods": [],
"external_checkouts": [],
"shipping_options": [
  {
    "id": "free_shipping",
    "name": "Free Shipping",
    "description": "Delivers in 5-7 days",
    "price": 0,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": true,
    "shipping_method": "Home"
  },
  {
    "id": "pick_up_store",
    "name": "Pick up at closest store",
    "price": 399,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": false,
    "shipping_method": "PickUpStore"
  }
],
"selected_shipping_option": {
  "id": "free_shipping",
  "name": "Free Shipping",
  "description": "Delivers in 5-7 days",
  "price": 0,
  "tax_amount": 0,
  "tax_rate": 0,
  "preselected": true,
  "shipping_method": "Home"
}
}

2. Update the Checkout Order

You should update the checkout order to reflect the changes that the customer has made to the cart. The request below will update the order with adding another item to the card.

Updating Order 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
POST /checkout/v3/orders/<order_id>
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
"order_amount": 756682,
"order_tax_amount": 151336,
"order_lines": [
  {
    "type": "physical",
    "reference": "19-402-SWE",
    "name": "Camera Travel Set",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 603341,
    "tax_rate": 2500,
    "total_amount": 503341,
    "total_discount_amount": 100000,
    "total_tax_amount": 100668,
    "image_url": "http://merchant.com/logo.png"
  },
  {
    "type": "physical",
    "reference": "19-403-SWE",
    "name": "MP3 Player with Audio",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 303341,
    "tax_rate": 2500,
    "total_amount": 253341,
    "total_discount_amount": 50000,
    "total_tax_amount": 50668,
    "image_url": "http://merchant.com/logo.png"
  }
]
}

Updating Order Response

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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
{
"order_id": "1203c28c-f101-765f-bed8-f57a2d5e83e0",
"status": "checkout_incomplete",
"purchase_country": "se",
"purchase_currency": "sek",
"locale": "en-GB",
"billing_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"customer": {},
"shipping_address": {
  "given_name": "Testperson-se",
  "family_name": "Approved",
  "email": "youremail@email.com",
  "street_address": "Stårgatan 1",
  "postal_code": "12345",
  "city": "Ankeborg",
  "phone": "+46765260000",
  "country": "se"
},
"order_amount": 756682,
"order_tax_amount": 151336,
"order_lines": [
  {
    "type": "physical",
    "reference": "19-402-SWE",
    "name": "Camera Travel Set",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 603341,
    "tax_rate": 2500,
    "total_amount": 503341,
    "total_discount_amount": 100000,
    "total_tax_amount": 100668,
    "image_url": "http://merchant.com/logo.png"
  },
  {
    "type": "physical",
    "reference": "19-403-SWE",
    "name": "MP3 Player with Audio",
    "quantity": 1,
    "quantity_unit": "pcs",
    "unit_price": 303341,
    "tax_rate": 2500,
    "total_amount": 253341,
    "total_discount_amount": 50000,
    "total_tax_amount": 50668,
    "image_url": "http://merchant.com/logo.png"
  }
],
"merchant_urls": {
  "terms": "http://merchant.com/tac.php",
  "checkout": "http://merchant.com/checkout.php?sid={checkout.order.id}",
  "confirmation": "http://merchant.com/thankyou.php?sid={checkout.order.id}",
  "push": "http://localhost/kco/push.php?sid={checkout.order.id}"
},
"html_snippet": "<div id=\"klarna-checkout-container\"................",
"started_at": "2018-01-24T14:21:55Z",
"last_modified_at": "2018-01-24T15:03:10Z",
"options": {
  "allow_separate_shipping_address": false,
  "date_of_birth_mandatory": false,
  "require_validate_callback_success": false
},
"external_payment_methods": [],
"external_checkouts": [],
"shipping_options": [
  {
    "id": "free_shipping",
    "name": "Free Shipping",
    "description": "Delivers in 5-7 days",
    "price": 0,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": true,
    "shipping_method": "Home"
  },
  {
    "id": "pick_up_store",
    "name": "Pick up at closest store",
    "price": 399,
    "tax_amount": 0,
    "tax_rate": 0,
    "preselected": false,
    "shipping_method": "PickUpStore"
  }
],
"selected_shipping_option": {
  "id": "free_shipping",
  "name": "Free Shipping",
  "description": "Delivers in 5-7 days",
  "price": 0,
  "tax_amount": 0,
  "tax_rate": 0,
  "preselected": true,
  "shipping_method": "Home"
}
}

Note: Find out more about the different fields in the cart items list in the API Reference.

Update an Ongoing Checkout Order

If you want to update an order while the customer is on the checkout page, you will need to suspend the checkout, update the order, and then resume the checkout to make sure the information shown in the checkout is up to date.

The flow is visualized in the chart below:

1. Suspend the Checkout

Suspending the checkout puts it in a waiting state, preventing customer input. A loading icon is rendered on top of the iframe indicating to the customer that the checkout is loading.

You can do this by issuing a Javascript command, as per the code example below:

1
2
3
window._klarnaCheckout(function (api) {
    api.suspend();
});

2. Update the Order

Update the order as you did in the example above.

3. Resume the Checkout

Resuming the checkout forces it to fetch the most recent order data from Klarna. The loading indicator will disappear, the form will become enabled. The amount presented in the checkout will now reflect the new order total.

1
2
3
window._klarnaCheckout(function (api) {
    api.resume();
});

Zero Sum Orders

This occurs when a customer has entered a voucher / discount code that results in the cart total amounting to zero. Visually, the user will see no payment methods, but be able to have an activated Buy Button to complete the purchase directly. The confirmation page will display confirming that their purchase with a 0 sum order is successful.

Note: A user cannot select a payment method at this stage, so no card payments will be applicable.

What’s next?

You have integrated Klarna Checkout into your checkout page.

The next steps: