Payment form and interoperability data

Enable a seamless checkout experience by integrating its payment presentation and interoperability features to enhance the checkout experience with up-to-date payment method listings.

​With this integration path, Acquiring Partners are responsible for:

  • Supporting Partners in building the payment form and selector.
  • Directly referring to Klarna’s official presentation requirements in their documentation - see how to present Klarna.
  • Ensuring compatibility with Klarna’s Payment Presentation API, if applicable.

This guide outlines how to handle interoperability parameters and return dynamic Klarna assets to Partners, using Klarna’s Presentation API. Here's an overview of all the steps to support dynamic payment method listing:

  • Include Klarna presentation rules in your documentation
  • Support interoperability_token and interoperability_data in your APIs
  • Forward these values unaltered to Klarna’s APIs
  • Use Klarna’s Payment Presentation API to fetch assets
  • Return Klarna’s presentation data to your Partners in a consistent format.
  • Optionally serialize the full response from the Payment Presentation API into klarna_payment_presentation_data

This step only applies to Acquiring Partners that have APIs that allow Partners to retrieve available payment methods.

If an Acquiring Partner provides an API for retrieving payment methods, it must:

  • Accept interoperability_token and interoperability_data in requests.
  • Use Klarna’s Payment Presentation API to fetch the most up-to-date Klarna content.
  • Include Klarna-specific display instructions and assets (labels, icons, etc.) in the API response sent to Partners.

Klarna uses interoperability_token and interoperability_data to ensure all information and context associated with a Payment Transaction is preserved throughout the journey of a customer. These must be forwarded accurately.

Below an example of how Acquiring Partners can accept the interoperability parameters in their Get Payment Method API endpoint.

Sample request

JSON
{
  "currency": "USD",
  "amount": 17800,
  "locale": "en-US",
  "payment_method_options": {
    "klarna": {
      "interoperability_token": "eyJhbGciOiJ...",
      "interoperability_data": "****"
    }
  }

You should name these fields clearly, using either:

  • klarna_interoperability_token / klarna_interoperability_data, or
  • interoperability_token / interoperability_data (in Klarna-specific context).

This ensures easy identification for any Partner.

Parameter validation guidelines

As those parameters can change over time and are versioned so that the third party integration continues to work, Acquiring Partners need to respect these guidelines if they wish to validate parameters:

ParameterTypeMax lengthValidation

interoperability_token

string8192 charsOptional: verify length only

interoperability_data

string (stringified JSON object)10240 charsOptional: check for valid JSON

The Acquiring Partner can validate the input based on the provided guidelines but must not modify it. The input must always be forwarded as received, without any interference.

The Klarna Payment Presentation API enables Acquiring Partners to retrieve Klarna-branded presentation assets (e.g. button text, icons, descriptors) tailored to a specific payment context. These assets help Partners render Klarna in compliance with Klarna’s brand and UX guidelines.

getPresentationAPI
ParameterRequiredDescription
Klarna-Interoperability-Token
No

The interoperability token enables continuity of customer journey across domains and services. If you are an Acquiring Partner, you receive this token from your merchant.

Klarna-Customer-Token
No

The customer token represents the tokenized customer and allows you to act on behalf of the customer.

Klarna-Integration-Metadata
No

Metadata about the integrator and originators of the request, a valid JSON object string literal, to improve troubleshooting. Read more here

The header value as appearing on...

Read more
integrator
Yes

An integrator is the entity that is responsible for the integration with Klarna.

name
Yes

The name of the integrator using SCREAMING_SNAKE_CASE.

session_reference
Yes

A reference to the session that is being used.

module_name
No

The name of the module that is being used to initiate the request

module_version
No

The version of the module that is being used. Can be a semantic version, commit hash, date or any other versioning scheme to identify which code that issued the request.

originators
No

Array of originators that are responsible for the request. If the request is sent through multiple systems before reaching the integrator, each system can be represented as an originator.

name
Yes

The name of the originator using SCREAMING_SNAKE_CASE.

session_reference
Yes

A reference to the session that is being used.

module_name
No

The name of the module that is being used.

module_version
No

The version of the module that is being used.

Partner-Correlation-Id
No

An optional alpha numerical String that the partner can use to correlate. This value will be returned in the response.

Consult the API reference getPresentationAPI for a complete description of the parameters.

Sample request

SHELL
curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/presentation \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Interoperability-Token: eyJhbGciOiJIU...' \
  -d '{
        "locale": "en-US",
        "amount": 11836,
        "currency": "USD",
        "intents": ["PAY"]
      }'

Response parameters

FieldTypeDescription

instruction

stringKlarna display instruction (e.g., SHOW_KLARNA, HIDE_KLARNA, etc.).

icon

objectKlarna badge/logo suitable for checkout forms.

header

objectThe main descriptor that introduces Klarna in the payment form. The value will be dynamically adjusted based on the locale provided.

subheader

objectThe descriptor subheader which must be loaded inline below the main descriptor header. Short and enriched descriptive texts. Provides transparency on available options like installments, pay later, etc.

message

objectEnriched tailored description with link

payment_button

objectContains the label to be used on the Klarna payment button.

Sample response

JSON
{
  "instruction": "SHOW_KLARNA",
  "payment_button": {
    "text": "Pay with Klarna"
  },
  "header": {
    "text": "Pay with Klarna"
  },
  "subheader": {
    "text": "Pay in 4."

The message.parts will be available in a future release.

Your API response (e.g., for Get Payment Methods) should include the Klarna assets returned in the response from the Payment Presentation API, so your Partner can render the payment method correctly.

You have two options:

  1. Map Individual Fields: Extract and structure the response from Klarna’s Payment Presentation API and map relevant keys (e.g., descriptor, payment_button) into your API response format.
  2. Serialize the Entire Response: Alternatively, you may populate a single field—klarna_payment_presentation_data—with a serialized version (e.g., JSON string) of the full response obtained from Klarna’s Payment Presentation API. This avoids the need to map each field individually.
JSON
{
  "payment_methods": [{
    "name": "VISA",
    "type": "scheme"
  }, {
    "name": "Pay with Klarna",
    "type": "klarna",
    "klarna_payment_presentation_data": "{\"instruction\":\"SHOW_KLARNA\",...}"
  }]
}

You may structure the response to fit your API format, but ensure that the Klarna presentation data is clearly identifiable. Use a field name like:

  • klarna_payment_presentation_data
  • or payment_presentation_data (when used specifically for Klarna)

This makes it easy for Partner integrations to parse and use Klarna presentation data dynamically.