Klarna Docs - On-site messaging API reference

On-site messaging API reference

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

Other placement types may return content but they OSM cannot guarantee fully support of them.

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

NameRequiredDescription
client_idYesUnique key that identifies a Klarna Merchant e-store
placement_keyYesThe only allowed placement types are:
  • credit-promotion-badge
  • top-strip-promotion-badge
    If you want to use other placement types, please use the frontend integration way.
localeYesThe 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_amountNoThe 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.

NameRequiredDescription
user-agentYesCan be any string value. Requests will be blocked with a 403 status code, if this header is not present.

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

NameDescription
klarna-correlation-idUUID v4 formatted string.
Unique identifier for the request. Used for debugging.
cache-controlSpecifies 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 CodeDescription
200Successful request with content.
204Successful 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.
400Bad Request, check that all the required parameters are being sent and that format is valid.
403Forbidden. Your client_id is not enabled for OSM API calls.
404placement_key not found, client_id not found, or locale not available.
500Internal error, please contact us and send us the klarna-correlation-id present in the response headers so we can debug the issue.

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

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

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

Example of a credit promotion placement

Example of a credit promotion placement

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

Response shape

credit-promotion-badge with legal text and prequalify action

This is a variant that will also include a link for the customer to check if they qualify for credit before entering the checkout. Currently available in US and UK.

Example of placement with legal text and prequalify link

Example of placement with legal text and prequalify link

JSON
{
 "content": {
   "nodes": [
     {
       "type": "TEXT",
       "name": "TEXT_MAIN",
       "value": "Pay as low as $144/mo."
     },
     {
       "type": "TEXT",

Response shape

top-strip-promotion-badge

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

Example of top-strip-promotion ad
JSON
{
 "content": {
   "nodes": [
     {
       "type": "TEXT",
       "name": "TEXT_MAIN",
       "value": "Make 4 payments of $128.67. No fees."
     },
     {
       "type": "ACTION",

Response shape

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.

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.

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

Example of text node

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.

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 2 types of action nodes:

  • ACTION_LEARN_MORE: Link to a external page hosted on Klarna servers that displays more information to the customer about the advertised payment method
  • ACTION_PREQUALIFY: Link to an external page hosted on Klarna servers that allows the customer to perform a pre-qualify credit check. Note: This only applies if the merchant supports financing with Klarna.
JSON
{
  "type": "ACTION",
  "name": "ACTION_LEARN_MORE",
  "label": "Learn more",
  "url": "https://na-assets.klarnaservices.com/learn-more/index.html?..."
}

Example of ACTION_LEARN_MORE action

JSON
{
  "type": "ACTION",
  "name": "ACTION_PREQUALIFY",
  "label": "See if you're prequalified",
  "url": "https://na-assets.klarnaservices.com/eligibility/index.html?..."
}

Example of ACTION_PREQUALIFY case

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

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

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

Example of KLARNA_BADGE node

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.

List of 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_MAINTEXTAlways returned.
TEXT_LEGALTEXTDepends on the market. If present, it must be rendered.
ACTION_LEARN_MOREACTIONAlways returned.
ACTION_PREQUALIFYACTIONDepends on market and if the merchant offers financing with Klarna. If present, it must be rendered.
KLARNA_BADGEIMAGEAlways returned. Image in SVG format.
top-strip-promotion-badge
Node nameTypeDescription
TEXT_MAINTEXTAlways returned.
ACTION_LEARN_MOREACTIONAlways returned.
KLARNA_BADGEIMAGEAlways returned. Image in SVG format.

Branding images

The API returns svg images, if you want to use a different image type, please see below

Klarna Badge

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

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

Klarna logo black

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

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

Klarna white logo in transparent background

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

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