Documentation Portal

Global-e offers a checkout solution for e-commerce retailers looking to expand internationally, partnered with Klarna to enable pay later, slice it, or pay now across the e-stores (“merchants”) where their checkout is displayed.

Global-e owns all claims and liabilities on behalf of their merchants, so Klarna has signed them as a Merchant of Record and not as a partner. Each of the three Klarna regions (EU, US, and OC) has a single MID and credentials managed by Global-e. These credentials have been implemented in Global-e Checkout and are used across all Global-e merchants.

As Global-e only offers the checkout solution, merchants use their platform to manage other pages in the e-stores, this means that Global-e has no direct control over the implementation of Klarna On-Site Messaging (OSM) for the merchants.

The purpose of this section is to provide support for Global-e when working with merchants implementing Klarna OSM in their e-stores. The following guidelines describe the key considerations and best practices for implementation, especially when implementing OSM in multiple markets.

To maximize the performance of the OSM integration merchants should perform the following:

Check out our FAQ page for further information

There are several considerations for merchants integrating via Global-e, including but not limited to:

The On-Site Messaging (OSM) will only work by adding the JavaScript Library code snippet to all website pages along with the placements in specific places where you want messaging to appear.

Although the exact way merchants edit their e-store may differ depending on the e-commerce solution, the steps described below apply for all websites.

The JavaScript Library is the core part of On-Site Messaging integration. This library is used to communicate between the sub-merchants e-store and On-Site Messaging, and will render the content in the placements tags and not adding it to the merchants site will mean placements are not loaded. The On-Site JavaScript library delivers the core functionality of the On-Site Messaging:

More about how the On-Site JavaScript library works can be read here.

The JavaScript library contains three key attributes, these are:

Klarna provides three different Javascript libraries, one of each of the regions that are supported:

The countries currently supported in each region are listed in the below table:

If merchants are offering Klarna in different markets then they need to handle this in the OSM implementation by using the correct JavaScript library for the consumer. Below are the snippets for the iintegration of Global-e with Klarna:

To refresh placements we need to push an event into the data layer to inform the JavaScript Library the placements on the page have been altered. This should be triggered in the code after a change.

Example 

<script>
window.KlarnaOnsiteService = window.KlarnaOnsiteService || [];
window.KlarnaOnsiteService.push({ eventName: 'refresh-placements' });
</script>

Placement tags are the HTML tags that decide where to display messaging to visitors on your website. Placements require basic configurations to adjust them for your needs. Some attributes are required and others are optional.

Example of the attributes used in a placement

<!-- Placement v2 -->
<klarna-placement
data-key="credit-promotion-badge"
data-locale="en-GB"
data-purchase-amount="90000"
></klarna-placement>

<!-- end Placement →

It is important to correctly set the locale for the placement, based on the consumers' selection in the e-store.

Amount-based Placements

Amount-based placements include the data-purchase-amount attribute. This will deliver messaging with an offering for the specific price provided in micro units, where available. The placements can be used in many places across the website, such as cart view, product details page, product list page, etc.

It is recommended that either of the following data-key should be used:

Adaptive Width Placements

This type of placement will adjust to 100% of the width of the container element. They are labeled with (auto) instead of a pixel width. For best results, add this type of placement inside elements that span the entire width of the page, and with high visibility for the user: page header, after navigation bar, etc.

Adaptive Height Placements

This type of placement will adjust depending on the length of the content. They are labeled with (auto) instead of a pixel height to minimize the placement size.

One-line content generally renders a default height of 40px. Two lines of content generally render 55px. Some credit promotions require additional legal disclosures and tend to have two or, in some cases, three lines of content.

All responsive placements have an adaptive height. This is to allow the content to display correctly when the placement is constrained by a parent element or through CSS.

For this type of placement, it is recommended to avoid adding a fixed height or overflow: hidden to their container element.

Refreshing placements

There are use cases where we need to refresh the content of the placement on demand. The most popular ones are:

In those use cases, the JavaScript Library should be informed of changes to trigger messaging delivery for those placements or update the existing content to reflect changes. Our recommendation is to use such script.

Pre-loading placements

Some use-cases require the content to be pre-loaded in the placement before registering the impression. An example of this use case may be loading the ad in a pop-up triggered by a user action. If that is the case we want to have placement pre-loaded to deliver a fast experience, but we want to register the impression only if the content is displayed to the consumer.

To achieve this we need to make sure we do two things:

To configure placement as pre-loaded we have to add an attribute to the HTML tag called data-preloaded="true".

Once we will have placement configured correctly we have to fire the impression in the code.

Example

window.KlarnaOnsiteService =
window.KlarnaOnsiteService || []
window.KlarnaOnsiteService.push({
eventName: 'placement-impression',
placementKey: 'credit-promotion-standard'

})

Available Placements

Global-e should provide a list of available placements for the sub-merchant based on the region they wish to implement OSM. The list of placements can be accessed from the Merchant Portal for each region.

Outlined below are some of the common issues seen when implementing OSM: