1. Create session

First, create a Klarna session for this customer. 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.

1.1 Create session call

The session is created when the customer proceeds to the checkout. This step is preferably executed before the customer loads the checkout page, since the data from the create_session response is required to load the widget.

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.

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 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. Is required when loading a widget
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"
  }]
}

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. 

POST /payments/v1/sessions/068df369-13a7-4d47-a564-62f8408bb760
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

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

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

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