One-click payments with Klarna Web SDK (Partner orchestrated)

Charge a returning customer's saved Klarna option in a one-click, customer-initiated transaction using the Klarna Web SDK, where you orchestrate the charge. Create the Klarna payment request with the Klarna Customer Token, then finalize through Solidgate with the klarna_network_session_token.

9 min read

This guide explains how to charge a returning customer's saved Klarna option in a one-click, customer-initiated transaction using the Klarna Web SDK, where you orchestrate the charge. The customer is at checkout and has a stored Klarna Customer Token, so Klarna can be pre-selected as a one-click "Saved" option.

You restore the saved option from the Klarna Customer Token, then create Klarna's payment request yourself with the Klarna Customer Token and the selected payment_option_id. Klarna returns a klarna_network_session_token via the completion webhook, which you forward to Solidgate to finalize the charge.

Integration requirement

Charge credential: Klarna Customer Token only. Because you initiate the charge, this flow is authorized on the Klarna Customer Token only. The Solidgate token applies only when Solidgate initiates the charge — see One-click payments with Klarna Web SDK (Solidgate orchestrated).

Full Web SDK setup reference

For the full Web SDK setup (loading the SDK, rendering the payment selector, button styling, payment-request lifecycle), follow Build checkout form with Klarna Web SDK. This page covers only the saved-option specifics. To compare all tokenized flows, see the Tokenized payments overview.

Prerequisites

Before you integrate, check that you meet the following prerequisites:

1.
Ensure that you have Klarna enabled with Solidgate.
2.
A stored Klarna Customer Token for the customer, issued with the payment:customer_present scope (see Create a Klarna Customer Token).
3.
Confirm you have access to the Klarna Partner Portal with a client identifier (domain allowlisted) and an API key able to call the Klarna Payment Request API and generate a Klarna Network Session Token.
4.
Confirm that you have registered webhooks for payment.request.state-change.completed events following the Webhooks guidelines.
5.
Add Terms and Conditions covering saved payment methods.

Integration overview

1.
Generate a Klarna Network Session Token from the stored Klarna Customer Token and initialize the Web SDK with it.
2.
The payment presentation returns the customer's saved option and its payment_option_id for the one-click experience.
3.
Render Saved (pre-selected) and Pick plan in your payment selector.
4.
The customer selects the saved option; you call Klarna's Create Payment Request with the Klarna Customer Token, the payment_option_id, and a customer_interaction_config.
5.
If Klarna requires a step-up (based on risk), the Klarna Web SDK launches the Klarna Purchase Journey and the customer completes it. Otherwise the request completes immediately.
6.
Klarna fires the payment.request.state-change.completed webhook with a (new) Klarna Network Session Token.
7.
You forward the (new) Klarna Network Session Token to Solidgate to finalize the charge.
8.
Solidgate approves the order; you redirect the customer to your confirmation page.

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna participant AP as Solidgate C->>P: Visits checkout page P->>K: Generate Klarna Network Session Token POST network/session/tokens Note over P,K: Header: Klarna-Customer-Token K-->>P: Return klarna_network_session_token P->>K: Initialize Klarna Web SDK Note over P,K: klarnaNetworkSessionToken K-->>P: Return payment methods and instruction P->>P: Display Klarna payment methods C->>P: Click Klarna payment button K->>P: Trigger initiate callback Note over K,P: (new) klarna_network_session_token paymentOptionId P->>K: Create payment request POST /v2/payment/requests Note over P,K: Header: Klarna-Customer-Token Header: (new) Klarna-Network-Session-Token payment_option_id alt STEP_UP_REQUIRED K-->>P: Return payment_request_url P->>K: Forward payment_request_url to Klarna Web SDK K->>C: Launch Klarna purchase journey C->>K: Complete Klarna purchase journey end K-->>P: Payment request completed event (webhook) Note over K,P: (new) klarna_network_session_token P->>AP: Confirm payment Note over P,AP: (new) klarna_network_session_token AP-->>P: Order completed notification P-->>C: Display confirmation message

Integration details

1.
Generate a Klarna Network Session Token from the Klarna Customer Token. Before initializing the Web SDK, call the Generate Klarna Network Session Token endpoint server-side (POST /v2/network/session/tokens) with the stored Klarna Customer Token in the Klarna-Customer-Token header. The returned Klarna Network Session Token carries the customer's saved Klarna context and is directly Web SDK-compatible.
2.
Initialize the Web SDK with the Klarna Network Session Token so the payment presentation returns the saved option, including its payment_option_id for the one-click experience.
3.
Render the saved option. With a Klarna Customer Token context present, the presentation returns a savedPaymentOption (in addition to the default paymentOption) with the PRESELECT_KLARNA instruction. Render the Saved option before the default option and pre-select it; the default option becomes the Pick plan entry.

Customer token required for saved option

The Klarna Customer Token is required to present the saved option. Use it to generate a Klarna Network Session Token via generateKlarnaNetworkSessionToken (the legacy Generate SDK Token / sdk_token exchange is deprecated). The Klarna Customer Token is a durable credential — generating a session token does not consume it, so you can reuse it to generate more.

Chain a session token from Boost features

If you already hold a Klarna Network Session Token obtained when the customer interacted with a Boost feature (for example On-site messaging or Sign in with Klarna) earlier in the checkout, chain it: call generateKlarnaNetworkSessionToken with both that session token in the Klarna-Network-Session-Token header and the Klarna Customer Token in the Klarna-Customer-Token header. The returned session token is what you use to initialize the SDK, preserving session continuity across the checkout.

The recommended presentation when a Klarna Customer Token is available:


Saved Klarna option (pre-selected)	Pick Plan selected

Prioritize the savedPaymentOption by placing it before the default paymentOption. Pre-select it on PRESELECT_KLARNA, and show it as the only option on SHOW_ONLY_KLARNA.

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

function renderKlarna(paymentPresentation) {
  const { paymentOption, savedPaymentOption, instruction } = paymentPresentation;

  // Render the saved option first (Saved), then the default option (Pick plan)
  if (savedPaymentOption) renderKlarnaOption("klarna-option-saved", savedPaymentOption);
  if (paymentOption)      renderKlarnaOption("klarna-option-default", paymentOption);

  const primaryId = savedPaymentOption ? "klarna-option-saved" : "klarna-option-default";

  if (instruction === "PRESELECT_KLARNA" || instruction === "SHOW_ONLY_KLARNA") {

When the customer selects the saved option, create the Klarna payment request from your server, passing the Klarna Customer Token, the (new) klarna_network_session_token from the initiate callback, the selected payment_option_id, and a customer_interaction_config. For a payment:customer_present token the charge may complete immediately or require a short step-up, depending on Klarna's risk assessment — include the customer_interaction_config so Klarna can drive the Klarna Purchase Journey when a step-up is needed.

Field	Presence	Description
`klarna_customer_token`	required	The stored Klarna Customer Token. This is the only charge credential for a Partner-orchestrated charge.
`klarna_network_session_token`	required	The (new) session token returned by the `initiate` callback, sent in the `Klarna-Network-Session-Token` header.
`payment_option_id`	required	The saved option's `payment_option_id` from the presentation — drives the one-click "Saved" experience.
`currency`	required	Currency in ISO 4217 format.
`amount`	required	Total charge amount in non-negative minor units (e.g. $10.00 = `1000`).
`customer_interaction_config.return_url`	required	URL Klarna returns the customer to after a step-up Klarna Purchase Journey. Include it so a step-up can be completed if Klarna requires one.

BASH

1 2 3 4 5 6 7 8 9 10

curl -X POST https://api-global.test.klarna.com/v2/payment/requests \
  -H 'Authorization: Basic <API key>' \
  -H 'Klarna-Customer-Token: krn:network:eu1:live:customer-token:[...]' \
  -H 'Klarna-Network-Session-Token: krn:network:eu1:live:session-token:[...]' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "USD",
    "amount": 1000,
    "payment_option_id": "S0xBUk5BXzE3NzI3MDY2MTI2ODg=",
    "payment_request_reference": "one-click-ref-123",

Klarna's Create Payment Request response tells you whether a step-up is needed:

No step-up — the payment request completes immediately. Continue to retrieve the (new) klarna_network_session_token.
Step-up required — Klarna returns state_context.customer_interaction.payment_request_url and the payment request moves to IN_PROGRESS. Hand the payment_request_url to the Klarna Web SDK, which launches the Klarna Purchase Journey in-page for the customer to complete. Once the customer finishes, the payment request transitions to COMPLETED.

Either way, the flow converges on the payment.request.state-change.completed webhook below.

Klarna issues a (new) klarna_network_session_token once the payment request reaches COMPLETED. Retrieve it by subscribing to the payment.request.state-change.completed webhook (required); you may additionally call the Read Payment Request API API

for resilience.

Integration requirement

The klarna_network_session_token is valid for only 1 hour and must be forwarded to Solidgate within this time frame to finalize the authorization.

Forward the (new) klarna_network_session_token to Solidgate to finalize the charge. Solidgate authorizes with Klarna and returns the outcome. The request/response contract is owned by Solidgate; only the Klarna-specific token you must include is shown here.

BASH

1 2 3 4 5 6 7 8 9 10

curl -X POST https://api.acquiring-partner.com/payment \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_methods": {
      "klarna": {
        "klarna_network_session_token": ""
      }
    }

Outcome	What it means	Next step
`APPROVED`	Klarna authorized the charge.	Display the confirmation page and record the successful charge.
`DECLINED`	Klarna did not authorize the charge.	Surface a retry/alternative payment to the customer.

Integration requirement

Once any required step-up is complete and you forward the (new) klarna_network_session_token, Solidgate returns APPROVED or DECLINED. A saved-option charge often completes without a step-up, but Klarna may still require one based on risk — always handle the step-up branch above. If you instead present Klarna as a one-time payment (no Klarna Customer Token), follow Build checkout form with Klarna Web SDK.

API & SDK references

Read the state of a Payment Request

Jump to section...

One-click payments with Klarna Web SDK (Partner orchestrated)

Prerequisites

Integration overview

Integration details

Step 1: Restore and present the saved Klarna option

Step 2: Create the Klarna payment request with the Klarna Customer Token

Step 3: Handle a step-up (if required)

Step 4: Retrieve the (new) `klarna_network_session_token`

Step 5: Finalize the charge through Solidgate

Step 6: Handle the outcome