Help Center

Checkout

Coverage

Capabilities

Principle of operation

1. Selection at checkout
   Customer selects Klarna as the payment method at checkout.
2. Payment initiation
   Merchant sends a payment request to Solidgate. Solidgate returns a redirect URL in pay_form.return_url . Use this parameter to inject it into the Klarna Web SDK, which initiates a Klarna Customer Journey.
3. Redirect to Klarna
   Customer is redirected to Klarna's hosted payment page and selects a preferred payment option based on eligibility. Options may include Pay in Full, Pay in 30 Days, Pay in N (3 or 4), or Financing.
4. Authentication and authorization
   Customer authenticates with Klarna. Klarna evaluates eligibility for the selected payment option and authorizes the payment.
5. Capture
   Solidgate auto-captures the payment upon Klarna authorization. No separate capture request is required.
6. Merchant notification
   Merchant receives a notification Webhook confirming the order status.

1. Selection at checkout
   Customer selects Klarna as the payment method and initiates mandate authorization.
2. Payment initiation
   Merchant sends a payment request to Solidgate with future_usage.payment_type recurring , along with the applicable recurring parameters. Solidgate returns a redirect URL in pay_form.return_url . Use this parameter to inject it into the Klarna Web SDK, which initiates a Klarna Customer Journey.
3. Redirect to Klarna
   Customer is redirected to Klarna's hosted payment page, where they authorize the initial payment and the recurring mandate terms.
4. Mandate authorization
   Klarna evaluates the customer's eligibility and authorizes the mandate. A mandate token is issued for subsequent charges.
5. Capture
   Solidgate auto-captures the initial payment upon authorization.
6. Merchant notification
   Merchant receives a notification Webhook with the mandate token for subsequent recurring payments.

Transaction lifecycle

Klarna is an asynchronous payment method. Webhook notifications are sent on each status transition. Use the order.status field in the webhook payload to track the current payment state. Use the webhook as the source of truth.

Integration

Klarna can be integrated via the following approaches. Choose based on how much control you need over the checkout UI.

H2H integration

In the H2H flow, your backend sends the init payment API v1 request to Solidgate and receives a Klarna redirect URL. All backend operations are performed by Solidgate. Your frontend is responsible for displaying Klarna as a payment option and initiating the redirect after receiving the response from Solidgate. Final payment status is delivered via webhooks.

1. Display Klarna in your checkout using the Klarna Web SDK Reference or Payment Presentation API Reference .
2. When the customer selects Klarna and proceeds, send the init payment request to Solidgate.
3. Include payment_type_data.klarna_network_session_token in the request, obtained from Klarna Web SDK. Optionally, pass payment_type_data.klarna_network_data to provide supplementary Klarna SDK session state when extended session continuity is required.
4. Solidgate returns pay_form.return_url (the Klarna redirect URL).
5. Inject pay_form.return_url into the Klarna Web SDK to initiate the Klarna authorisation flow. When using the Payment Presentation API, redirect the customer to pay_form.return_url instead.
6. Klarna handles the payment UI on its hosted page and redirects the customer back to your return_url on completion.

Payment Form

Payment Form embeds Solidgate's checkout widget directly into your existing checkout page. Your page structure, branding, and surrounding UI remain fully under your control. The form occupies a defined area within your flow.

Klarna's redirect and UI are handled internally by Solidgate. No separate redirect logic is required on your side.

You own your page layout, the surrounding checkout experience, and when or how the form is initialised. Solidgate owns Klarna display, redirect to Klarna's hosted page, and payment state handling.

This path requires frontend integration work. You embed the widget, initialise it with a session token, and handle payment completion callbacks. It is suitable for merchants who want to keep customers within their own checkout environment without building a full H2H integration.

Optionally, if you use Klarna boost features (Express Checkout, Sign in with Klarna, On-Site Messaging), pass payment_type_data.klarna_network_data to provide supplementary Klarna SDK session state for extended session continuity.

Configure the Klarna button on Payment Form.

Payment Page / Payment Link

Payment Page and Payment Link are fully hosted by Solidgate. Your customer leaves your site and completes the payment on a Solidgate-hosted page. You have no control over the checkout UI.

Integrated via a redirect from your backend. Generate the payment session, receive a hosted page URL, and redirect the customer to it. Use Payment Page for hosted checkout configuration.

Requires no code integration. Generate a shareable URL via Hub or API and send it to the customer directly by email, messenger, or any other channel. No checkout page is needed on your side. Use Payment Link for shareable URL setup.

Both options require minimal development effort. They are best suited for merchants who prioritise speed of launch, operate without a dedicated checkout page, or need a no-code payment collection option.

Optionally, if you use Klarna boost features (Express Checkout, Sign in with Klarna, On-Site Messaging), pass payment_type_data.klarna_network_data to provide supplementary Klarna SDK session state for extended session continuity.

Klarna Web SDK & Payment Presentation API

The Klarna Web SDK Reference is required for H2H integrations to render Klarna in the checkout. It is also recommended for Payment Form and Payment Page to enable session continuity and pre-filled customer details. It powers Klarna boost features such as Express Checkout, On-Site Messaging, and Sign in with Klarna.

For H2H integrations, you can also use the Payment Presentation API Reference instead of the Klarna Web SDK. It retrieves Klarna's dynamically generated checkout elements, including logo, header, messaging, and payment button. These adapt automatically to the customer's locale, transaction amount, and eligible payment options. This integration path requires Klarna API credentials that can be created and retrieved from Klarna Portal.

Klarna presentation

Branding

Klarna branding follows the Present Klarna in the checkout Reference guidelines, including brand assets and design rules.

Group Klarna under Wallet or Mobile payment. Do not place it under “Installment payments” or “Buy now, pay later.” Klarna offers a full suite of payment solutions including pay now, pay later, and financing.

Always retrieve the Klarna logo dynamically. Do not use static copies. Three variants are available. Badge is recommended and is ideal for displaying the full Klarna logo when space allows. Square fits constrained layouts with a 1:1 aspect ratio. Rectangle fits layouts with a 2:3 aspect ratio.

All headers, subheaders, and messages must be retrieved dynamically and adjust automatically to the customer's locale, transaction details, and available payment options. Messages surface pre-qualification status, deals, or 0% financing campaigns when applicable. Do not hardcode payment option names or promotional copy.

Once Klarna is selected, the payment button updates to display “Continue with Klarna” with the Klarna badge. Dark and light themes are available to match your checkout background. Rounded and square button styles are supported. Minimum button height is 40px (48px recommended). Minimum width is 160px. Match the width of other payment buttons in stacked layouts.

Checkout layout

Two layout variants are supported depending on your checkout flow.

The customer selects Klarna via radio button and confirms with a dedicated button. The subheader is shown before selection. The message is revealed after.

Checkout navigates directly after payment selection. A short description is shown before selection. A dynamically generated subheader appears after.

Pre-selection

Klarna's pre-selection behaviour depends on the customer's prior interaction.

With no prior interaction, Klarna appears as a standard payment option and respects your payment method ordering. When the customer is pre-qualified via On-Site Messaging or Express Checkout, they have already shown clear intent to pay with Klarna. Show only Klarna and collapse all other payment options. When the customer is authenticated via Sign in with Klarna, Klarna recognises them. Pre-select Klarna and list it first to maximise conversion.

Boost features

Klarna offers conversion-optimising features available through the Solidgate integration. Full documentation and implementation guides are in the Perfect Customer Journey Reference guide.

Pre-fills shipping and billing details for returning Klarna customers, reducing checkout steps and accelerating purchase completion. Requires the Klarna Web SDK and a valid klarna_network_session_token passed in the payment request.

Displays Klarna payment option messaging (for example, “Pay in 3 installments from €X/month”) on product and cart pages before the customer reaches checkout. Configured through the Klarna Web SDK independently of the payment request.

Allows returning Klarna customers to authenticate with their Klarna account at checkout, enabling personalized payment options and pre-filled details. Configured through the Klarna Web SDK.

Partner portal

You can also use Klarna Partner Portal for Klarna Disputes, including Klarna Disputes Handling. You can learn more about Klarna Dispute Management Reference .

Data specifications

Description

Payment method identifier.

Example

klarna-network

Description

Unique merchant order identifier.

Example

order_kln_001

Description

Order description displayed to the customer and used in Klarna's customer journey.

Example

Order #kln_001

Description

Currency in three-letter code per the ISO-4217 Wiki standard. For example, EUR , SEK , or GBP .

Example

EUR

Description

Order amount in the smallest currency unit Guide supported by the alternative payment method. For example, 9900 means €99.00.

Example

9900

Description

Customer email address.

Minimum length is 6 characters.

Example

buyer@example.com

Description

Customer first name.

Example

Emma

Description

Customer last name.

Example

Johansson

Description

Customer phone number.

Should be provided in international format E.164 Wiki , starting with the plus + sign.

Recommended format ^\+[1-9]\d{1,14}$

Example

+46701234567

Description

Public IP address of the customer. Both IPv4 and IPv6 are supported.

Example

82.115.34.21

Description

Customer billing address details.

Description

ISO-3166 Wiki country code of the billing address. For example, SWE or DEU .

Example

SWE

Description

Billing state or region.

Description

Billing city.

Example

Stockholm

Description

Billing postal code.

Example

111 57

Description

Customer platform at the moment of payment.

• WEB - desktop
• MOB - mobile version
• APP - application

Example

WEB

Description

Customer shipping address details.

Description

Shipping street address line 1.

Description

Shipping street address line 2.

Description

ISO-3166 Wiki country code of the shipping address.

Example

SWE

Description

Shipping state or region.

Description

Shipping city.

Description

Shipping postal code.

Description

Product category sent to Klarna for eligibility and address handling.

• digital_goods - digital products such as software, subscriptions, and downloads. No shipping address is sent to Klarna.
• physical_goods - physical products shipped to a delivery address. Include shipping_address in the request.

Example

digital_goods

Description

Payment usage configuration for one-time or recurring Klarna payments.

Description

Type of the payment usage scenario for Klarna.

• one-time - one-off payment, no recurring mandate
• recurring - mandate for fixed scheduled recurring charges

Example

one-time

Description

Amount in the smallest currency unit charged in each subsequent recurring payment.

Example

9900

Description

Billing interval for subsequent recurring charges.

Description

Billing interval unit.

• day
• week
• month
• year

Example

month

Description

Number of interval units between charges. For example, 1 with month means monthly billing.

Example

1

Description

Klarna-specific payment data, including session tokens, originators, and country identity fields.

Description

Klarna Web SDK session token.

Description

Klarna Network Data (KND). Structured JSON pass-through carrying Klarna payment context across the payment lifecycle.

Description

Array of third-party systems responsible for the request (for example, Shopify or WooCommerce). If the request is sent through multiple systems before reaching Solidgate, each system can be represented as an originator.

Description

Name of the originator in SCREAMING_SNAKE_CASE .

Pattern: ^[A-Z0-9_]+$

Example

SHOPIFY

Description

Reference to the session that is being used.

Example

shop-session-abc123

Description

Name of the module that is being used.

Example

shopify-plugin

Description

Version of the module that is being used.

Example

1.0.0

Description

Swedish personal identity number for customers in Sweden.

Description

Norwegian national identity number for customers in Norway.

Description

Italian tax code (codice fiscale) for customers in Italy.

Description

Finnish personal identity code for customers in Finland.

Description

Spanish national ID (DNI) for customers in Spain.

Description

Danish civil registration number for customers in Denmark.

Description

US Social Security Number for customers in the United States.

{
    "payment_method": "klarna-network",
    "order_id": "order_kln_001",
    "order_description": "Order #kln_001",
    "currency": "EUR",
    "amount": 9900,
    "customer_email": "buyer@example.com",
    "customer_first_name": "Emma",
    "customer_last_name": "Johansson",
    "customer_phone": "+46701234567",
    "ip_address": "82.115.34.21",
    "billing_address":
    {
        "country": "SWE",
        "city": "Stockholm",
        "zip_code": "111 57"
    },
    "platform": "WEB",
    "item_category": "digital_goods",
    "future_usage":
    {
        "payment_type": "one-time"
    }
}

{
    "order":
    {
        "amount": 9900,
        "currency": "EUR",
        "order_id": "order_kln_001",
        "status": "processing",
        "method": "klarna-network",
        "customer_email": "buyer@example.com",
        "ip_address": "82.115.34.21",
        "order_description": "Order #kln_001",
        "created_at": "2026-05-19 10:31:44",
        "updated_at": "2026-05-19 10:31:44"
    },
    "pay_form":
    {
        "token": "pft1ymnx6gq32ej3dvr9p45w",
        "return_url": "https://pay.klarna.com/eu/payments/...",
        "script_url": ""
    },
    "transactions":
    []
}

{
    "payment_method": "klarna-network",
    "order_id": "order_kln_rec_001",
    "order_description": "Monthly subscription",
    "currency": "EUR",
    "amount": 9900,
    "customer_email": "buyer@example.com",
    "customer_first_name": "Emma",
    "customer_last_name": "Johansson",
    "customer_phone": "+46701234567",
    "ip_address": "82.115.34.21",
    "billing_address":
    {
        "country": "SWE",
        "city": "Stockholm",
        "zip_code": "111 57"
    },
    "platform": "WEB",
    "item_category": "digital_goods",
    "future_usage":
    {
        "payment_type": "recurring",
        "billing_amount": 9900,
        "billing_period":
        {
            "unit": "month",
            "value": 1
        }
    }
}

{
    "order":
    {
        "amount": 9900,
        "currency": "EUR",
        "order_id": "order_kln_rec_001",
        "status": "processing",
        "method": "klarna-network",
        "customer_email": "buyer@example.com",
        "ip_address": "82.115.34.21",
        "order_description": "Monthly subscription",
        "created_at": "2026-05-19 10:31:44",
        "updated_at": "2026-05-19 10:31:44"
    },
    "pay_form":
    {
        "token": "pft2abc7xyz9mnop4qrs1tuv",
        "return_url": "https://pay.klarna.com/eu/payments/...",
        "script_url": ""
    },
    "transactions":
    []
}

Klarna payment options

Klarna dynamically presents payment options based on the customer's eligibility and the merchant's Klarna payment program configuration. Options may include Pay in Full, Pay in 30 Days, Pay in N (3 or 4), and Financing. The set of options shown to a given customer is determined by Klarna at the time of authorisation.

Merchants cannot pre-select or restrict specific Klarna payment options shown to customers via the Solidgate API . Klarna's eligibility engine controls which options are shown to each customer. Merchants can configure which payment options will be enabled for customers on their Klarna Account via Klarna partner portal.

Auto-capture

Solidgate automatically captures the payment upon Klarna authorisation. No separate capture request is required. The order moves to approved status once capture is confirmed.

Recurring

Error codes

Specific errors may occur when a Klarna payment attempt fails.

Testing

Use Solidgate's test environment to validate the Klarna integration before going live. Test API keys are available in the Solidgate Hub under Settings → API keys.