Payment Presentation for Server-side integration

Integrate Klarna's Payment Presentation API for server-side flows. This guide shows how to retrieve dynamic Klarna assets and forward them to Partners for building their own payment selector.

Overview

This guide explains how to provide dynamic Klarna assets to Partners using Klarna's Presentation API, enabling them to create their own payment selector in line with Klarna's best practices.

Below is a step-by-step overview for supporting dynamic payment method listing:

1.
Accept klarna_network_session_token in requests.
2.
Call Klarna's getPresentationAPI endpoint to fetch the most up-to-date Klarna content.
3.
Include Klarna-specific display instructions and assets (labels, icons, etc.) in the API response sent to Partners. Example of the payment selector built by a Partner when the Acquiring Partner enables this support:


Initial presentation	When Klarna is selected

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

Integration flow

The following diagram illustrates the server-side Payment Presentation flow:

sequenceDiagram participant Partner as Partner participant AP as Acquiring Partner participant Klarna as Klarna Presentation API Note over Partner,Klarna: Retrieve available payment methods Partner->>AP: Request payment methods Note over Partner,AP: Accept session token AP->>Klarna: Call the Payment Presentation API Note over AP,Klarna: locale, amount, currency, intent Klarna-->>AP: Payment Presentation data Note over Klarna,AP: instruction, payment_option AP->>AP: Include Klarna Payment Presentation data AP-->>Partner: Return Payment Presentation data Note over AP,Partner: Payment methods response with Klarna assets Note over Partner: Partner renders payment selector

Integration details

Accept Klarna Network data points

klarna_network_session_token
- Encodes Klarna session context, such as payment option preselection, prequalification results, or payment approval
- May be present on the initial authorization request
- Required when finalizing authorization after a step-up flow

Below is an example of how Acquiring Partners can accept the Klarna Network parameters in their Partner-facing APIs.

JSON

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "klarna_network_session_token": "krn:network:us1:test:session-token:eyJhbGciOiJIU[...]"
    }
  }
}

Requirements

Accept the Klarna Network parameters in the Partner-facing APIs.
Use the field name klarna_network_session_token, ensuring that it's easy for any Partner to identify and use.
Validation should be implemented, but it must not be more restrictive than what is specified in Klarna's authorizePayment endpoint.
All printable UTF-8 characters must be supported
Forward the Klarna Network parameters unmodified to Klarna.

Call the Payment Presentation API

Acquiring configuration for multi-payment-account Partners

If you are an Acquiring Partner with multiple Payment Accounts, include the acquiring_config query parameter to specify which Payment Account to use. For Partners with a single Payment Account, omitting acquiring_config is allowed — Klarna automatically uses the only available Payment Account.

Provide one of the following combinations — not both:

Payment Account Reference: acquiring_config[payment_acquiring_account_id] + acquiring_config[payment_account_reference]
Payment Account ID: acquiring_config[payment_account_id]

Example

SHELL

curl -G 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-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'amount=15000' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'intent=PAY'

Example - Tokenized payments

When calling the getPresentationAPI API endpoint with a Customer Token, the response will have an additional saved_payment_option object.

SHELL

curl -G 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-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]' \
  -H 'Klarna-Customer-Token: krn:partner:us1:test:identity:customer-token:ACZawkw7-2[...]' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'amount=15000' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'intent=PAY'

Return Klarna Payment Presentation data to the Partner

If your API supports preselecting payment methods, account for the instruction property returned by the getPresentationAPI API . Preselect Klarna when instruction is set to PRESELECT_KLARNA.

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

Map individual fields

Extract and structure the response from Klarna's Payment Presentation API and map relevant keys into your API response format.

The getPresentationAPI API returns multiple properties within the payment_option and saved_payment_option objects. Map these properties to fields in your API response format based on what your Partner-facing API supports:

Property Path	Description
`{...}.header.text`	The primary label that identifies Klarna as a payment option (e.g., "Pay with Klarna"). Map to whatever field your API uses for the payment method's display name or title.
`{...}.subheader.text`	A secondary descriptive line that provides additional context about the Klarna offering (e.g., "Plans from 0% interest"). Map to a field like subtitle, description, or tagline in your payment method object.
`{...}.icon.badge_image_url`	URL to a curved-edged badge-style Klarna logo. Map to the icon or logo URL field for displaying the Klarna brand mark next to the payment method name.
`{...}.icon.square_image_url`	URL to a square-shaped Klarna logo. Use this if your UI requires square icons instead of badge-shaped icons.
`{...}.icon.rectangle_image_url`	URL to a rectangular Klarna logo containing just the 'K' symbol. Use this for compact layouts where space is limited.
`{...}.icon.alt`	Alternative text for the icon (typically "Klarna"). Map to the alt text or accessibility label for the icon image.
`{...}.payment_option_id`	An opaque identifier for the specific Klarna payment offer. Include this if your API tracks which payment option variant was presented, but treat it as a black box (do not parse or interpret it).
`{...}.badge.text`	A small label (e.g., "Saved") that appears on the payment option in certain contexts. Map to a badge or tag field if your API supports visual indicators on payment methods.
`{...}.terms.parts`	An array of text and link segments containing legal terms or disclosures. Map to a terms or legal text field if your API requires displaying regulatory information alongside payment methods.

Example: Minimal mapping

If your API has a simple structure, map these essential fields:

JSON

{
  "payment_methods": [{
    "type": "klarna",
    "name": "<payment_option.header.text>",
    "subtitle": "<payment_option.subheader.text>",
    "icon_url": "<payment_option.icon.badge_image_url>",
    "display_instruction": "<instruction>"
  }]
}

Example: Detailed mapping

If your API supports rich payment method presentation, map additional fields:

JSON

{
  "payment_methods": [
    {
      "type": "klarna",
      "header": "<payment_option.header.text>",
      "subheader": "<payment_option.subheader.text>",
      "icons": {
        "badge": "<payment_option.icon.badge_image_url>",
        "square": "<payment_option.icon.square_image_url>",
        "rectangle": "<payment_option.icon.rectangle_image_url>",
        "alt_text": "<payment_option.icon.alt>"
      },

API & SDK references

Klarna payment presentation API