Klarna for Payments Setup API

Last updated: February 25, 2026

To accept Klarna payments, you must:

Create a payment setup.
Update the payment setup and initialize Klarna as a payment method.
Configure Klarna's JavaScript SDK.
Verify payment authorization.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payment-contexts


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 2000,
5  "reference": "test",
6  "description": "test-demo",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://success.co.uk",
10    "failure_url": "https://failure.co.uk"
11  },
12  "order":{
13    "items":[
14        {
15            "name": "Item1",
16            "quantity": 2,
17            "unit_price": 10,
18            "total_amount": 20,
19            "reference": "item-ref"
20        }
21    ]
22  },
23    "customer":{
24        "phone": {
25            "country_code": "44",
26            "number": "7898789879"
27        },
28        "email": {
29            "address": "test@email.com"
30        },
31        "device": {
32            "locale": "en-GB"
33    }
34  }
35}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency


1{
2    "id": "set_cmc6zms6g6oevkhdikey5sd2ky",
3    "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
4    "amount": 2000,
5    "currency": "GBP",
6    "payment_type": "Regular",
7    "reference": "test",
8    "description": "test-demo",
9    "payment_methods": {
10        "klarna": {
11            "initialization": "disabled",
12            "status": "available",
13            "flags": ["initialization_not_enabled"]
14        }
15    },
16    "available_payment_methods": [
17        "klarna"
18    ],
19    "settings": {
20        "success_url": "https://success.co.uk/",
21        "failure_url": "https://failure.co.uk/"
22    },
23    "customer": {
24        "email": {
25            "address": "test@email.com"
26        },
27        "phone": {
28            "country_code": "44",
29            "number": "7898789879"
30        },
31        "device": {
32            "locale": "en-GB"
33        }
34    },
35    "order": {
36        "items": [
37            {
38                "name": "Item1",
39                "quantity": 2,
40                "unit_price": 10,
41                "total_amount": 20,
42                "reference": "item-ref"
43            }
44        ]
45    }
46}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

For Klarna, payment_methods contains the following fields:

flags – An array of error codes or indicators that highlight missing or invalid information which you can prompt the customer to provide.
status – The status of the payment method.
initialization - The initialization status of the payment method, which can be either enabled or disabled. If initialization is disabled, you need to initialize the payment method before offering it to the customer.

When the customer selects Klarna, you must update the payment setup to:

Initialize the payment method.
Provide the required fields for Klarna.

Call the Update a payment setup endpoint, setting payment_methods.klarna.initialization to enabled.

Additionally, provide the following required fields:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1
`customer.device.locale` string	The locale of the customer's device.
`payment_methods.klarna.account_holder.billing_address.country` string	The customer's billing address country, as a two-letter ISO 3166 alpha-2 country code.
`order.items[]` array[object]	The list of items in the order. Minimum value: 1
`order.items[].name` string	The descriptive name of the line item.
`order.items[].quantity` integer	The quantity of the line item. Minimum value: 1
`order.items[].unit_price` string	The unit price of the line item, in the minor currency unit.
`order.items[].total_amount` string	The total cost of the line item, in the minor currency unit. The value should include any tax and discounts applied using the formula: `value = (quantity x unit_price) - discount_amount`.
`order.items[].reference` string	The line item reference or product stock keeping unit (SKU).


1{
2    "processing_channel_id": "{{ProcessingChannel-Klarna}}",
3    "currency": "GBP",
4    "amount": 2000,
5    "reference": "test",
6    "description": "test-demo",
7    "payment_type": "Regular",
8    "settings": {
9        "success_url": "https://success.co.uk",
10        "failure_url": "https://failure.co.uk"
11    },
12    "payment_methods": {
13        "klarna": {
14            "initialization": "enabled",
15            "account_holder": {
16                "billing_address": {
17                    "country": "GB"
18                }
19            }
20        }
21    },
22    "order": {
23        "items": [
24            {
25                "name": "Item1",
26                "quantity": 2,
27                "unit_price": 10,
28                "total_amount": 20,
29                "reference": "item-ref"
30            }
31        ]
32    },
33    "customer": {
34        "phone": {
35            "country_code": "44",
36            "number": "7898789879"
37        },
38        "email": {
39            "address": "test@email.com"
40        },
41        "device": {
42            "locale": "en-GB"
43        }
44    }
45}

In addition to the required fields, you can also send the following fields:

customer.email.address
customer.merchant_account.id
customer.merchant_account.registration_date
customer.merchant_account.last_modified
description
reference
order.shipping.method
order.sub_merchants[].id
order.sub_merchants[].number_of_sales
order.sub_merchants[].registration_date


1{
2    "id": "set_cmc6zms6g6oevkhdikey5sd2ky",
3    "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
4    "amount": 2000,
5    "currency": "GBP",
6    "payment_type": "Regular",
7    "reference": "test",
8    "description": "test-demo",
9    "payment_methods": {
10        "klarna": {
11            "initialization": "enabled",
12            "account_holder": {
13                "billing_address": {
14                    "country": "GB"
15                }
16            },
17            "action": {
18                "type": "sdk",
19                "client_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjgyMzA1ZWJjLWI4MTEtMzYzNy1hYTRjLTY2ZWNhMTg3NGYzZCJ9.eyJzZXNzaW9uX2lkIjoiMTRiNTAyMWItMjlhOC02MDczLTliNTMtOThmYjFlMmQwNWUyIiwiYmFzZV91cmwiOiJodHRwczovL2pzLnBsYXlncm91bmQua2xhcm5hLmNvbS9ldS9rcCIsImRlc2lnbiI6ImtsYXJuYSIsImxhbmd1YWdlIjoiZW4iLCJwdXJjaGFzZV9jb3VudHJ5IjoiR0IiLCJlbnZpcm9ubWVudCI6InBsYXlncm91bmQiLCJtZXJjaGFudF9uYW1lIjoiQ0tPIFBsYXlncm91bmQgUE5TIERpZ2l0YWwgU2VydmljZXMiLCJzZXNzaW9uX3R5cGUiOiJQQVlNRU5UUyIsImNsaWVudF9ldmVudF9iYXNlX3VybCI6Imh0dHBzOi8vZXUucGxheWdyb3VuZC5rbGFybmFldnQuY29tIiwic2NoZW1lIjp0cnVlLCJleHBlcmltZW50cyI6W3sibmFtZSI6ImtwYy1hYmUiLCJ2YXJpYXRlIjoidmFyaWF0ZS0xIn0seyJuYW1lIjoia3BjLW9wZi1yd24iLCJ2YXJpYXRlIjoidmFyaWF0ZS0xIn0seyJuYW1lIjoia3BjLW9wZi1maW5hbGl6ZS1pbi1wb3B1cCIsInZhcmlhdGUiOiJ2YXJpYXRlLTEifSx7Im5hbWUiOiJrcGMtb3NtLXdpZGdldCIsInZhcmlhdGUiOiJ2MSJ9LHsibmFtZSI6ImtwYy1wc2VsLTQ0MjkiLCJ2YXJpYXRlIjoiYSJ9LHsibmFtZSI6ImtwLWNsaWVudC1vbmUtcHVyY2hhc2UtZmxvdyIsInZhcmlhdGUiOiJ2YXJpYXRlLTEifSx7Im5hbWUiOiJrcGMtMWstc2VydmljZSIsInZhcmlhdGUiOiJ2YXJpYXRlLTEifSx7Im5hbWUiOiJrcC1jbGllbnQtdXRvcGlhLXN0YXRpYy13aWRnZXQiLCJ2YXJpYXRlIjoiaW5kZXgiLCJwYXJhbWV0ZXJzIjp7ImR5bmFtaWMiOiJ0cnVlIn19LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtZmxvdyIsInZhcmlhdGUiOiJ2YXJpYXRlLTEifSx7Im5hbWUiOiJrcC1jbGllbnQtdXRvcGlhLXNkay1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9LHsibmFtZSI6ImtwLWNsaWVudC11dG9waWEtd2Vidmlldy1mbG93IiwidmFyaWF0ZSI6InZhcmlhdGUtMSJ9XSwicmVnaW9uIjoiZXUiLCJ1YV9lbmFibGVkX2FuZF9vbmVfcG0iOnRydWUsIm9yZGVyX2Ftb3VudCI6MjAwMCwib2ZmZXJpbmdfb3B0cyI6MCwib28iOiIxcyIsInZlcnNpb24iOiJ2MS4xMC4wLTE1OTAtZzNlYmMzOTA3IiwiYSI6MH0.IidFz51ZWo_ozXOGQn1dJy6fMW6UVIZbyl37YbOYzAGtJb0y1H5_P_sLo7ads37-gVq9MeIGlM9jYMrnpLINjFEWndpC_bBT49k-uFWo6QpKhkf4rZwFul9-F2op7qNL_U6cpAtqNJUx3-uVeUw1GNu57Kf58eh2lWUEnO_Pa8U4pAUKNKiQ9satYl9rlDDA6m1vrjduwq_LkXYj6sC_kdyE1fLcFqd6zoa40WENkqUlEek4raBCrLth4nBl-rhjCBzGxMCBI74Pc5gv_VbvFPlULfURagdLwLqFZmqcsbxufmwR5I8GfWVjTHQ7Q8swgoBgjyZ71J1ogUBwRxlpzw",
20                "session_id": "a8297b13-41e8-4a0f-81c5-d36f094114a2"
21            },
22            "status": "action_required",
23            "flags": []
24        }
25    },
26    "available_payment_methods": ["klarna"],
27    "settings": {
28        "success_url": "https://success.co.uk/",
29        "failure_url": "https://failure.co.uk/"
30    },
31    "customer": {
32        "email": {
33            "address": "test@email.com"
34        },
35        "phone": {
36            "country_code": "44",
37            "number": "7898789879"
38        },
39        "device": {
40            "locale": "en-GB"
41        }
42    },
43    "order": {
44        "items": [
45            {
46                "name": "Item1",
47                "quantity": 2,
48                "unit_price": 10,
49                "total_amount": 20,
50                "reference": "item-ref"
51            }
52        ]
53    }
54}

The response returns the Klarna token and session ID required to proceed with the Klarna JavaScript SDK.

The Klarna JavaScript SDK enables you to display the Klarna widget in your site:

Add the Klarna script to your web application.


1<script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>

Initialize the Klarna SDK with the client_token and session_id that you received after initializing Klarna:


1window.klarnaAsyncCallback = function () {
2    Klarna.Payments.init({
3      client_token:"eyJhbGciOiJub...",
4      session_id: "a8297b13-41e8-4a0f-81c5-d36f094114a2"
5    });
6};

Place a container on your page to render Klarna as a payment option.


1<div id="klarna-payments-container"></div>

Load the Klarna widget into the container.


1Klarna.Payments.load(
2  {
3    container: '#klarna-payments-container'
4  },
5  {},
6  function (res) {
7    console.debug(res);
8  }
9)

Information

For a better user experience, call load() when you load your checkout page. This ensures that the container for Klarna payments loads immediately in a hidden container, and is ready to display when needed.

For more information, see Klarna docs:

After the customer authorizes the payment in the Klarna widget, the payment method status sets to ready.

Call the Get a Payment Setup endpoint, setting the id of the payment setup as the id path parameter to check the payment method status.

post

https://{prefix}.api.checkout.com/payments/setups/{id}


1{
2    "id": "set_cmc6zms6g6oevkhdikey5sd2ky",
3    "processing_channel_id": "pc_vxhxgm52yoxejcsdtoffscf35i",
4    "amount": 2000,
5    "currency": "GBP",
6    "payment_type": "Regular",
7    "reference": "test",
8    "description": "test-demo",
9    "payment_methods": {
10        "klarna": {
11            "initialization": "enabled",
12            "account_holder": {
13                "billing_address": {
14                    "country": "GB"
15                }
16            },
17            "status": "ready",
18            "flags": []
19        }
20    },
21    "available_payment_methods": ["klarna"],
22    "settings": {
23        "success_url": "https://success.co.uk/",
24        "failure_url": "https://failure.co.uk/"
25    },
26    "customer": {
27        "email": {
28            "address": "test@email.com"
29        },
30        "phone": {
31            "country_code": "44",
32            "number": "7898789879"
33        },
34        "device": {
35            "locale": "en-GB"
36        }
37    },
38    "order": {
39        "items": [
40            {
41                "name": "Item1",
42                "quantity": 2,
43                "unit_price": 10,
44                "total_amount": 20,
45                "reference": "item-ref"
46            }
47        ]
48    }
49}

After the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint, providing the id of the payment setup as the id path parameter, and klarna as the payment_method_name path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/klarna

Klarna for Payments Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Additional fields

Response example

Configure the Klarna JavaScript SDK

Information

Verify payment authorization

Response example

Confirm the payment