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:
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:
interoperability_token
and interoperability_data
in your APIsklarna_payment_presentation_data
This step only applies to Acquiring Partners that have APIs that allow Partners to retrieve available payment methods. It is identical to the server-side only integration for one-time payments.
If an Acquiring Partner provides an API for retrieving payment methods, it must:
interoperability_token
and interoperability_data
in requests.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
{
"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
, orinteroperability_token
/ interoperability_data
(in Klarna-specific context).This ensures easy identification for any Partner.
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:
Parameter | Type | Max length | Validation |
---|---|---|---|
| string | 8192 chars | Optional: verify length only |
| string (stringified JSON object) | 10240 chars | Optional: 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 APIAPI 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.
/v2/accounts/{partner_account_id}/payment/presentation
Parameter | Required | Description |
---|
Sample request
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"]
}'
Field | Type | Description |
string | Klarna display instruction (e.g., SHOW_KLARNA , HIDE_KLARNA , etc.). | |
object | Klarna badge/logo suitable for checkout forms. | |
object | The main descriptor that introduces Klarna in the payment form. The value will be dynamically adjusted based on the locale provided. | |
object | The 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. | |
object | Enriched tailored description with link | |
object | Contains the label to be used on the Klarna payment button. |
Sample response
{
"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:
descriptor
, payment_button
) into your API response format.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.{
"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
payment_presentation_data
(when used specifically for Klarna)This makes it easy for Partner integrations to parse and use Klarna presentation data dynamically.