# Klarna for Payment Setup API

To accept Klarna payments, you must:

1. Create a payment setup.
2. Update the payment setup and initialize Klarna as a payment method.
3. Configure the Klarna SDK.
4. Verify payment authorization.
5. Confirm the payment.

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.

> **Information**
>
> The Payment Setup API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "EUR",
  "amount": 1000,
  "reference": "ORDER_01234",
  "description": "Klarna payment",
  "payment_type": "Regular",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

- `processing_channel_id` – The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier
- `amount` – The payment amount
- `currency` – The payment currency

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Klarna payment",
  "payment_methods": {
    "klarna": {
      "initialization": "disabled",
      "status": "initialization_required",
      "flags": []
    }
  },
  "available_payment_methods": [
    "klarna"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api#Payment_method_status).
- `flags` – An array of error codes or indicators that highlight missing or invalid information.

---

## Update the payment setup

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

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

Call the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint, setting `payment_methods.klarna.initialization` to `enabled`.

Additionally, provide the following fields:

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

> **Warning**
>
> Klarna only supports the local currency of each country. The `currency` value must map to the `billing.address.country` value. For example, if `billing.address.country` is `SE`, `currency` must be `SEK`. If any other value is used, including `EUR`, Klarna does not render as a payment option in Flow. For the full list of supported country and currency pairs, see Klarna's [purchase countries, currencies, and locales](https://docs.klarna.com/acquirer/klarna/get-started/data-requirements/puchase-countries-currencies-locales) documentation.

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "EUR",
  "amount": 1000,
  "reference": "ORDER_01234",
  "description": "Klarna payment",
  "payment_type": "Regular",
  "billing": {
    "address": {
      "country": "DE"
    }
  },
  "customer": {
    "device": {
      "locale": "en-GB"
    }
  },
  "order": {
    "items": [
      {
        "name": "Battery Power Pack",
        "quantity": 1,
        "unit_price": 1000,
        "total_amount": 1000,
        "reference": "ORDER_01234"
      }
    ]
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "klarna": {
      "initialization": "enabled"
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Klarna payment",
  "payment_methods": {
    "klarna": {
      "initialization": "enabled",
      "action": {
        "type": "sdk",
        "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzZXNzaW9uX2lkIiA6ICIw",
        "session_id": "0b1d9815-165e-42e2-8867-35bc03789e00"
      },
      "status": "action_required",
      "flags": []
    }
  },
  "available_payment_methods": [
    "klarna"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

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

---

## Configure 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.

---

## Verify payment authorization

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

Call the [Get a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/getAPaymentSetup) 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.

**Production**

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

**Sandbox**

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

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Klarna payment",
  "payment_methods": {
    "klarna": {
      "initialization": "enabled",
      "status": "ready",
      "flags": []
    }
  },
  "available_payment_methods": [
    "klarna"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

---

## Confirm the payment

When the payment status changes to `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

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

**Production**

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

**Sandbox**

`POST` `https://{prefix}.api.sandbox.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

---

## Configure webhooks

You can manage your webhooks using the [API](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/manage-webhooks-using-the-api.md), or the [Dashboard](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/manage-webhooks-in-the-dashboard.md).

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. |

---

## Manage payments

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

- To capture a payment, see [Capture a payment](https://www.checkout.com/docs/payments/manage-payments/capture-a-payment.md).
- To refund a payment, see [Refund a payment](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md).
- To void a payment, see [Void a payment](https://www.checkout.com/docs/payments/manage-payments/void-a-payment.md).

---

## Test your integration

To test your Klarna integration:

1. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_configuration_change&issue=case_configuration_issue_operational_change_request) to activate Klarna payments in your Checkout.com sandbox environment.
2. Create a Klarna transaction by following the steps in this guide and using Klarna's [sample customer data](https://docs.klarna.com/resources/test-environment/sample-customer-data/).
3. Complete the payment in the Klarna widget.

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

---

## Move your integration to the production environment

Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_configuration_change&issue=case_configuration_issue_operational_change_request) to move your integration to a production environment.

---

## Optional features

### Extra merchant data

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](https://docs.klarna.com/payments/web-payments/additional-resources/use-cases/extra-merchant-data/).

### Discounts

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