Step 1: Initiate a payment

This section of the guide walks you through initiating a payment and letting your customers pay with Klarna.

Last updated on Aug 29, 2023

When your customer wants to pay with Klarna, you have to open a payment session and share the shopping cart details in a POST request to the {apiURL}/payments/v1/sessions endpoint. In that request, you also specify if the payment is one-time or recurring.

Once you start a payment session, it stays open for 48 hours or until you place an order. You can also send a separate POST request to cancel the session.

Authentication

Klarna payments API uses HTTP basic authentication. To authenticate, use your API credentials that consist of:

a username linked to your Merchant ID at Klarna
a password associated with your username.

If you're using an API platform that lets you store your credentials, you can add them in relevant fields. Otherwise, make sure to include the Base64-encoded username:password in the Authorization header field of each API request, as shown below.

JSON

Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==

Authorization request header with Base64-encoded credentials.

Common parameters

To get a success response, include the following required parameters in your POST {apiURL}/payments/v1/sessions request.

Parameter	Description
`locale`	The language of information presented on the Klarna widget. Learn more about using locale in API calls.
`purchase_country`	The country where the purchase is made. Learn more about supported countries.
`purchase_currency`	The currency in which the customer is charged. Learn more about supported currencies.
`order_amount`	The total price of the order, including tax and discounts.
`order_lines`	The details of order lines in the purchase.
`intent`	The purpose of the payment session.
`merchant_urls.authorization`	Get a callback once the customer has completed the flow and you can create an order.

We recommend you don't include customer details when initiating a payment session. Instead, use the authorize() call to share them with Klarna at a later stage of the checkout process when the customer clicks Buy.

Payment scenarios and intent

As we already mentioned, you can use Klarna payments in a variety of payment scenarios. Depending on the scenario, add the right value in the intent field of the request.

For one-time payments, set intent to buy.

For recurring payments:

Set intent to tokenize if you don't want to place an order at checkout.
Set intent to buy_and_tokenize if you want to place the first order at checkout.

The intent you set for a session determines the steps you need to take when creating an order later in the process.

One-time payment

To open a one-time payment session, include all common parameters in the request body and set intent to buy.

JSON

{
  "intent": "buy",
  "purchase_country": "US",
  "purchase_currency": "USD",
  "locale": "en-US",
  "order_amount": 10,
  "order_tax_amount": 0,
  "order_lines": [{
    "type": "physical",
    "reference": "19-402",

A POST request to create a one-time payment session for a customer located in the US.

Recurring payment without payment at checkout

To enable recurring payments without charging your customer at checkout, include the following in your request:

all common parameters
intent set to tokenize
the subscription details in the subscription object.

You can charge the customer later using a customer token created in the same Klarna payments session.

JSON

{ 
  "intent": "tokenize",
  "purchase_country": "US", 
  "purchase_currency": "USD", 
  "locale": "en-US", 
  "order_amount": 999, 
  "order_tax_amount": 0, 
  "order_lines": [{ 
	"type": "digital", 
	"subscription": {

A POST request to enable recurring payments for a customer located in the US.

Recurring payment with payment at checkout

To charge the customer at checkout and enable recurring payments at the same time, include the following in your request:

all common parameters
intent set to buy_and_tokenize
the subscription details in the subscription object.

JSON

{ 
  "intent": "buy_and_tokenize",
  "purchase_country": "US",
  "purchase_currency": "USD", 
  "locale": "en-US", 
  "order_amount": 999, 
  "order_tax_amount": 0, 
  "order_lines": [{ 
	"type": "digital", 
	"subscription": {

A POST request to charge the US customer at checkout and enable recurring payments.

Success response

In response to a create session call, you receive:

session_id, a payment session identifier you can use to update the session and retrieve session details
client_token, a token you pass to the JavaScript SDK to launch the Klarna widget
payment_method_categories, an array that lists the Klarna payment methods you can use. We can respond with one or more categories. Later, in the authorize() call, you may send one or more categories in your request, basically categories that you want to authorize the purchase for. For single categories, the used parameter is the payment_method_category, with a string value. We accept both the array of payment_method_categories and the string of payment_method_category.

JSON

{
"session_id": "068df369-13a7-4d47-a564-62f8408bb760",
"client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAwMDAwMDAwMDAtMDAwMDAtMDAwMC0wMDAwMDAwMC0wMDAwIiwidXJsIjoiaHR0cHM6Ly9jcmVkaXQtZXUua2xhcm5hLmNvbSJ9.A_rHWMSXQN2NRNGYTREBTkGwYwtm-sulkSDMvlJL87M",
"payment_method_categories": [{
    "identifier": "klarna"
    "name" : "Pay with Klarna",
    "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"
    }

A success response to the create session call.

Error response

If your request doesn't pass our validation, you'll receive an error response.

JSON

{
    "correlation_id":	"6a9b1cb1-73a3-4936-a030-481ba4bb203b",
    "error_code":	"BAD_VALUE",
    "error_messages":	[
        "Bad value: order_lines"
    ]
}

An error response caused by incorrect order line details.

Here are examples of common errors with troubleshooting suggestions. You can use the value in correlation_id to find entries related to the request under Logs in the Merchant portal.

Error code	Error message	Description
`BAD_VALUE`	`Bad value: order_tax_amount`	The tax details in the request aren't aligned with the rules for tax handling.
`BAD_VALUE`	`Bad value: order_lines`	Some of the order line details don't follow our guidelines or violate API field restrictions. Refer to the Klarna payments API reference for details.
`BAD_VALUE`	`Bad value: order_lines[i].tax_rate`	This validation failed for an item in `order_lines`.
`BAD_VALUE`	`Bad value: purchase_currency`	`purchase_currency` is incorrectly formatted or doesn’t match `locale`.
`BAD_VALUE`	`Bad value: billing_address.phone`	If you share the customer's billing address in the request, it's validated against format standards. Read more about customer data requirements.

Integrate with Klarna payments

Step 2: Check out

Mobile SDK

The Mobile SDK is the best and only official way to integrate Klarna's products into your mobile app.

Additional features

Depending on the market and the details of your Klarna deal, you may be able to add some extra features to your store.

Sharing subscription details with Klarna

When sharing order information related to a subscription, you need to provide some additional information about the order.