KLARNA- (Klarna Payments) - WEBSALE Dokumentation

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

{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}

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.

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.

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

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

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.

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.

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.

{KLARNA-NeedUpdate}
   <script>
      Klarna.Payments.load({ container: "#klarna_payments_container" });
   </script>
{/KLARNA-NeedUpdate}

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.

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.

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

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.

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

{KLARNA-MerchantID}
   <form action="~FORM-Basket~" method="post">
      <input type="hidden" name="~KLARNA-AddressDataName~" id="klarna-address-data">
      ...
   </form>
{/KLARNA-MerchantID}

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.

{KLARNA-ObsoleteMode}
   <!-- Aufbau für die ältere Anbindung -->
{/KLARNA-ObsoleteMode}

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

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.

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

​Displaying the widget

​Retrieving the authorization

​When the order data has changed

​The order data as JSON

​Express checkout in the basket

​The old integration

​The tags at a glance

​Related topics

Displaying the widget

Retrieving the authorization

When the order data has changed

The order data as JSON

Express checkout in the basket

The old integration

The tags at a glance

Related topics