On-site messaging API Integration with Stripe Messaging Element

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:

https://api.playground.klarna.com/messaging/v4?placement_key=stripe-messaging-element&channel=<channel>&locale=<locale>&purchase_amount=<purchase_amount>

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

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.

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

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

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

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.

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

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

content

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

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?..."
}

{
  "type": "ACTION",
  "name": "ACTION_PREQUALIFY",
  "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"

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