On-site messaging API reference

Find here all details of the On-site messaging API.

9 min read

Find here all details of On-site messaging API.

Recommended for integration

The only placement type keys that are currently fully supported are credit-promotion-badge and top-strip-promotion-badge.

We recommend integration via Web SDK to get full access to On-site messaging capabilities.

On-site messaging API specifications

Make sure you are calling the right endpoint per environment and region, the following query parameters are allowed:

Name	Required	Description
`client_id`	Yes for v3 routes	Unique key that identifies a Klarna Merchant e-store.
`placement_key`	Yes	The only allowed placement types are `credit-promotion-badge` and `top-strip-promotion-badge`. If you want to use other placement types, please use the frontend integration way.
`locale`	Yes	The language and the billing country of the ad. The following values are applicable: `"en-AT", "de-AT", "nl-BE", "en-BE", "fr-BE", "en-CH", "de-CH", "it-CH", "fr-CH", "en-CZ", "cs-CZ", "de-DE", "en-DE", "da-DK", "en-DK", "es-ES", "en-ES", "fi-FI", "sv-FI", "en-FI", "fr-FR", "en-FR", "en-GB", "en-GR", "el-GR", "en-IE", "en-IT", "it-IT", "nl-NL", "en-NL", "no-NO", "nb-NO", "en-NO", "en-PL", "pl-PL", "en-PT", "pt-PT", "sv-SE", "en-SE", "en-CA", "fr-CA", "es-MX", "en-MX", "en-US", "es-US", "en-AU", "en-NZ"`.
`purchase_amount`	No	The amount of money in minor units ($120.00 = 12000), minor currency units are defined in ISO-4217. Required for amount-based credit promotion placements.

Along with the query params you need to pass request headers to the API. If you are calling the API from your frontend, this will be handled automatically.

Name	Required	Description
`user-agent`	Yes	Can be any string value. Requests will be blocked with a 403 status code, if this header is not present.
`Authorization`	Yes for v4 routes	When you choose to integrate messaging using the v4 route it is essential to add this header attribute in the headers. The value is the API Key which can be acquired from Klarna Portal.

Authentication

Klarna messaging API uses HTTP basic authentication. To authenticate, use your API credentials that consist of:

A username linked to your Klarna merchant ID (MID)
A password associated with your username

If you're using an API platform that lets you store your credentials, you can add them in relevant fields.

A sample authorization request header with Base64-encoded credentials:

JSON

Authorization: Basic klarna_live_client_pwhcueUff0MmwLShJiBE9JHA==

The API will also return response headers, for debugging and caching purposes.

Name	Description
`klarna-correlation-id`	UUID v4 formatted string. Unique identifier for the request. Used for debugging.
`cache-control`	Specifies how long the response should be cached. Integrator needs to honor this header when possible. Default value is: private, max-age=86400.

Depending on your request the API will return the relevant status code:

Status Code	Description
200	Successful request with content.
204	Successful request, no content to display. This can happen if the `purchase_amount` is out of range for all of your product configuration, locale not available, and many other configurations.
400	Bad Request, check that all the required parameters are being sent and that format is valid.
401	Unauthorized. Your Authorization key is incorrect or the host url is different than the one listed in the merchant portal.
403	Forbidden. Your `client_id` is not enabled for OSM API calls.
404	`placement_key` not found, `client_id` not found, or `locale` not available.
500	Internal error, please contact us and send us the `klarna-correlation-id` present in the response headers so we can debug the issue.

Important considerations

Versioning

The OSM team will try to prevent making breaking changes to the API as much as possible, but in the case this is not possible, we will create a new version of the API endpoint and communicate with the integrator as soon as possible so they can update to the latest version.

The following changes are considered as "non-breaking":

Addition of optional or read-only fields/properties
Re-ordering of fields in the JSON response
Re-ordering or addition of nodes in the JSON response nodes array
Addition of HTTP headers
Addition of new values to an enum if there is a default defined
Addition of new HTTP methods to existing resources

HTTP call recommendations

We recommend integrators make the HTTP call in an asynchronous way and set a sensible HTTP client timeout when calling the OSM API. We suggest that the HTTP client timeout be set to at least 5 seconds. This will prevent the user experience on your application to be degraded if the OSM API is not reachable or not responding for any reason.

Placement types

Placement types are containers of messages returned by OSM.

The backend API implementation of OSM currently supports these two types of placements:

credit-promotion-badge
top-strip-promotion-badge

Other placement types via library

If you want other types of placements (e.g. Footer or FAQ page) please see the OSM library integration.

credit-promotion-badge

These are amount-based placements that will deliver messaging with an offering for the specific purchase_amount provided, where available. The placements can be used in various places across the website, such as cart view, product details page, product list page, etc.

Response shape:

JSON

1 2 3 4 5 6 7 8 9 10

{
 "content": {
   "nodes": [
     {
       "type": "TEXT",
       "name": "TEXT_MAIN",
       "value": "Make 4 payments of $128.67. No fees."
     },
     {
       "type": "ACTION",

top-strip-promotion-badge

These are non amount-based placements that are designed to show messaging on landing pages.

Example of a top-strip-promotion-badge placement

JSON

1 2 3 4 5 6 7 8 9 10

{
 "content": {
   "nodes": [
     {
       "type": "TEXT",
       "name": "TEXT_MAIN",
       "value": "Make 4 payments of $128.67. No fees."
     },
     {
       "type": "ACTION",

Rendering ads

Once you get the response from the OSM API endpoint you can render the ad in your application using the content object present in the response.

Integration requirement

When you render a placement based on the response DO NOT rely on the type of node but rather on the name. This is because we may add more nodes of the same type, but the name will always be unique.

Content object schema

For easier integration, we defined an Ad as a collection of nodes. These nodes contain the text, actions (or links) elements of the ad, and the image/s needed to render the Ad.

OSM supports 3 types of nodes:

Text node

The lines of text for the ad. The number of text elements will change depending on the placement group requested.

Example of text node:

JSON

1 2 3 4 5

{
  "type": "TEXT",
  "name": "TEXT_MAIN",
  "value": "Buy now, pay later"
}

Action node

The possible call-to-action buttons or links contained in the ad. These elements will contain a URL that should be opened when the user clicks on the button/link.

Mobile integration link behavior

Note for mobile integrations: On mobile integrations, we suggest that the link opens in a WebView (or equivalent) container so the customer doesn't have to leave the application.

We currently support 1 type of action nodes:

ACTION_LEARN_MORE: Link to an external page hosted on Klarna servers that displays more information to the customer about the advertised payment method.

Example of ACTION_LEARN_MORE action:

JSON

1 2 3 4 5 6

{
  "type": "ACTION",
  "name": "ACTION_LEARN_MORE",
  "label": "Learn more",
  "url": "https://na-assets.klarnaservices.com/learn-more/index.html?..."
}

Image node

URL of the image needed to display the OSM ad.
Alternative text is also provided for accessibility reasons.

Only SVG format provided

Only SVG format is provided. If a different image format is needed, please see the Branding images section below.

Example of KLARNA_BADGE node:

JSON

1 2 3 4 5 6

{
  "type": "IMAGE",
  "name": "KLARNA_BADGE",
  "alt": "Klarna",
  "url": "http://us-assets.klarnaservices.com/images/badges/klarna.svg"
}

Recommended for integration

Important considerations regarding the nodes array

Unrecognized nodes or properties in nodes should be ignored during de-serialization and not cause an error. This will allow forward compatibility for new properties and nodes.
Each type of node has a different object schema, you can check these schemas on the attached Open API document.

Available nodes by type of placement

Each type of placement will have a different representation in nodes. For example: top-strip placements don't have a TEXT_LEGAL node. Here is a list of all the possible nodes that can be returned per placement.

credit-promotion-badge

Node name (unique)	Type (not unique)	Description
`TEXT_MAIN`	TEXT	Always returned.
`TEXT_LEGAL`	TEXT	Depends on the market. If present, it must be rendered.
`ACTION_LEARN_MORE`	ACTION	Always returned.
`KLARNA_BADGE`	IMAGE	Always returned. Image in SVG format.

top-strip-promotion-badge

Node name	Type	Description
`TEXT_MAIN`	TEXT	Always returned.
`ACTION_LEARN_MORE`	ACTION	Always returned.
`KLARNA_BADGE`	IMAGE	Always returned. Image in SVG format.

Branding images

The API returns SVG images. If you want to use a different image type, use one of the hosted assets below.

PNG: https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.png

SVG: https://osm.klarnaservices.com/images/badges/klarna_v2_1.svg

PNG: https://us-assets.klarnaservices.com/images/logo_black.png

SVG: https://us-assets.klarnaservices.com/images/logo_black.svg

PNG: https://us-assets.klarnaservices.com/images/logo_white.png

SVG: https://us-assets.klarnaservices.com/images/logo_white.svg

Jump to section...