This section of the guide walks you through initiating a payment and letting your customers pay with Klarna.
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.
Klarna payments API uses HTTP basic authentication. To authenticate, use your API credentials that consist of:
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==A sample authorization request header with Base64-encoded credentials.
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.
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.
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:
intent to tokenize if you don't want to place an order at checkout.intent to buy_and_tokenize if you want to place the first order at checkout.To open a one-time payment session, include all common parameters in the request body and set intent to buy.
{
"acquiring_channel": "ECOMMERCE",
"intent": "buy",
"purchase_country": "SE",
"purchase_currency": "SEK",
"locale": "en-SE",
"order_amount": 9500,
"order_tax_amount": 1900,
"order_lines": [
{A sample POST request to create a one-time payment session.
To enable recurring payments without charging your customer at checkout, include the following in your request:
intent set to tokenizesubscription objectYou can charge the customer later using a customer token created in the same Klarna payments session.
{
"acquiring_channel": "ECOMMERCE",
"intent": "tokenize",
"purchase_country": "SE",
"purchase_currency": "SEK",
"locale": "en-SE",
"order_amount": 9999,
"order_tax_amount": 2000,
"order_lines": [
{A sample POST request to enable recurring payments.
To charge the customer at checkout and enable recurring payments at the same time, include the following in your request:
intent set to buy_and_tokenizesubscription object{
"acquiring_channel": "ECOMMERCE",
"intent": "buy_and_tokenize",
"purchase_country": "SE",
"purchase_currency": "SEK",
"locale": "en-SE",
"order_amount": 9999,
"order_tax_amount": 2000,
"order_lines": [
{A sample POST request to charge the customer at checkout and enable recurring payments.
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 detailsclient_token, a token you pass to the JavaScript SDK to launch the Klarna widgetpayment_method_categories, an array that lists the grouped Klarna payment methods available for the session. We can respond with one or more categories depending on the market and account configuration.{
"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 sample success response to the create session call.
If your request doesn't pass our validation, you'll receive an error response.
{
"correlation_id": "6a9b1cb1-73a3-4936-a030-481ba4bb203b",
"error_code": "BAD_VALUE",
"error_messages": [
"Bad value: order_lines"
]
}A sample 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. |