> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# KLARNA- (Klarna Payments)

> The tags of the Klarna Payments direct integration: display the widget, retrieve the authorization, evaluate order data as JSON and detect when the Klarna session needs to be updated.

With the Klarna Payments direct integration, part of the payment process takes place in the buyer's browser. The shop sets up a session with Klarna, the Klarna script uses it to display its widget, and after the buyer authorizes, a token comes back with which the shop completes the order.

The `KLARNA-` tags provide exactly the building blocks this exchange needs: the two tokens, the field names for the hidden input fields, the return address and the order data as JSON. In addition, there are three area tags that query the state of the Klarna session.

The tags are distributed across three pages of the order process. The basket contains the tags for express checkout, while the payment and shipping method page and the order overview contain the widget and the authorization.

Guide: Klarna Payments · Guide: JSON interface

## Displaying the widget

The Klarna script needs the client token to build its widget.

| Tag | Returns |
| - | - |
| `KLARNA-ClientToken` | the client token of the current Klarna session |
| `KLARNA-ShowKlarnaAtPayDeliv` | takes effect if the widget should already appear on the payment and shipping method page |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{KLARNA-ClientToken}
   <div id="klarna_payments_container"></div>

   <script>
      Klarna.Payments.init({ client_token: "~KLARNA-ClientToken~" });
   </script>
   <script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>
{/KLARNA-ClientToken}
```

> [!NOTE]
>
> Always wrap the integration in an area tag. Without a valid Klarna session, the token is empty, and the script builds an empty widget that the buyer cannot use.

> [!WARNING]
>
> An empty client token is not necessarily a configuration error. If the shop runs in the mode with a locked Klarna session, the tag deliberately does not output the token unless the Klarna Payments tunnel is active. In this case, check the operating mode first before reviewing the credentials.

> [!NOTE]
>
> `KLARNA-ShowKlarnaAtPayDeliv` is not described in the previous documentation. The tag combines two conditions: the setting that Klarna should already appear on the payment and shipping method page, and that the session is not locked. This lets you decide in one place whether the widget appears there or only on the order overview.

## Retrieving the authorization

After authorization, the Klarna script returns a token that the shop needs. To do this, the template sends the buyer to a dedicated return address and appends the token as a parameter.

| Tag | Returns |
| - | - |
| `KLARNA-AuthCallbackURL` | the address to which the buyer is redirected after successful authorization |
| `KLARNA-AuthTokenName` | the name of the parameter or field for the token |
| `KLARNA-AuthTokenValue` | the token, after the shop has received it |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<script>
   Klarna.Payments.authorize({}, function (res) {
      if (res.authorization_token) {
         const redirectURL = new URL("~KLARNA-AuthCallbackURL~");
         redirectURL.searchParams.append("~KLARNA-AuthTokenName~", res.authorization_token);
         window.location.href = redirectURL.href;
      }
   });
</script>
```

> [!WARNING]
>
> `KLARNA-AuthCallbackURL` outputs the address with unencoded ampersands because it is intended for JavaScript. In this form, it does not belong in an HTML attribute. Use it inside a script as in the example.

> [!NOTE]
>
> The field name is fixed in the shop system. Don't write it by hand; always take it from `KLARNA-AuthTokenName`, otherwise the shop won't recognize the returned token.

> [!NOTE]
>
> `KLARNA-AuthTokenValue` is only filled after the return. As an area tag, it is suitable for building the order overview differently depending on the state of the authorization.

## When the order data has changed

The Klarna session contains a copy of the order and address data. If the buyer then changes something, for example the quantity or the delivery address, the two no longer match.

`KLARNA-NeedUpdate` takes effect in exactly this case.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{KLARNA-NeedUpdate}
   <script>
      Klarna.Payments.load({ container: "#klarna_payments_container" });
   </script>
{/KLARNA-NeedUpdate}
```

> [!WARNING]
>
> This area tag is not a placeholder for future extensions, even though the previous description suggests so. It marks the state in which the Klarna session is outdated. If it is not updated before the buyer places the order, the shop system rejects the order completion, because an update is no longer possible after authorization. The buyer then sees an abort without any recognizable reason.

> [!NOTE]
>
> In the mode with a locked Klarna session, the area tag never takes effect, because a new session is set up for each pass anyway. The template may still contain the area tag; it then simply has no effect.

## The order data as JSON

`KLARNA-OrderDataJSON` outputs the data that the shop passes to Klarna, including billing and delivery address. This is especially useful for express checkout, where the address comes from Klarna and is to be displayed in the shop.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "purchase_country": "DE",
   "purchase_currency": "EUR",
   "locale": "de-DE",
   "order_amount": 700,
   "billing_address": {
      "city": "Berlin",
      "country": "DE",
      "email": "kunde@example.de",
      "family_name": "Mustermann",
      "given_name": "Max",
      "postal_code": "10178",
      "street_address": "Musterstraße 2",
      "street_address2": null
   },
   "shipping_address": { }
}
```

You retrieve individual values from it with the tags of the JSON interface.

> [!NOTE]
>
> The JSON is regenerated from the current basket and address data each time the tag is evaluated. It is therefore always up to date, but it also has a cost. Evaluate it once and then continue working with the JSON interface instead of placing the tag several times.

> [!NOTE]
>
> The output is converted from UTF-8 to the shop's character set. Umlauts in the addresses supplied by Klarna therefore appear in the encoding that the rest of the page also uses.

Reference: EJD- (JSON interface)

## Express checkout in the basket

With express checkout, the buyer starts the payment process in the basket, and Klarna supplies the address data.

| Tag | Returns |
| - | - |
| `KLARNA-MerchantID` | the MerchantID stored in the shop configuration |
| `KLARNA-AddressDataName` | the field name for the hidden field with the address data from Klarna |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{KLARNA-MerchantID}
   <form action="~FORM-Basket~" method="post">
      <input type="hidden" name="~KLARNA-AddressDataName~" id="klarna-address-data">
      ...
   </form>
{/KLARNA-MerchantID}
```

> [!NOTE]
>
> This field name is also fixed. The Klarna script writes the address data to the field, and the shop reads it on submission under exactly this name.

## The old integration

`KLARNA-ObsoleteMode` distinguishes between the two operating modes of the integration. The area tag takes effect if the shop is **not** running in the mode with a locked Klarna session, that is, in the older variant.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{KLARNA-ObsoleteMode}
   <!-- Aufbau für die ältere Anbindung -->
{/KLARNA-ObsoleteMode}

{!KLARNA-ObsoleteMode}
   <!-- Aufbau für die gesperrte Sitzung -->
{/!KLARNA-ObsoleteMode}
```

> [!NOTE]
>
> You only need this area tag as long as a template has to serve both variants. Once the migration is complete, you can remove the branch that is no longer needed and dissolve the area tag.

## The tags at a glance

| Tag | Single tag | Area tag | Negative area tag | Loop tag |
| - | - | - | - | - |
| `KLARNA-ClientToken` | yes | yes | yes | – |
| `KLARNA-OrderDataJSON` | yes | yes | yes | – |
| `KLARNA-AuthTokenName` | yes | – | – | – |
| `KLARNA-AuthTokenValue` | yes | yes | yes | – |
| `KLARNA-AuthCallbackURL` | yes | – | – | – |
| `KLARNA-MerchantID` | yes | yes | yes | – |
| `KLARNA-AddressDataName` | yes | – | – | – |
| `KLARNA-NeedUpdate` | – | yes | yes | – |
| `KLARNA-ShowKlarnaAtPayDeliv` | – | yes | yes | – |
| `KLARNA-ObsoleteMode` | – | yes | yes | – |

`KLARNA-MerchantID` and `KLARNA-AddressDataName` belong on the basket page `ws_basket.htm`, `KLARNA-AuthTokenName` and `KLARNA-AuthCallbackURL` on the order overview page `ws_place_order.htm`, and `KLARNA-ClientToken` on both pages of the payment process. The other tags are permitted on all templates.

## Related topics

* Guide: Klarna Payments
* Reference: EJD- (JSON interface)
* Reference: ST- (Page states)
* Reference: MSG- (Messages)


## Related topics

- [Payment methods](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/zahlungsarten.md)
- [Buttons for payment methods](https://dokumentation.websale.de/en/v8s/referenz/tags/bt/zahlungsarten.md)
- [PAY- (Displaying and selecting payment methods)](https://dokumentation.websale.de/en/v8s/referenz/tags/pay/zahlungsarten-anzeigen-und-auswaehlen.md)
- [Payment method codes](https://dokumentation.websale.de/en/v8s/materialien/zahlungsarten-codes.md)
- [stripe](https://dokumentation.websale.de/en/frontend/funktionsubersicht/zahlungsarten/stripe.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.