Create a Klarna Payments Session

A Klarna Payments session is created by you as a merchant. This session should be continued after a customer has completed a purchase or has dropped off.

Date: 11.07.2019

Create Session

A Klarna Payments session is created server-side via our REST API. This is done before the Klarna widget is loaded. Best practice is that you tie the Klarna session to your own user session to keep track of it throughout the purchase flow.

When a session is created you will receive the available payment_method_categories for the session, a session_id and a client_token. The session_id can be used to update the session using the REST API, the client_token should be passed to the browser.

Note: A session stays valid for 48 hours after the last update of it.

Best practice: Consumer details could be added to the session creation call. If the checkout process is designed in such a way that not all customer details are known at this stage, they can be added in either Load or Authorize .

Authentication

Use your API Credentials and HTTP Basic auth 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 Klarna end points use HTTPS. Read more here.

Create the session

To create the session, send the shopping cart details, country, currency and locale via a server-side call to our REST API. You’ll find the complete REST API reference here.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "GB",
  "purchase_currency": "GBP",
  "locale": "en-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"
  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "DE",
  "purchase_currency": "EUR",
  "locale": "de-DE",
  "order_amount": 499,
  "order_tax_amount": 0,
  "order_lines": [{
    "type": "physical",
    "reference": "19-402",
    "name": "Battery Power Pack",
    "quantity": 1,
    "unit_price": 499,
    "tax_rate": 0,
    "total_amount": 499,
    "total_discount_amount": 0,
    "total_tax_amount": 0,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "US",
  "purchase_currency": "USD",
  "locale": "en-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "AT",
  "purchase_currency": "EUR",
  "locale": "de-AT",
  "order_amount": 499,
  "order_tax_amount": 0,
  "order_lines": [{
    "type": "physical",
    "reference": "19-402",
    "name": "Battery Power Pack",
    "quantity": 1,
    "unit_price": 499,
    "tax_rate": 0,
    "total_amount": 499,
    "total_discount_amount": 0,
    "total_tax_amount": 0,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "NL",
  "purchase_currency": "EUR",
  "locale": "nl-NL",
  "order_amount": 499,
  "order_tax_amount": 0,
  "order_lines": [{
    "type": "physical",
    "reference": "19-402",
    "name": "Battery Power Pack",
    "quantity": 1,
    "unit_price": 499,
    "tax_rate": 0,
    "total_amount": 499,
    "total_discount_amount": 0,
    "total_tax_amount": 0,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "DK",
  "purchase_currency": "DKK",
  "locale": "da-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "NO",
  "purchase_currency": "NOK",
  "locale": "nb-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "FI",
  "purchase_currency": "EUR",
  "locale": "fi-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "CH",
  "purchase_currency": "CHF",
  "locale": "de-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}
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
POST /payments/v1/sessions
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "purchase_country": "SE",
  "purchase_currency": "SEK",
  "locale": "sv-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,
    "image_url": "https://www.exampleobjects.com/logo.png",
    "product_url": "https://www.estore.com/products/f2a8d7e34"

  }]
}

NOTE: Please make sure you follow all validation rules as described in the create-session section of this article .

Create session response

The REST API returns the following data:

  • session_id is used for server-side updates on the session via the server-side REST API
  • client_token is used to initialize the widget
  • payment_method_categories represents what categories of payment methods that are available for this purchase. The payment_method_category is required when loading a widget

Example successful response

Example from US.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200 OK
Content-Type: application/json

{
"session_id": "068df369-13a7-4d47-a564-62f8408bb760",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAwMDAwMDAwMDAtMDAwMDAtMDAwMC0wMDAwMDAwMC0wMDAwIiwidXJsIjoiaHR0cHM6Ly9jcmVkaXQtZXUua2xhcm5hLmNvbSJ9.A_rHWMSXQN2NRNGYTREBTkGwYwtm-sulkSDMvlJL87M",
"payment_method_categories": [{
    "identifier": "pay_later"
    "name" : "Buy now, pay later",
    "asset_urls" : {
      "descriptive" : "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
      "standard" : "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"
    }
}]
}

Example error responses

1
2
3
4
5
6
7
{
    "correlation_id":	"6a9b1cb1-73a3-4936-a030-481ba4bb203b",
    "error_code":	"ERROR_CODE",
    "error_messages":	[
        "ERROR_MESSAGE"
    ]
}

Best practice: You can use the correlation_id to troubleshoot the call in the logs app in merchant portal.

Possible error codes and messages

Error CodeError messageComment
Error Code
BAD_VALUE
Error message
Bad value: order_tax_amount
Comment
If you enter any tax for orders, this is validated as described in this article. This validation is not passed in case this error message is thrown.
Error Code
BAD_VALUE
Error message
Bad value: order_lines
Comment
All order lines are validated as seen in this article. If your added order lines do not follow our guidelines, we will throw an error referring to the specific part of an order line that has failed.
Error Code
BAD_VALUE
Error message
Bad value: purchase_currency
Comment
In case a purchase_currency is wrongly formatted or doesn’t apply in a certain locale this error message is thrown.
Error Code
BAD_VALUE
Error message
Bad value: order_lines[i].tax_rate
Comment
If you enter any tax for orders, this is validated as described in this article. This validation is also done per item, so if the validation criteria are not met you will find this error message.
Error Code
BAD_VALUE
Error message
Bad value: billing_address.phone
Comment
If you share billing address at create_session, this will be validated against format standards. These are not fulfilled in case this validation error is thrown. Please look into this article for details about customer data.