Klarna for Payment Setup API

Last updated: May 13, 2026

To accept Klarna payments, you must:

Create a payment setup.
Update the payment setup and initialize Klarna as a payment method.
Configure the Klarna 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/payments/setups


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "EUR",
4  "amount": 1000,
5  "reference": "ORDER_01234",
6  "description": "Klarna payment",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  }
12}

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_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "EUR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Klarna payment",
9  "payment_methods": {
10    "klarna": {
11      "initialization": "disabled",
12      "status": "pending",
13      "flags": [
14        "initialization_not_enabled"
15      ]
16    }
17  },
18  "available_payment_methods": [
19    "klarna"
20  ],
21  "settings": {
22    "success_url": "https://example.com/payments/success",
23    "failure_url": "https://example.com/payments/failure"
24  }
25}

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

For Klarna, payment_methods contains the following fields:

initialization – The initialization status of the payment method, which can be either enabled or disabled.
status – The status of the payment method.
flags – An array of error codes or indicators that highlight missing or invalid information.

When the customer selects Klarna as the payment method on the checkout page, you must update the payment setup to:

Initialize the payment method.
Provide Klarna-specific configuration values.

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

Additionally, provide the following fields:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`billing.address.country` string	The two-letter ISO 3166-1 alpha-2 country code. Required
`currency` string	The three-letter ISO 4217 currency code. Required
`order.items` array	The list of items in the order. Each item must include `name`, `quantity`, `unit_price`, `total_amount`, and `reference`. Required
`customer.device.locale` string	The locale used to render the Klarna widget. For example, `en-UK`.
`customer.merchant_account.id` string	Your unique identifier for your customer's account.
`customer.merchant_account.last_modified` string	The date the customer last modified their account with you.
`customer.merchant_account.registration_date` string	The date the customer registered their account with the merchant.
`customer.merchant_account.returning_customer` boolean	Whether the customer is a returning customer.
`description` string	A description of the payment. Max length: 100 characters
`order.shipping.method` string	The shipping method for the order.
`order.sub_merchants` array	The list of sub-merchants associated with the order. Each item can include `id`, `product_category`, `number_of_sales`, and `registration_date`.
`reference` string	The payment reference. Max length: 80 characters


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "EUR",
4  "amount": 1000,
5  "reference": "ORDER_01234",
6  "description": "Klarna payment",
7  "payment_type": "Regular",
8  "billing": {
9    "address": {
10      "country": "DE"
11    }
12  },
13  "customer": {
14    "device": {
15      "locale": "en-GB"
16    }
17  },
18  "order": {
19    "items": [
20      {
21        "name": "Battery Power Pack",
22        "quantity": 1,
23        "unit_price": 1000,
24        "total_amount": 1000,
25        "reference": "ORDER_01234"
26      }
27    ]
28  },
29  "settings": {
30    "success_url": "https://example.com/payments/success",
31    "failure_url": "https://example.com/payments/failure"
32  },
33  "payment_methods": {
34    "klarna": {
35      "initialization": "enabled"
36    }
37  }
38}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "EUR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Klarna payment",
9  "payment_methods": {
10    "klarna": {
11      "initialization": "enabled",
12      "action": {
13        "type": "sdk",
14        "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
15        "session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
16      },
17      "status": "action_required",
18      "flags": []
19    }
20  },
21  "available_payment_methods": [
22    "klarna"
23  ],
24  "settings": {
25    "success_url": "https://example.com/payments/success",
26    "failure_url": "https://example.com/payments/failure"
27  }
28}

The response indicates an action_required status and returns payment_methods.klarna.action.client_token, which you use to initialize the Klarna SDK.

Use payment_methods.klarna.action.client_token from the update response to initialize and render Klarna on your checkout page. Then, the customer can confirm the payment using the Klarna widget.

After the customer completes the payment, the payment method status changes to ready.

Call the Get a payment setup endpoint, setting the id of the payment setup as the id path parameter, to check the status before confirming.

Information

You can subscribe to the payment_method_ready webhook to be notified when the payment method status changes to ready, without polling the endpoint.

get

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


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "EUR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Klarna payment",
9  "payment_methods": {
10    "klarna": {
11      "initialization": "enabled",
12      "status": "ready",
13      "flags": []
14    }
15  },
16  "available_payment_methods": [
17    "klarna"
18  ],
19  "settings": {
20    "success_url": "https://example.com/payments/success",
21    "failure_url": "https://example.com/payments/failure"
22  }
23}

When the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
klarna as the payment_method_name path parameter.

post

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

After confirming the payment, you receive the following webhooks depending on your capture configuration:

payment_pending – when the payment request is successfully initiated
payment_approved (manual capture only) – when the payment status changes to Approved
payment_captured (auto capture only) – when the payment is captured
payment_declined – if the payment is rejected

You can manage your webhooks using the API, or the Dashboard.

When integrating Klarna using the Payment Setup API, you can subscribe to the following webhooks:

Webhook	Description
`payment_method_ready`	Occurs when the customer authorizes the payment in the Klarna widget and the payment method status changes to `ready`.
`payment_pending`	Occurs when the payment confirmation request is successfully initiated.
`payment_approved` (only in manual capture payments)	Occurs when the payment is approved.
`payment_captured`	Occurs when the payment is successfully captured.
`payment_declined`	Occurs when the payment is rejected.
`payment_capture_declined` (only in manual capture payments)	Occurs when the capture request is rejected.
`payment_refunded`	Occurs when the payment is fully or partially refunded.
`payment_refund_declined`	Occurs when the refund fails.
`payment_voided` (only in manual capture payments)	Occurs when the payment is voided after authorization.
`payment_void_declined` (only in manual capture payments)	Occurs when the void request fails.

After the payment is confirmed, you can capture, refund, or void the payment:

To capture a payment, see Capture a payment.
To refund a payment, see Refund a payment.
To void a payment, see Void a payment.

To test your Klarna integration:

Contact your account manager or request support to activate Klarna payments in your Checkout.com sandbox environment.
Create a Klarna transaction by following the steps in this guide and using Klarna's sample customer data.
Complete the payment in the Klarna widget.

If successful, you receive a payment_captured or payment_approved webhook, depending on your capture configuration.

Contact your account manager or request support to move your integration to a production environment.

Depending on your merchant segment, Klarna may require additional information about the customer, the merchant, and the purchase. This information is known as extra merchant data (EMD).

Klarna uses EMD to complete an assertive risk assessment, enable new promotional products, and improve conversion rates.

For more information, see Klarna – Extra merchant data.

You can apply a discount to an individual item by providing the discount amount in order.items[].discount_amount.

Klarna for Payment Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Configure the Klarna SDK

Verify payment authorization

Information

Response example

Confirm the payment

Configure webhooks

Manage payments

Test your integration

Move your integration to the production environment

Optional features

Extra merchant data

Discounts