The only placement type keys that are currently fully supported are credit-promotion-badge and top-strip-promotion-badge.
We recommend integration via WebSDK to get full access to On-site messaging capabilities
Make sure you are calling the right endpoint per environment and region, the following query parameters are allowed:
Name | Required | Description |
---|---|---|
client_id | Yes | Unique key that identifies a Klarna Merchant e-store |
placement_key | Yes | The only allowed placement types are:
|
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. |
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. |
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. |
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":
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.
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
{
"content": {
"nodes": [
{
"type": "TEXT",
"name": "TEXT_MAIN",
"value": "Make 4 payments of $128.67. No fees."
},
{
"type": "ACTION",
Response shape
These are non amount-based placements that are designed to show messaging on landing pages.
{
"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.
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:
The lines of text for the ad. The number of text elements will change depending on the placement group requested.
{
"type": "TEXT",
"name": "TEXT_MAIN",
"value": "Buy now, pay later"
}
Example of text 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.{
"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
{
"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
Only SVG format is provided. If a different image format is needed, please see Branding images.
{
"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
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.
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. |
ACTION_PREQUALIFY | ACTION | Depends on market and if the merchant offers financing with Klarna. If present, it must be rendered. |
KLARNA_BADGE | IMAGE | Always returned. Image in SVG format. |
Node name | Type | Description |
---|---|---|
TEXT_MAIN | TEXT | Always returned. |
ACTION_LEARN_MORE | ACTION | Always returned. |
KLARNA_BADGE | IMAGE | Always returned. Image in SVG format. |
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://osm.klarnaservices.com/images/badges/klarna_v2_1.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