1. Create session

First, create a Klarna session for this customer.

1.1 Create session call

The session is created server-side via our REST API before the widget is used. Best practice is that you tie the Klarna session to your own user session to keep track of it throughout the purchase flow. All known order details should be provided in order to enable pre-assessment and to personalize the offering. 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. When a session is created you will receive the available payment_method_categories, 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. A session is valid for 48 hours.

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.

Options when creating a session

With creating the session you’ll be able to transmit both the required extra_merchant_data and the parameter auto_capture: true if you want the order to be captured automatically once you placed it.

Extra Merchant Data

Depending on the merchant industry additional data can be transmitted when creating a new session. This data has to be transferred in the attachment field of the create session call.

To send an attachment you set the content_type and body property according to the desired attachment type. Available attachment types can be found here.

Automatically capture created orders

If you are selling digital goods or depending on the used payment method you may want the order to be captured automatically once it has been created. In order to do so, you can set auto_capture to true when creating the session or when placing the order.

Options

You can use options to change the default look and feel of the payment widget. Find more information 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
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
  }]
}

1.2 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_category represents what categories of payment methods that are available for this purchase. The payment_method_category is required when loading a widget

Example response:

For DE, AT

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "session_id": "068df369-13a7-4d47-a564-62f8408bb760",
  "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAwMDAwMDAwMDAtMDAwMDAtMDAwMC0wMDAwMDAwMC0wMDAwIiwidXJsIjoiaHR0cHM6Ly9jcmVkaXQtZXUua2xhcm5hLmNvbSJ9.A_rHWMSXQN2NRNGYTREBTkGwYwtm-sulkSDMvlJL87M",
  "payment_method_categories" : [ {
    "identifier" : "pay_now",
    "name" : "Sofort bezahlen.",
    "asset_urls" : {
      "descriptive" : "https://cdn.klarna.com/1.0/shared/image/generic/badge/de_de/pay_now/descriptive/pink.svg",
      "standard" : "https://cdn.klarna.com/1.0/shared/image/generic/badge/de_de/pay_now/standard/pink.svg"
      }
    }, {
      "identifier" : "pay_later",
      "name" : "Rechnung.",
      "asset_urls" : {
        "descriptive" : "https://cdn.klarna.com/1.0/shared/image/generic/badge/de_de/pay_later/descriptive/pink.svg",
        "standard" : "https://cdn.klarna.com/1.0/shared/image/generic/badge/de_de/pay_later/standard/pink.svg"
      }
    }]
}

For SE, NO, FI, DK, NL, GB, 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" : "Pay later.",
      "asset_urls" : {
        "descriptive" : "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_later/descriptive/pink.svg",
        "standard" : "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_later/standard/pink.svg"
      }
  }]
}

The Klarna session must be connected to the Merchant session. It expires after 48 hours. Error messages are explained in the API reference.

1.3 Session Updates

If the checkout page is reloaded, for example if the consumer goes back to the product page and then back to the checkout, you can update an existing session.

Updating a session is done by making a server-side POST call to update session using the same payload structure as when creating the session in the first place.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
POST /payments/v1/sessions/068df369-13a7-4d47-a564-62f8408bb760
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

{
  "order_amount": 998,
  "order_tax_amount": 0,
  "order_lines": [{
    "type": "physical",
    "reference": "19-315",
    "name": "Battery Power Pack",
    "quantity": 2,
    "unit_price": 499,
    "tax_rate": 0,
    "total_amount": 998,
    "total_discount_amount": 0,
    "total_tax_amount": 0
  }]
}

This call will update the existing Klarna session, and has an empty reply when successful.

1
2
HTTP/1.1 204 No content
Content-Type: application/json

What’s next?

It’s time to open the checkout page and present Klarna’s widget