Klarna Partner Product API - Messaging (v2/r6)

Download OpenAPI specification:Download

Credit Promotion

Get credit promotion messaging for auto-size placement

Securityklarna_api_key or klarna_partner_account

Request

path Parameters

partner_account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

Example: krn:partner:global:account:live:LWT2XJSE

validation-info: Validation that is a valid krn

query Parameters

locale required	string (Locale) Preferred locale, in IETF BCP 47 format. Supported locales `en-AU` `de-AT` `en-AT` `nl-BE` `fr-BE` `en-BE` `en-CA` `fr-CA` `cs-CZ` `en-CZ` `da-DK` `en-DK` `fi-FI` `sv-FI` `en-FI` `fr-FR` `en-FR` `de-DE` `en-DE` `el-GR` `en-GR` `hu-HU` `en-HU` `en-IE` `it-IT` `en-IT` `en-MX` `es-MX` `nl-NL` `en-NL` `en-NZ` `nb-NO` `en-NO` `pl-PL` `en-PL` `pt-PT` `en-PT` `ro-RO` `en-RO` `es-ES` `en-ES` `sv-SE` `en-SE` `de-CH` `fr-CH` `it-CH` `en-CH` `en-GB` `en-US` `es-US` Example: locale=en-US validation-info: Validation that locale contain {language}-{region} syntax.
amount required	integer <int64> (PaymentAmount) [ 1 .. 2147483647 ] Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions. Invariant: `amount = sum(line_items[].total_line_amount)` Example: amount=2000 validation-info: Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.
custom_payment_method_ids	string You can dynamically trigger promotional credit offers. First, work with Klarna’s responsible account manager to determine the criteria for custom offers and a standard naming convention that will be referred to when requesting such offers via Klarna payments API. To be able to advertise these payment methods, pass the names as an array of strings to the On-site messaging placement. The array can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, and so on) should be included in the content selection. Example: custom_payment_method_ids=FINANCING0
message_preference	string Default: "klarna" Allows the partner to indicate preference for the message type. If no value is passed or an unrecognized value is provided, the default "klarna" message will be used. Passing "in-store" adjusts the content to display "in-store" related message, while passing "prequalification" adjusts the message to display the prequalification related content. Enum: "klarna" "in-store" "prequalification" Example: message_preference=in-store validation-info: Validation that the value should be one of the allowed values(klarna, in-store, prequalification) or the default value(klarna) will be used.
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or validation-info: Validates that the value is either "Or" or "or"

header Parameters

required

object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

get/v2/accounts/{partner_account_id}/payment/messaging/credit-promotion-auto-size

Request samples

curl
JavaScript
Node.js

Response samples

application/json

{"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Pay as low as $177/mo."
},
{"name": "ACTION_LEARN_MORE",
"url": "url_t",
"type": "ACTION",
"label": "Learn more"
},
{"name": "KLARNA_LOGO",
"alt": "Klarna",
"url": "https://osm.klarnaservices.com/images/logo_black_v2.svg",
"type": "IMAGE"
}
]
}
}

Get credit promotion messaging for badge placement

Securityklarna_api_key or klarna_partner_account

Request

path Parameters

partner_account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

Example: krn:partner:global:account:live:LWT2XJSE

validation-info: Validation that is a valid krn

query Parameters

locale required	string (Locale) Preferred locale, in IETF BCP 47 format. Supported locales `en-AU` `de-AT` `en-AT` `nl-BE` `fr-BE` `en-BE` `en-CA` `fr-CA` `cs-CZ` `en-CZ` `da-DK` `en-DK` `fi-FI` `sv-FI` `en-FI` `fr-FR` `en-FR` `de-DE` `en-DE` `el-GR` `en-GR` `hu-HU` `en-HU` `en-IE` `it-IT` `en-IT` `en-MX` `es-MX` `nl-NL` `en-NL` `en-NZ` `nb-NO` `en-NO` `pl-PL` `en-PL` `pt-PT` `en-PT` `ro-RO` `en-RO` `es-ES` `en-ES` `sv-SE` `en-SE` `de-CH` `fr-CH` `it-CH` `en-CH` `en-GB` `en-US` `es-US` Example: locale=en-US validation-info: Validation that locale contain {language}-{region} syntax.
amount required	integer <int64> (PaymentAmount) [ 1 .. 2147483647 ] Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions. Invariant: `amount = sum(line_items[].total_line_amount)` Example: amount=2000 validation-info: Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.
custom_payment_method_ids	string You can dynamically trigger promotional credit offers. First, work with Klarna’s responsible account manager to determine the criteria for custom offers and a standard naming convention that will be referred to when requesting such offers via Klarna payments API. To be able to advertise these payment methods, pass the names as an array of strings to the On-site messaging placement. The array can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, and so on) should be included in the content selection. Example: custom_payment_method_ids=FINANCING0
message_preference	string Default: "klarna" Allows the partner to indicate preference for the message type. If no value is passed or an unrecognized value is provided, the default "klarna" message will be used. Passing "in-store" adjusts the content to display "in-store" related message, while passing "prequalification" adjusts the message to display the prequalification related content. Enum: "klarna" "in-store" "prequalification" Example: message_preference=in-store validation-info: Validation that the value should be one of the allowed values(klarna, in-store, prequalification) or the default value(klarna) will be used.
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or validation-info: Validates that the value is either "Or" or "or"

header Parameters

required

object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

get/v2/accounts/{partner_account_id}/payment/messaging/credit-promotion-badge

Request samples

curl
JavaScript
Node.js

Response samples

application/json

{"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Pay as low as $177/mo."
},
{"name": "ACTION_LEARN_MORE",
"url": "url_t",
"type": "ACTION",
"label": "Learn more"
},
{"name": "KLARNA_BADGE",
"alt": "Klarna",
"url": "https://osm.klarnaservices.com/images/logo_black_v2.svg",
"type": "IMAGE"
}
]
}
}

Top Strip

Get top strip promotion messaging for auto-size placement

Securityklarna_api_key or klarna_partner_account

Request

path Parameters

partner_account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

Example: krn:partner:global:account:live:LWT2XJSE

validation-info: Validation that is a valid krn

query Parameters

locale required	string (Locale) Preferred locale, in IETF BCP 47 format. Supported locales `en-AU` `de-AT` `en-AT` `nl-BE` `fr-BE` `en-BE` `en-CA` `fr-CA` `cs-CZ` `en-CZ` `da-DK` `en-DK` `fi-FI` `sv-FI` `en-FI` `fr-FR` `en-FR` `de-DE` `en-DE` `el-GR` `en-GR` `hu-HU` `en-HU` `en-IE` `it-IT` `en-IT` `en-MX` `es-MX` `nl-NL` `en-NL` `en-NZ` `nb-NO` `en-NO` `pl-PL` `en-PL` `pt-PT` `en-PT` `ro-RO` `en-RO` `es-ES` `en-ES` `sv-SE` `en-SE` `de-CH` `fr-CH` `it-CH` `en-CH` `en-GB` `en-US` `es-US` Example: locale=en-US validation-info: Validation that locale contain {language}-{region} syntax.
message_preference	string Default: "klarna" Allows the partner to indicate preference for the message type. If no value is passed or an unrecognized value is provided, the default "klarna" message will be used. Passing "in-store" adjusts the content to display "in-store" related message, while passing "prequalification" adjusts the message to display the prequalification related content. Enum: "klarna" "in-store" "prequalification" Example: message_preference=in-store validation-info: Validation that the value should be one of the allowed values(klarna, in-store, prequalification) or the default value(klarna) will be used.
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or validation-info: Validates that the value is either "Or" or "or"

header Parameters

required

object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

get/v2/accounts/{partner_account_id}/payment/messaging/top-strip-promotion-auto-size

Request samples

curl
JavaScript
Node.js

Response samples

application/json

{"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Shop now. Pay with"
},
{"name": "ACTION_LEARN_MORE",
"url": "url_t",
"type": "ACTION",
"label": "Learn more"
},
{"name": "KLARNA_LOGO",
"alt": "Klarna",
"url": "https://osm.klarnaservices.com/images/logo_black_v2.svg",
"type": "IMAGE"
}
]
}
}

Get top strip promotion messaging for badge placement

Securityklarna_api_key or klarna_partner_account

Request

path Parameters

partner_account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

Example: krn:partner:global:account:live:LWT2XJSE

validation-info: Validation that is a valid krn

query Parameters

locale required	string (Locale) Preferred locale, in IETF BCP 47 format. Supported locales `en-AU` `de-AT` `en-AT` `nl-BE` `fr-BE` `en-BE` `en-CA` `fr-CA` `cs-CZ` `en-CZ` `da-DK` `en-DK` `fi-FI` `sv-FI` `en-FI` `fr-FR` `en-FR` `de-DE` `en-DE` `el-GR` `en-GR` `hu-HU` `en-HU` `en-IE` `it-IT` `en-IT` `en-MX` `es-MX` `nl-NL` `en-NL` `en-NZ` `nb-NO` `en-NO` `pl-PL` `en-PL` `pt-PT` `en-PT` `ro-RO` `en-RO` `es-ES` `en-ES` `sv-SE` `en-SE` `de-CH` `fr-CH` `it-CH` `en-CH` `en-GB` `en-US` `es-US` Example: locale=en-US validation-info: Validation that locale contain {language}-{region} syntax.
message_preference	string Default: "klarna" Allows the partner to indicate preference for the message type. If no value is passed or an unrecognized value is provided, the default "klarna" message will be used. Passing "in-store" adjusts the content to display "in-store" related message, while passing "prequalification" adjusts the message to display the prequalification related content. Enum: "klarna" "in-store" "prequalification" Example: message_preference=in-store validation-info: Validation that the value should be one of the allowed values(klarna, in-store, prequalification) or the default value(klarna) will be used.
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or validation-info: Validates that the value is either "Or" or "or"

header Parameters

required

object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

get/v2/accounts/{partner_account_id}/payment/messaging/top-strip-promotion-badge

Request samples

curl
JavaScript
Node.js

Response samples

application/json

{"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Shop now. Pay with"
},
{"name": "ACTION_LEARN_MORE",
"url": "url_t",
"type": "ACTION",
"label": "Learn more"
},
{"name": "KLARNA_BADGE",
"alt": "Klarna",
"url": "https://osm.klarnaservices.com/images/logo_black_v2.svg",
"type": "IMAGE"
}
]
}
}

Checkout

Get messaging for checkout placement

Securityklarna_api_key or klarna_partner_account

Request

path Parameters

partner_account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

Example: krn:partner:global:account:live:LWT2XJSE

validation-info: Validation that is a valid krn

query Parameters

locale required	string (Locale) Preferred locale, in IETF BCP 47 format. Supported locales `en-AU` `de-AT` `en-AT` `nl-BE` `fr-BE` `en-BE` `en-CA` `fr-CA` `cs-CZ` `en-CZ` `da-DK` `en-DK` `fi-FI` `sv-FI` `en-FI` `fr-FR` `en-FR` `de-DE` `en-DE` `el-GR` `en-GR` `hu-HU` `en-HU` `en-IE` `it-IT` `en-IT` `en-MX` `es-MX` `nl-NL` `en-NL` `en-NZ` `nb-NO` `en-NO` `pl-PL` `en-PL` `pt-PT` `en-PT` `ro-RO` `en-RO` `es-ES` `en-ES` `sv-SE` `en-SE` `de-CH` `fr-CH` `it-CH` `en-CH` `en-GB` `en-US` `es-US` Example: locale=en-US validation-info: Validation that locale contain {language}-{region} syntax.
custom_payment_method_ids	string You can dynamically trigger promotional credit offers. First, work with Klarna’s responsible account manager to determine the criteria for custom offers and a standard naming convention that will be referred to when requesting such offers via Klarna payments API. To be able to advertise these payment methods, pass the names as an array of strings to the On-site messaging placement. The array can be used to define which of the configured payment options within a payment category (pay_later, pay_over_time, and so on) should be included in the content selection. Example: custom_payment_method_ids=FINANCING0
amount required	integer <int64> (PaymentAmount) [ 1 .. 2147483647 ] Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions. Invariant: `amount = sum(line_items[].total_line_amount)` Example: amount=2000 validation-info: Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.

header Parameters

required

object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

get/v2/accounts/{partner_account_id}/payment/messaging/checkout

Request samples

curl
JavaScript
Node.js

Response samples

application/json

{"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Enjoy Buyer Protection with Klarna"
},
{"name": "ACTION_LEARN_MORE",
"url": "url_t",
"type": "ACTION",
"label": "Learn more"
},
{"name": "KLARNA_BADGE",
"alt": "Klarna",
"url": "https://osm.klarnaservices.com/images/logo_black_v2.svg",
"type": "IMAGE"
},
{"name": "ACTION_OPEN_BUYERS_PROTECTION_LINK",
"label": "Buyer Protection",
"url": "https://www.klarna.com/de/kauferschutzrichtlinie/",
"type": "ACTION"
},
{"name": "ZERO_INTEREST_BADGE_TEXT",
"label": "0% Financing",
"type": "TEXT"
}
]
}
}

Payment Descriptors

Provides payment descriptors for rendering the checkout experience, based on the specified category preference. The no. of checkout items are defined based on the category_preference value and amount.

If category_preference is set to KLARNA, all payment categories are combined into a single descriptor node in the response.
If a valid category_preference (PAY_NOW, PAY_LATER, PAY_OVER_TIME) is provided, the response includes descriptors for the specified category as the first item, and a grouped descriptor for all other categories as the second item.
If an invalid category_preference is provided, the response returns an error.
If no category_preference is specified, the response includes individual descriptors for all available categories.
Note: Use PAYMENT_DESCRIPTOR as the main header/title and PAYMENT_DESCRIPTOR_SUBHEADER as the subheader for each item. When multiple descriptor nodes are returned from the API, the merchant must generate multiple checkout listings consistently.

SLO Category: The SLO Service Category. Operations that support personalized payment messaging, including customized options and descriptors.Personalized Message Placements

SLA Service Class: The SLA Service Class this operation is classified at when evaluating SLA compliance. Operations, webhooks and other services that does not directly impact the core purchasing process in real-time and enables supplemental or secondary featuresTransactions Non-critical Services

Lifecycle Stage: The Lifecycle Stage tag in operations and attributes defines completeness of the feature for usage Feature under development, may not be fully available and is subject to change as we continue building the service in partnership with early usersEarly Release

Availability in Test environment: Indicates if the feature is available in the Klarna Test environment Feature is available in the Klarna Test environmentAvailable

Availability in Production environment: Indicates if the feature is available in the Klarna Production environment Feature is available in the Klarna Production environmentAvailable

internal: true

Securityklarna_api_key or klarna_partner_account

Request

path Parameters

partner_account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

Example: krn:partner:global:account:live:LWT2XJSE

validation-info: Validation that is a valid krn

header Parameters

required

object

Metadata about the integrator and originators of the request in n object, serialized as a valid JSON

Example: object=[object Object]

Request Body schema: application/json

amount required	integer <int64> (PaymentAmount) [ 1 .. 2147483647 ] Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. Should not include any amounts for subscriptions. Invariant: `amount = sum(line_items[].total_line_amount)` validation-info: Validation that it is 10 digits max, up to 2^31-1. That is >= 0. Validation that is equal to line_items.total_amount.
locale required	string (Locale) Preferred locale, in IETF BCP 47 format. Supported locales `en-AU` `de-AT` `en-AT` `nl-BE` `fr-BE` `en-BE` `en-CA` `fr-CA` `cs-CZ` `en-CZ` `da-DK` `en-DK` `fi-FI` `sv-FI` `en-FI` `fr-FR` `en-FR` `de-DE` `en-DE` `el-GR` `en-GR` `hu-HU` `en-HU` `en-IE` `it-IT` `en-IT` `en-MX` `es-MX` `nl-NL` `en-NL` `en-NZ` `nb-NO` `en-NO` `pl-PL` `en-PL` `pt-PT` `en-PT` `ro-RO` `en-RO` `es-ES` `en-ES` `sv-SE` `en-SE` `de-CH` `fr-CH` `it-CH` `en-CH` `en-GB` `en-US` `es-US` validation-info: Validation that locale contain {language}-{region} syntax.
category_preference	string (CategoryPreference) The payment category that the merchant want to display as first option. "KLARNA" will club all categories into one text. Not passing this key will return all categories individually without grouping. if a category_preference is passed, the first option will be the preferred category, the next one will be the remaining categories grouped under one text. Enum: "KLARNA" "PAY_NOW" "PAY_LATER" "PAY_OVER_TIME" validation-info: Validation that the passed value should be one of the allowed values(KLARNA, PAY_NOW, PAY_LATER, PAY_OVER_TIME).

Responses

200

Successful response

400

Bad Request, there was an error in the input of the request. The request can not be retried without modifications.

401

Unauthorized, the request was not authorized.

404

Not Found, the requested resource was not found.

429

Too Many Requests, the request was rate limited.

500

Internal Server Error, there was an unexpected error in the API.

post/v2/accounts/{partner_account_id}/payment/messaging/payment-descriptors

Request samples

Payload
curl
JavaScript
Node.js

application/json

When category_preference is set to KLARNA, the payment_descriptor should return only one descriptor which has grouped text of all categories and with no payment_option_id.

{"locale": "en-US",
"amount": 1000,
"category_preference": "KLARNA"
}

Response samples

application/json

When category_preference is set to KLARNA, the payment_descriptor should return only one descriptor which has grouped text of all categories and with no payment_option_id.

{"payment_descriptors": [{"content": {"nodes": [{"name": "PAYMENT_DESCRIPTOR",
"type": "TEXT",
"value": "Pay with Klarna"
},
{"name": "PAYMENT_DESCRIPTOR_SUBHEADER",
"type": "TEXT",
"value": "Pay in 3 parts or in 30 or over 6-36 months or now"
},
{"alt": "Klarna",
"url": "/images/badges/klarna_v2_1.svg",
"name": "KLARNA_BADGE",
"type": "IMAGE"
}
]
}
}
],
"impression_url": "https://EVT-TEST.klarnaservices.com/v1/osm-client-script/1.0.0/b?ab=api&g=bab9850e-772c-5cac-aec5-e0542d7f84a5&pm=all&d=payment-descriptor&h=EN&i=DE&sid=eVSYgYD5wAiRrCfk5JjI7&timestamp=1724835865443&iv=osm-api"
}