Klarna Docs - On-site messaging API Integration with Stripe Messaging Element

On-site messaging API Integration with Stripe Messaging Element

Describes an API proposal for Stripe Messaging to leverage OSM API.

This document describes the integration steps needed to leverage Klarna's On-site Messaging API by Stripe for the Payment Method Messaging Element

To ensure secure communication, the API mandates the inclusion of two crucial headers for authentication. First, Stripe must pass an Authentication header containing the requisite credentials. Second, a Klarna-Account header is required to specify the Merchant ID (MID) of the sub-account on which operations are intended.

Initiate an HTTPS GET request to the OSM API using the programming language you prefer. Example:


Example of a request in EU Playground

Please ensure you target the appropriate API endpoint based on both the environment and the geographic region.

Testing Environment (Playground)
  • Europe: For European countries, use https://api.playground.klarna.com/messaging/v4
  • North America: For the United States and Canada, use https://api-na.playground.klarna.com/messaging/v4
  • Oceania: For Australia, New Zealand, etc., use https://api-oc.playground.klarna.com/messaging/v4
Production Environment
  • Europe: For European countries, use https://api.klarna.com/messaging/v4
  • North America: For the United States and Canada, use https://api-na.klarna.com/messaging/v4
  • Oceania: For Australia, New Zealand, etc., use https://api-oc.klarna.com/messaging/v4

The endpoint response will look like:

  "payment_options": [
      "payment_method_label": "Financing",
      "number_of_installments": 12,
      "payment_option_id": "asda23JuOi8vP2tybj1rcm46bXBjLXVzO",
      "content": {
        "nodes": [
            "name": "TEXT_MAIN",

Example of API response

Warning: Do not rely on the presence or absence of fields that are not publicly documented in our API. While we strive to maintain backwards compatibility and stability for publicly documented fields, additional fields may be added in the future. Please ensure that any validation of API responses is limited to the publicly documented fields.

Utilize the content payload from the API response to render the message. This can be accomplished through the programming language or framework of your preference.

The API endpoint returns a Cache-Control header, which should be adhered to whenever feasible. For web-based frontend integrations, this header is automatically managed by the browser.

Should the purchase amount undergo any changes, it necessitates a subsequent API call to update the displayed messaging. Once the new data is retrieved, the message should be re-rendered to reflect the current purchase amount.

As placement key `stripe-messaging-element` should be passed.

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

placement_keyYesThe only allowed placement types is:
  • stripe-messaging-element
localeYesThe language and the billing country as locale, supported: "en-AU","en-NZ","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-HU","hu-HU","en-IE","en-IT","it-IT","nl-NL","en-NL","no-NO","nb-NO","en-NO","en-PL","pl-PL","en-PT","pt-PT","en-RO","ro-RO","sv-SE","en-SE","en-CA","fr-CA","es-MX","en-MX","en-US","es-US"
channelYes'web' or 'app' . Used to identify the platform where the message will be shown.
purchase_amountYesThe amount of money in minor units ($120.00 = 12000), minor currency units are defined in ISO-4217.

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

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.
400Bad Request, check that all the required parameters are being sent and that their format is valid.
403Forbidden. Authentication error.
404placement_key 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.

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

Content object schema

The response will have an array of payment_options. Each item in the array represents a possible payment option for the passed amount and contains:

  • payment_method_label, the name of the payment method (string)
  • number_of_installments, the number of installments in case it is possible for the given payment method to pay the amount in installments (number | null)
  • payment_option_id, a unique identifier of the payment option
  • content: Array of nodes representing the content to be rendered.

Each element within the payment_options array includes a payment_method_label field, designating the type of payment option it represents. Note that these labels are not unique.
Possible Values: Installments, Financing, Pay Now, Pay Later.

This field serves as a unique identifier for each element in the payment_options array. Generated upon API invocation, this identifier is arbitrary in nature. In the context of Stripe's Messaging Element, this field can be ignored.


To facilitate seamless integration, each option is structured as a collection of nodes. These nodes encompass textual content, actionable elements (links), and images. The API has three node types:

Text node

It will have a name and value, as string.

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

Example of text node

Action node

The possible call-to-action buttons or links. These elements will contain a URL that should be opened when the user clicks on a button. In the context of Stripe's messaging element, this node can be ignored.

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.
  • ACTION_OPEN_TERMS: Link to the terms of the payment option

Each action node has a label property that can be used to find the word(s) in the TEXT nodes from which the provided url should be linked. For example in the following snippet of terms:

            "name": "TEXT_TERMS",
            "type": "TEXT",
            "value": "A higher initial payment may be required for some consumers. CA residents: Loans made or arranged pursuant to a California Financing Law license. See terms."
            "url": "https://cdn.klarna.com/1.0/shared/content/legal/terms/0/en_us/sliceitinx",
            "name": "ACTION_OPEN_TERMS",
            "type": "ACTION",
            "label": "terms"

The word "terms" inside the TEXT_TERMS needs to be linked to the url defined in the ACTION_OPEN_TERMS (defined as label)

  "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",
  "label": "See if you're prequalified",
  "url": "https://na-assets.klarnaservices.com/eligibility/index.html?..."


            "name": "TEXT_TERMS",
            "type": "TEXT",
            "value": "Please note that a higher initial payment may be required for some consumers. Fees may apply. Read the Pay later in 4 instalments terms for more information"
            "url": "https://cdn.klarna.com/1.0/shared/content/legal/terms/0/en_au/paylaterin4",
            "name": "ACTION_OPEN_TERMS",
            "type": "ACTION",
            "label": "terms"

Example ACTION_OPEN_TERMS with the relative TEXT_TERMS node.

Image node

This contains a link to the Klarna logo with relevant a11y alt text. 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