Klarna Partner Product API - Messaging (release/4)

Download OpenAPI specification:Download

Authentication

klarna_api_key

Use the Klarna API key as HTTP Basic Authentication credentials

Security Scheme Type	API Key
Header parameter name:	Authorization

klarna_partner_account

Klarna Partner Account ID when acting on-behalf of another account

Security Scheme Type	API Key
Header parameter name:	Klarna-Partner-Account

Credit Promotion

Get credit promotion messaging for auto-size placement

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

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
payment_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: `payment_amount = sum(line_items[].total_line_amount)` Example: payment_amount=2000
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
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad request.

get/v1/accounts/{account_id}/payment/messaging/credit-promotion-auto-size

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/messaging/credit-promotion-auto-size?locale=en-US&payment_amount=2000&custom_payment_method_ids=string&message_preference=klarna&message_prefix=Or' \
  -H 'Authorization: YOUR_API_KEY_HERE'

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

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

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
payment_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: `payment_amount = sum(line_items[].total_line_amount)` Example: payment_amount=2000
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
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad request.

get/v1/accounts/{account_id}/payment/messaging/credit-promotion-badge

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/messaging/credit-promotion-badge?locale=en-US&payment_amount=2000&custom_payment_method_ids=string&message_preference=klarna&message_prefix=Or' \
  -H 'Authorization: YOUR_API_KEY_HERE'

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

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

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
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
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad request.

get/v1/accounts/{account_id}/payment/messaging/top-strip-promotion-auto-size

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/messaging/top-strip-promotion-auto-size?locale=en-US&message_preference=klarna&message_prefix=Or' \
  -H 'Authorization: YOUR_API_KEY_HERE'

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

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

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
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
message_prefix	string Prefixes the content of the message. Allowed values: Or, or Enum: "Or" "or" Example: message_prefix=Or

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad request.

get/v1/accounts/{account_id}/payment/messaging/top-strip-promotion-badge

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/messaging/top-strip-promotion-badge?locale=en-US&message_preference=klarna&message_prefix=Or' \
  -H 'Authorization: YOUR_API_KEY_HERE'

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

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

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
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
payment_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: `payment_amount = sum(line_items[].total_line_amount)` Example: payment_amount=2000

Responses

200

Successful response

204

No messaging available for the given parameters.

400

Bad request.

get/v1/accounts/{account_id}/payment/messaging/checkout

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/messaging/checkout?locale=en-US&custom_payment_method_ids=string&payment_amount=2000' \
  -H 'Authorization: YOUR_API_KEY_HERE'

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

Capabilities

Get merchant placements, clientId in OSM by MID or clientId(UUID).

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

query Parameters

mid	string MID of the merchant. Example: mid=K12345
client_id	string Client ID(UUID) of the merchant. Example: client_id=5fb4f264-dd9b-5df9-82d4-e7d88fcfaa89

Responses

200

Successful response

400

Bad request.

404

Bad request.

get/v1/accounts/{account_id}/payment/messaging/capabilities

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api-global.klarna.com/v1/accounts/{account_id}/payment/messaging/capabilities?mid=string&client_id=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

application/json

{"client_id": "5fb4f264-dd9b-5df9-82d4-e7d88fcfaa89",
"countries": [{"locales": ["en-IE"
],
"country": "IE"
},
{"locales": ["da-DK",
"en-DK"
],
"country": "DK"
},
{"locales": ["de-AT",
"en-AT"
],
"country": "AT"
},
{"locales": ["en-SE",
"sv-SE"
],
"country": "SE"
},
{"locales": ["en-NO",
"no-NO"
],
"country": "NO"
},
{"locales": ["en-FI",
"fi-FI",
"sv-FI"
],
"country": "FI"
},
{"locales": ["en-NL",
"nl-NL"
],
"country": "NL"
},
{"locales": ["de-DE",
"en-DE"
],
"country": "DE"
},
{"locales": ["de-CH",
"en-CH",
"fr-CH",
"it-CH"
],
"country": "CH"
},
{"locales": ["en-GB"
],
"country": "GB"
},
{"locales": ["en-FR",
"fr-FR"
],
"country": "FR"
},
{"locales": ["en-IT",
"it-IT"
],
"country": "IT"
},
{"locales": ["en-PL",
"pl-PL"
],
"country": "PL"
},
{"locales": ["en-BE",
"fr-BE",
"nl-BE"
],
"country": "BE"
}
],
"placements": [{"key": "footer-promotion-auto-size",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Footer"
}
},
{"key": "credit-promotion-auto-size",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Price Detail"
}
},
{"key": "sidebar-promotion-auto-size",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Sidebar"
}
},
{"key": "top-strip-promotion-auto-size",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Top strip"
}
},
{"key": "credit-promotion-badge",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Price Detail Badge"
}
},
{"key": "info-page",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Information Page"
}
},
{"key": "top-strip-promotion-badge",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Top Strip Badge"
}
},
{"key": "homepage-promotion-tall",
"allow_custom_variant": false,
"size": {"label": "160 x 600",
"width": 160,
"height": 600,
"width_unit": "px",
"height_unit": "px"
},
"type": {"name": "Body"
}
},
{"key": "homepage-promotion-wide",
"allow_custom_variant": false,
"size": {"label": "728 x 90",
"width": 728,
"height": 90,
"width_unit": "px",
"height_unit": "px"
},
"type": {"name": "Body"
}
},
{"key": "homepage-promotion-box",
"allow_custom_variant": false,
"size": {"label": "300 x 300",
"width": 300,
"height": 300,
"width_unit": "px",
"height_unit": "px"
},
"type": {"name": "Body"
}
},
{"key": "payment-options",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Custom Payment Selector"
}
},
{"key": "checkout",
"allow_custom_variant": true,
"size": {"label": "(auto) x (auto)",
"width": 100,
"height": 0,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Checkout"
}
},
{"key": "payment-options",
"allow_custom_variant": true,
"size": {"label": "(auto) x 40",
"width": 100,
"height": 40,
"width_unit": "%",
"height_unit": "px"
},
"type": {"name": "Custom Payment Selector"
}
}
]
}

Payment Options

Returns individual payment options, customers previous selected payment method and payment source if customer_token is passed in req body.

Returns all individual payment options (e.g. Financing 6 and Financing 12 are different items in the response, no grouping is applied). This endpoint is only available for selected merchants. Please advise with your point of contact before implemeting it.

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

Request Body schema: application/json

payment_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: `payment_amount = sum(line_items[].total_line_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`
currency required	string (Currency) ^[A-Za-z]{3}$ Currency in ISO 4217 format. Supported currencies: `AUD` `EUR` `CAD` `CZK` `DKK` `HUF` `MXN` `NZD` `NOK` `PLN` `RON` `SEK` `CHF` `GBP` `USD`
customer_token	string (CustomerToken) <= 1024 characters Returned if Account Linking or payment tokenization was requested. The `customer_token` represents the tokenized customer and allows you to act on behalf of the customer. You must persist this token in your system associated with the customer account. To de-duplicate customers, you should use the `customer_id` as the unique identifier.

Responses

200

Successful response

400

Bad request.

post/v1/accounts/{account_id}/payment/messaging/payment-options

Request samples

Payload
curl
JavaScript
Node.js

application/json

{"payment_amount": 2000,
"locale": "en-US",
"currency": "USD",
"customer_token": "krn:partner:us1:live:identity:customer-token:v1:vVQGmYzlfsQ16dko3jcwY5lV8hBgKs9a.96e12495afdc88be3c407087076deabcf50f626242f97c0169779fac4a9acc8f"
}

Response samples

application/json

{"payment_options": [{"payment_method": "PAY_NOW",
"payment_method_label": "Pay Now",
"payment_option_id": "edwqqr32dsad2dsefrassa",
"total_amount": 111101,
"preselected": false,
"currency": "USD",
"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Pay in full with card."
},
{"name": "ACTION_LEARN_MORE",
"type": "ACTION",
"label": "Learn more",
"url": "https://osm.klarnaservices.com/learn-more/index.html?showButtons=false&showBackground=true#eyJ..."
},
{"name": "TEXT_TERMS",
"type": "TEXT",
"value": "Terms and conditions",
"hyperlinks": [{"text": "Terms and conditions",
"url": "https://www.klarna.com/us/legal/"
}
]
},
{"name": "KLARNA_LOGO",
"type": "IMAGE",
"url": "https://osm.klarnaservices.com/images/logo_black_v2_1.svg",
"alt": "Klarna"
}
]
}
},
{"payment_method": "FINANCING",
"payment_method_label": "Financing",
"number_of_installments": 12,
"interest_rate": 1999,
"installment_amount": 9258,
"total_amount": 111101,
"payment_option_id": "czxsa4324132dsaddsxcxzzxs",
"preselected": true,
"currency": "USD",
"content": {"nodes": [{"name": "TEXT_MAIN",
"type": "TEXT",
"value": "Pay in 12 installments."
},
{"name": "TEXT_TERMS",
"type": "TEXT",
"value": "Pay monthly financing available through Klarna, Inc. is issued by WebBank, member FDIC. It’s available to eligible US residents in most states. Rates (0-29.99% APR) are based on your credit. Missed payments are subject to late fees. Review Klarna's terms.",
"hyperlinks": [{"text": "FDIC",
"url": "https://osm.klarnaservices.com/learn-more/index.html?showButtons=false&showBackground=true#eyJ..."
},
{"text": "Klarna's terms.",
"url": "https://cdn.klarna.com/1.0/shared/content/legal/terms/de-de/fixed_sum_credit"
}
]
},
{"name": "ACTION_LEARN_MORE",
"type": "ACTION",
"label": "Learn more",
"url": "https://osm.klarnaservices.com/learn-more/index.html?showButtons=false&showBackground=true#eyJ..."
},
{"name": "KLARNA_LOGO",
"type": "IMAGE",
"url": "https://osm.klarnaservices.com/images/logo_black_v2_1.svg",
"alt": "Klarna"
}
]
}
}
],
"funding_source": {"funding_source_type": "CARD",
"brand": "VISA",
"expires_at": "05/2025",
"masked_card_number": "**** 4555"
},
"impression_url": "https://evt-eu.klarnaservices.com/<params>"
}

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.

Request

Security:

klarna_api_key or klarna_partner_account

path Parameters

account_id

required

string (AccountIdentifier)

Unique account identifier assigned by Klarna to the onboarded merchant

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

Request Body schema: application/json

payment_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: `payment_amount = sum(line_items[].total_line_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`
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"

Responses

200

Successful response

400

Bad request.

post/v1/accounts/{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",
"payment_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"
}