For PartnersFor Acquiring Partners
Klarna

On-Site Messaging API reference

Find here all details of the On-Site Messaging API.
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:
NameRequiredDescription
client_idYes for v3 routesUnique key that identifies a Klarna Merchant e-store.
placement_keyYesThe 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.
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 (USD 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.
AuthorizationYes for v4 routesWhen 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 Partner 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
1
Authorization: Basic klarna_live_client_pwhcueUff0MmwLShJiBE9JHA==
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.
401Unauthorized. Your Authorization key is incorrect or the host url is different than the one listed in the merchant portal.
403Forbidden. Your client_id is not enabled for On-Site Messaging 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.

Important considerations

Versioning

The On-Site Messaging 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 On-Site Messaging 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 On-Site Messaging API is not reachable or not responding for any reason.

Placement types

Placement types are containers of messages returned by On-Site Messaging.
The backend API implementation of On-Site Messaging 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 (for example, Footer or FAQ page) please see the On-Site Messaging 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.
null
Example of a credit promotion placement
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.
null
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 On-Site Messaging 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.
On-Site Messaging 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 customer 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 On-Site Messaging 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.
The API can return 2 image nodes:
  • KLARNA_BADGE: The Klarna badge. Always returned.
  • IMAGE_LEGAL: Legal content shown as an image, for example a credit warning. Returned on credit-promotion-badge placements in some markets. See also Legal content.
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" }
Example of IMAGE_LEGAL node:
JSON
1 2 3 4 5 6
{ "type": "IMAGE", "name": "IMAGE_LEGAL", "alt": "Watch out! Borrowing money costs money", "url": "https://eu-assets.klarnaservices.com/images/legal/..." }
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_MAINTEXTAlways returned.
TEXT_LEGALTEXTDepends on the market. If present, it must be rendered.
ACTION_LEARN_MOREACTIONAlways returned.
KLARNA_BADGEIMAGEAlways returned. Image in SVG format.
IMAGE_LEGALIMAGEDepends on the market, to meet local regulations. If present, it must be displayed as returned for compliance. Image in SVG format, so it scales with the surrounding text.

top-strip-promotion-badge

Node nameTypeDescription
TEXT_MAINTEXTAlways returned.
ACTION_LEARN_MOREACTIONAlways returned.
KLARNA_BADGEIMAGEAlways returned. Image in SVG format.
In some markets, the law sets out what credit advertising must show, for example under the revised EU Consumer Credit Directive (CCD2). Klarna aims to include the legal text and images these requirements call for, and returns them in 2 nodes:
  • TEXT_LEGAL: A text node carrying legal text.
  • IMAGE_LEGAL: An image node carrying legal content, for example a credit warning.
Integration requirement
Render TEXT_LEGAL and IMAGE_LEGAL whenever the response includes them. Place them close to the promotional messaging, directly under it, so the customer sees them together.
When you render this content yourself, you're responsible for checking that the messaging you show meets the requirements in each market you operate in. Klarna is responsible for how messaging is presented only when the Web SDK renders it.
Some markets have specific national requirements that go beyond showing the legal text. These include:
MarketRequirementAuthority
NetherlandsCredit warning (Kredietwaarschuwing)Dutch Authority for the Financial Markets (AFM)
SwedenCredit warning with a red warning triangle (Att låna kostar pengar!)Swedish Consumer Agency (Konsumentverket)
Klarna's Partner marketing legal guidelines explain how to advertise Klarna's credit products in each market, including the pre-approved copy and the disclosures to show with it:

Branding images

The API returns SVG images. If you want to use a different image type, use one of the hosted assets below.
null
Klarna Badge
null
Klarna logo black
null
Klarna white logo in transparent background
Support
Partner support•Service Status
Cookies|Terms & Conditions|Copyright Klarna AB 2026
Jump to section...