Klarna

Last updated: April 29, 2022

Start accepting payments using Klarna, a favorite payment method in Europe.

We offer Klarna's Pay in 30 days and Pay in installments payment methods, allowing your customers to either pay up to 30 days later via an invoice, or split the payment into three equal installments.

Information

To start accepting Klarna payments, please contact your Account Manager.

Model	GW only
Payment flow	Redirect
Payment method type	BNPL, Online banking
One-step payment
Authorization
Capture	Immediate capture of full amount by Checkout; future partial captures by Klarna
Refund
Partial refund
Chargeback
Recurring payment

To integrate Klarna into your checkout process and start accepting payments, follow these five steps:

Create a session. When the customer reaches your checkout page, create a session with Klarna.
Display widget. Initialize and load the Klarna widget to present your customer with the payment methods.
Authorize. When the customer presses the buy/review order button on your page, make an authorization request.
Place the order. After the order has been authorized, place the order by using the authorization token generated in step three.
Capture the payment. Finally, once you've shipped the order or made it available to the customer, you can capture the payment.

First, you need to create a Klarna session for your customer.

You should provide all known order details at this stage to enable pre-assessment and to personalize the experience for your customer.

If, however, your checkout process is designed in a way that you don't have all the customer's details at this point, you can add them later on when you load the Klarna widget or when you come to authorize the payment.

When you create a session, you will receive the available payment_method_categories, a session_id and a client_token. A session is valid for 48 hours.

post

https://api.checkout.com/apms/klarna/credit-sessions

Header Value

Header	Value
`Authorization` required	`secret key` Use the valid secret key of your Checkout.com account. You can find this in the Hub.
`Content-Type` required	`application/json`

Authorization

required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

required

application/json

Field name	Description
`purchase_country` required string	The country in which the purchase is being made (two-letter ISO 3166 code).
`currency` required string	The currency in which the payment is being made (three-letter ISO 4217 code).
`locale` required string	The customer's locale (RFC 1766 code).
`amount` required integer	The total amount of the order, including tax and any discounts.
`tax_amount` required integer	The total tax amount of the order.
`products` required array	The order details. This object is passed directly to Klarna as order_lines. See Klarna's documentation for more information.
`custom_payment_method_ids` optional array	Klarna promo codes can be used to define the offers that are shown to the user in the Klarna modal – for example, a longer monthly finance allowance for a limited amount of time. Promo codes are created by Klarna and must be requested from them directly. See Klarna promo codes for more information.

Note

purchase_country and locale will affect the Klarna widget's validation rules. For example, when your customer is prompted for their address, the widget's postal code field will validate against available post codes in the country specified in purchase_country.


1{
2  "purchase_country": "GB",
3  "currency": "GBP",
4  "locale": "en-GB",
5  "amount": 1000,
6  "tax_amount": 1,
7  "products": [
8    {
9      "name": "Brown leather belt",
10      "quantity": 1,
11      "unit_price": 1000,
12      "tax_rate": 0,
13      "total_amount": 1000,
14      "total_tax_amount": 0
15    }
16  ],
17  "custom_payment_method_ids": ["6m_149APR"]
18}


1{
2  "session_id": "kcs_55xomnyd3ftujckeoyuvtkx2ue",
3  "client_token": "eyJhbGciOiJub25lIn0.ewogICJzZXNzaW9uX2lkIiA6ICI1MGEzYTNiOS02NGE5LTYwNjMtODNmNC1hMzRlM2Q4MjRiNGIiLAogICJiYXNlX3VybCIgOiAiaHR0cHM6Ly9rbGFybmEtcGF5bWVudHMtZXUucGxheWdyb3VuZC5rbGFybmEuY29tIiwKICAiZGVzaWduIiA6ICJrbGFybmEiLAogICJsYW5ndWFnZSIgOiAiZW4iLAogICJwdXJjaGFzZV9jb3VudHJ5IiA6ICJHQiIsCiAgImFuYWx5dGljc19wcm9wZXJ0eV9pZCIgOiAiVUEtMzYwNTMxMzctMTEiLAogICJ0cmFjZV9mbG93IiA6IGZhbHNlLAogICJlbnZpcm9ubWVudCIgOiAicGxheWdyb3VuZCIsCiAgIm1lcmNoYW50X25hbWUiIDogIlBsYXlncm91bmQgRGVtbyBNZXJjaGFudCIsCiAgInNlc3Npb25fdHlwZSIgOiAiUEFZTUVOVFMiLAogICJjbGllbnRfZXZlbnRfYmFzZV91cmwiIDogImh0dHBzOi8vZXZ0LnBsYXlncm91bmQua2xhcm5hLmNvbSIKfQ.",
4  "payment_method_categories": [
5    {
6      "asset_urls": {
7        "descriptive": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/slice_it/descriptive/pink.svg",
8        "standard": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/slice_it/standard/pink.svg"
9      },
10      "identifier": "pay_over_time",
11      "name": "Pay in installments"
12    },
13    {
14      "asset_urls": {
15        "descriptive": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/pay_later/descriptive/pink.svg",
16        "standard": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/pay_later/standard/pink.svg"
17      },
18      "identifier": "pay_later",
19      "name": "Pay in 30 days"
20    }
21  ],
22  "_links": {
23    "self": {
24      "href": "http://localhost:5100/credit-sessions/kcs_55xomnyd3ftujckeoyuvtkx2ue"
25    }
26  }
27}


1{
2  "request_id": "0HLK56US9BH1E:0000005B",
3  "error_type": "request_invalid",
4  "error_codes": ["purchase_country_required"]
5}

Information

If something goes wrong, you may get a 400 Bad request or 401 Unauthorized to access this resource error.

Next, load the widget on your page so your customer can choose one of the Klarna payment methods.

To do so, you first need to insert the below code into your page to load the Klarna Payments Library in your client.


1//<![CDATA[
2window.klarnaAsyncCallback = function () {
3  // This is where you start calling Klarna's JS SDK functions
4  //
5  // Klarna.Payments.init({ ... })
6};
7//]]>

Then initialize the Klarna Payments Library. To do this, call init and pass the client_token that you got in the response when you created the session in the first step.


1try {
2  Klarna.Payments.init({
3    client_token:
4      'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH',
5  });
6} catch (e) {
7  // Handle error
8}

Next, specify where you want the widget by adding a container to your checkout page with the following snippet.


1<div id="klarna_container"></div>

Note

The Klarna Payments iframe requires a minimum width of 280px.

To show your customers the Klarna payment options open to them (i.e. Pay in 30 days and Pay in installments), use the following payment_method_categories array, which you'll find in the response you received when you created the session in step one.


1{
2  "payment_method_categories": [
3    {
4      "asset_urls": {
5        "descriptive": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/slice_it/descriptive/pink.svg",
6        "standard": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/slice_it/standard/pink.svg"
7      },
8      "identifier": "pay_over_time",
9      "name": "Pay in installments"
10    },
11    {
12      "asset_urls": {
13        "descriptive": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/pay_later/descriptive/pink.svg",
14        "standard": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/pay_later/standard/pink.svg"
15      },
16      "identifier": "pay_later",
17      "name": "Pay in 30 days"
18    }
19  ]
20}

When that's done, present the Klarna widget to your customer by calling load, passing the ID of the container you added earlier and specifying the payment_method_categories.

If your customer has changed, say, their order or billing details since the session was created, you can also use load to pass these updates to the session by adding the relevant information to the data object.

Field name Description

Field name	Description
`options` required object	Use this to contain the container ID, `payment_method_categories`, and `instance_id`.
`options.container` required string	The ID you specified for the Klarna container above.
`options.payment_method_categories` required array	The `identifier`s of the `payment_method_categories` you want to present to the customer. (i.e. `pay_later` and/or `pay_over_time`)
`options.instance_id` required string	The ID you'll use to identify this instance of the Klarna Payments client. You should include this same `instance_id` for subsequent actions, like `authorize`, to indicate which instance the action applies to.
`data` optional object	If the customer has changed any of their order or billing information, this can be used to update the session.
`data.purchase_country` optional string	The country in which the purchase is being made (two-letter ISO 3166 code).
`data.purchase_currency` optional string	The currency in which the payment is being made (three-letter ISO 4217 code).
`data.locale` optional string	The customer's locale (RFC 1766 code).
`data.billing_address` optional object	Details about the customer's billing address.
`data.shipping_address` optional object	Details about the customer's shipping address.
`data.order_amount` optional integer	The total amount of the order, including tax and any discounts.
`data.order_tax_amount` optional integer	Total tax amount of the order.
`data.order_lines` optional array	Details about the order. This object is passed directly to Klarna as `order_lines`. See Klarna's documentation for more information.
`data.customer` optional object	Details about the customer.
`callback` required function	Catches the response from `Klarna.Payments.load()` for further processing.

options

required

object

Use this to contain the container ID, payment_method_categories, and instance_id.

options.container

required

string

The ID you specified for the Klarna container above.

options.payment_method_categories

required

array

The identifiers of the payment_method_categories you want to present to the customer. (i.e. pay_later and/or pay_over_time)

options.instance_id

required

string

The ID you'll use to identify this instance of the Klarna Payments client.

You should include this same instance_id for subsequent actions, like authorize, to indicate which instance the action applies to.

data

optional

object

If the customer has changed any of their order or billing information, this can be used to update the session.

data.purchase_country

optional

string

The country in which the purchase is being made (two-letter ISO 3166 code).

data.purchase_currency

optional

string

The currency in which the payment is being made (three-letter ISO 4217 code).

data.locale

optional

string

The customer's locale (RFC 1766 code).

data.billing_address

optional

object

Details about the customer's billing address.

data.shipping_address

optional

object

Details about the customer's shipping address.

data.order_amount

optional

integer

The total amount of the order, including tax and any discounts.

data.order_tax_amount

optional

integer

Total tax amount of the order.

data.order_lines

optional

array

Details about the order.

This object is passed directly to Klarna as order_lines. See Klarna's documentation for more information.

data.customer

optional

object

Details about the customer.

callback

required

function

Catches the response from Klarna.Payments.load() for further processing.

Information

We recommend passing the data object with every call to load, to ensure that the session reflects any changes the customer might have made to their order or billing information.


1try {
2  Klarna.Payments.load(
3    // options
4    {
5      container: '#klarna_container',
6      payment_method_categories: ['pay_later', 'pay_over_time'],
7      instance_id: 'klarna-payments-instance',
8    },
9    // data
10    {
11      purchase_country: 'GB',
12      purchase_currency: 'GBP',
13      locale: 'en-GB',
14      billing_address: {
15        given_name: 'John',
16        family_name: 'Doe',
17        email: '[email protected]',
18        title: 'Mr',
19        street_address: '13 New Burlington St',
20        street_address2: 'Apt 214',
21        postal_code: 'W13 3BG',
22        city: 'London',
23        region: '',
24        phone: '01895808221',
25        country: 'GB',
26      },
27      shipping_address: {
28        given_name: 'John',
29        family_name: 'Doe',
30        email: '[email protected]',
31        title: 'Mr',
32        street_address: '13 New Burlington St',
33        street_address2: 'Apt 214',
34        postal_code: 'W13 3BG',
35        city: 'London',
36        region: '',
37        phone: '01895808221',
38        country: 'GB',
39      },
40      order_amount: 10,
41      order_tax_amount: 0,
42      order_lines: [
43        {
44          type: 'physical',
45          reference: '19-402',
46          name: 'Battery Power Pack',
47          quantity: 1,
48          unit_price: 1000,
49          tax_rate: 0,
50          total_amount: 1000,
51          total_discount_amount: 0,
52          total_tax_amount: 0,
53          product_url: 'https://www.estore.com/products/f2a8d7e34',
54          image_url: 'https://www.exampleobjects.com/logo.png',
55        },
56      ],
57      customer: {
58        date_of_birth: '1970-01-01',
59        gender: 'male',
60      },
61    },
62    // callback
63    function (response) {
64      // ...
65    },
66  );
67} catch (e) {
68  // Handle error. The load~callback will have been called
69  // with "{ show_form: false }" at this point.
70}


1{
2  "show_form": true
3}


1{
2  "show_form": true,
3  "error": {
4    "invalid_fields": ["billing_address.email"]
5  }
6}


1{
2  "show_form": false
3}

When your customer presses the buy now button, you can authorize the order. In return, you'll receive an authorization token, which you'll then use to complete the payment.

Note

The authorize call may require the customer to provide more details, meaning that the response could be instant, could take a very long time (i.e. the time it takes the customer to complete the form), or might not happen (if the customer drops out). The integration, therefore, should not rely on an immediate response and should not implement timeouts on the merchant side, but, rather, wait for the callback function to be called.

Field name	Description
`options` required object	Use this to pass the `instance_id`.
`options.instance_id` required string	The ID of the Klarna Payments instance you want to authorize. You should use the `instance_id` from the load call above.
`data` optional object	Use this to provide any order or billing details that the customer has changed.
`callback` required function	Catches the response from `Klarna.Payments.authorize()` for further processing.


1try {
2  Klarna.Payments.authorize(
3    // options
4    {
5      instance_id: 'klarna-payments-instance', // Same as instance_id set in Klarna.Payments.load().
6    },
7    // data
8    {
9      billing_address: {
10        // ...
11      },
12    },
13    // callback
14    function (response) {
15      // ...
16    },
17  );
18} catch (e) {
19  // Handle error. The authorize~callback will have been called
20  // with "{ show_form: false, approved: false }" at this point.
21}


1{
2  "authorization_token": "b4bd3423-24e3",
3  "approved": true,
4  "show_form": true
5}


1{
2  "approved": false,
3  "show_form": true,
4  "error": {
5    "invalid_fields": ["billing_address.email"]
6  }
7}


1{
2  "approved": false,
3  "show_form": false
4}

If the authorization was successful, you will have received an authorization_token, which you can now use to place the customer's order.

Note

When you're processing a transaction via Klarna, you must only capture the payment once the goods have been shipped to the customer, unless you are selling an online service that the customer may use immediately.

You can find the full list, as well as complete request and response examples, in our API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "capture": false,
5  "source": {
6    "type": "klarna",
7    "authorization_token": "b4bd3423-24e3",
8    "locale": "en-GB",
9    "purchase_country": "GB",
10    "tax_amount": 0,
11    "billing_address": {
12      "given_name": "John",
13      "family_name": "Doe",
14      "email": "[email protected]",
15      "title": "Mr",
16      "street_address": "13 New Burlington St",
17      "street_address2": "Apt 214",
18      "postal_code": "W13 3BG",
19      "city": "London",
20      "phone": "01895808221",
21      "country": "GB"
22    },
23    "customer": {
24      "date_of_birth": "1970-01-01",
25      "gender": "male"
26    },
27    "products": [
28      {
29        "name": "Battery Power Pack",
30        "quantity": 1,
31        "unit_price": 1000,
32        "tax_rate": 0,
33        "total_amount": 1000,
34        "total_tax_amount": 0
35      }
36    ],
37    "custom_payment_method_ids": ["6m_149APR"]
38  }
39}

Information

Unlike the other payment method supports, Klarna is always synchronous. The redirect links contained in the response set Klarna-specific cookies, so that the customer is recognized in future payment requests.


1{
2  "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
3  "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
4  "amount": 1000,
5  "currency": "GBP",
6  "approved": true,
7  "status": "Authorized",
8  "response_code": "10000",
9  "response_summary": "Approved",
10  "source": {
11    "type": "klarna",
12    "order_id": "5ca8d9ed-d327-61a8-a8f7-c947073142ee",
13    "fraud_status": "ACCEPTED",
14    "authorized_payment_method": {
15      "number_of_days": 0,
16      "number_of_installments": 0,
17      "type": "invoice"
18    }
19  },
20  "customer": {
21    "date_of_birth": "1970-01-01",
22    "gender": "male"
23  },
24  "processed_on": "2019-01-15T10:59:51Z",
25  "reference": "ORD-5023-4E89",
26  "_links": {
27    "self": {
28      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
29    },
30    "actions": {
31      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
32    },
33    "klarna:payment-capture": {
34      "href": "https://api.checkout.com/klarna/orders/pay_jfcxs5vllp5ufden4lhe2wy4b4/captures/"
35    },
36    "klarna:payment-void": {
37      "href": "https://api.checkout.com/klarna/orders/pay_jfcxs5vllp5ufden4lhe2wy4b4/voids/"
38    }
39  }
40}

Information

The 202 response with an approved: true flag confirms that Klarna will process your payout as soon as you capture the payment in the next step.

Note

Klarna requires you to ship the product before capturing the payment. If, however, you provide the customer with immediate access to your product (e.g., you provide them with an online service), you can capture the payment as soon as the order is placed.

If you're shipping goods, it's a good idea to include the shipping_info for transparency as Klarna will include it in the correspondence with your customer.

Be careful not to capture payments on Klarna's Back Office.

post

https://api.checkout.com/klarna/orders/{payment_id}/captures

Header Value

Header	Value
`Authorization` required	`secret key` Use the valid secret key of your Checkout.com account. You can find this in the Hub.
`Content-Type` required	`application/json`

Authorization

required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

required

application/json

Path Value

Path	Value
`payment_id` required	The payment ID you received in the response when you placed the order.

payment_id

required

The payment ID you received in the response when you placed the order.

Field name Description

Field name	Description
`amount` optional integer	The amount you wish to capture. If you don't specify, you will capture the full payment amount.
`reference` optional string	A reference, such as an order number, you can later use to identify this payment.
`metadata` optional object	A set of key-value pairs that you can attach to a payment. You can use this to store additional information in a structured format.
`type` optional string	Type which can be used as a discriminator for a more generic capture endpoint with property bags.
`klarna` required object	Contains the order and shipping information.
`klarna.description` optional string	A description of the order shown to the customer. Up to 255 characters.
`klarna.products` optional array	The order details. This object is passed directly to Klarna as order_lines. See Klarna's documentation for more information.
`klarna.shipping_info` optional array	The shipping information for the order.
`klarna.shipping_delay` optional integer	The delay before the order is shipped. This field is currently not returned when reading the order. If you want to submit a value greater than 0, this needs to be enabled in your account. Please contact Klarna for further information.

amount

optional

integer

The amount you wish to capture. If you don't specify, you will capture the full payment amount.

reference

optional

string

A reference, such as an order number, you can later use to identify this payment.

metadata

optional

object

A set of key-value pairs that you can attach to a payment. You can use this to store additional information in a structured format.

type

optional

string

Type which can be used as a discriminator for a more generic capture endpoint with property bags.

klarna

required

object

Contains the order and shipping information.

klarna.description

optional

string

A description of the order shown to the customer.

Up to 255 characters.

klarna.products

optional

array

The order details.

This object is passed directly to Klarna as order_lines. See Klarna's documentation for more information.

klarna.shipping_info

optional

array

The shipping information for the order.

klarna.shipping_delay

optional

integer

The delay before the order is shipped. This field is currently not returned when reading the order.

If you want to submit a value greater than 0, this needs to be enabled in your account. Please contact Klarna for further information.


1{
2  "amount": 1000,
3  "reference": "ORD-5023-4E89",
4  "metadata": {},
5  "type": "klarna",
6  "klarna": {
7    "description": "Your order with Checkout.com",
8    "products": [
9      {
10        "name": "Battery Power Pack",
11        "quantity": 1,
12        "unit_price": 1000,
13        "tax_rate": 0,
14        "total_amount": 1000,
15        "total_tax_amount": 0
16      }
17    ],
18    "shipping_info": [
19      {
20        "shipping_company": "DHL US",
21        "shipping_method": "PickUpStore",
22        "tracking_number": "63456415674545679874",
23        "tracking_uri": "http://shipping.example/findmypackage?63456415674545679874",
24        "return_shipping_company": "DHL US",
25        "return_tracking_number": "93456415674545679888",
26        "return_tracking_uri": "http://shipping.example/findmypackage?93456415674545679888"
27      }
28    ],
29    "shipping_delay": 0
30  }
31}


1{
2  "action_id": "act_4sz4seltcrzuvcgaetumnlamq4"
3}


1{
2  "request_id": "beug8y83h978yh",
3  "error_type": "request_invalid",
4  "error_codes": ["customer_id_required", "given_name_exceed_length"]
5}

Information

If unsuccessful, you may receive a 403 Capture not allowed or 404 Payment not found error.

Klarna supports both partial and full refunds. You can refund a payment through the hub or using the refund API.

post

https://api.checkout.com/klarna/orders/{payment_id}/voids

Header Value

Header	Value
`Authorization` required	`secret key` Use the valid secret key of your Checkout.com account. You can find this in the Hub.
`Content-Type` required	`application/json`

Authorization

required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

required

application/json

Path Value

Path	Value
`payment_id` required	The payment ID (prefixed with `pay_`) you received in the response when you placed the order.

payment_id

required

The payment ID (prefixed with pay_) you received in the response when you placed the order.

Field name Description

Field name	Description
`reference` optional string	A reference, such as an order number, you can later use to identify this payment.
`metadata` optional object	A set of key-value pairs that you can attach to a payment. You can use this to store additional information in a structured format.

reference

optional

string

A reference, such as an order number, you can later use to identify this payment.

metadata

optional

object

A set of key-value pairs that you can attach to a payment. You can use this to store additional information in a structured format.


1{
2  "reference": "ORD-5023-4E89",
3  "metadata": {}
4}


1{
2  "action_id": "act_v6572a7elpuupbaljmoi4tk3ma"
3}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Information

If unsuccessful, you may get a 403 Void not allowed or 404 Payment not found error.

Klarna promo codes are an optional feature that can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, and so on) will be shown for a particular purchase.

Promo codes can also be used to provide promotional offers – for example, 0% financing – to specific customers. Please note that the usage of this feature can have commercial implications.

If you want to use this feature, reach out to Klarna and request promo codes to be configured for your account. After this has been set up, you can use promo codes by sending the custom_payment_method_ids field in the session creation request. You can see the payment option that the shopper has chosen in the authorized_payment_method object in the order creation response.

For more information, refer to the Klarna API Reference.

Note

To start testing, you'll need to:

create a test account, and
contact your Account Manager or Integrations engineer to activate Klarna payments in the sandbox environment.

Follow the steps above to display the Klarna widget ready for payment.
Select the desired payment method and pay.

Note

When testing, you may be asked to verify your details. If so, follow Klarna’s testing guide.

Information

Overview

Create a session

Header parameters

Body parameters

Note

Request example

Response examples

Information

Display widget

Add the JavaScript SDK to your page

Initialize the SDK

Add a container to your page

Note

Display available payment methods

Load the Klarna widget

Information

Example

Response examples

Authorize the order

Note

Example

Response examples

Place the order

Note

Endpoints

Request example

Response example

Information

Information

Capture the payment

Note

Header and path parameters

Body parameters

Request example

Response examples

Information

Refund a payment

Void a payment

Header and path parameters

Body parameters

Request example

Response examples

Information

Klarna promo codes

Testing Klarna

Note

Note