Klarna Network Session Token
Understand the Klarna network session token and how it enables seamless interoperability across Klarna's product suite. This resource explains the token's role in connecting Conversion Features with payment flows.
Overview
The
klarna_network_session_token is an opaque token issued by Klarna that enables seamless customer experiences across different Klarna integrations. It carries customer context, session state, and interaction history, allowing continuity throughout the customer journey from Conversion Features through Payment Authorization.The token is fundamental to achieving interoperability in multi-party integrations where Partners implement Conversion Features and Acquiring Partners process payments. Partners and Acquiring Partners should treat the token as a pass-through value that is forwarded to Klarna in all relevant API calls without validation or modification.
Token usage
Klarna uses
klarna_network_session_token as the required token to finalize Payment Authorization.- Existing integrations: Klarna previously used
payment_token, which continues to be returned for backward compatibility but will be removed in future versions. Plan to migrate toklarna_network_session_token. - New integrations: Use
klarna_network_session_tokenexclusively and ignorepayment_token.
Relationships and dependencies
The Klarna network session token connects customer interactions across multiple touchpoints and resources:
flowchart TB
subgraph Actors
direction LR
P[Partner]
AP[Acquiring Partner]
K[Klarna]
end
subgraph Token Flow
direction TB
BF[Conversion Features]
KNST[Klarna Network Session Token]
PA[Payment Authorization]
PR[Payment Request]
PT[Payment Transaction]
BF -->|Issues token| KNST
KNST -->|Forwarded by Partner| AP
KNST -->|Enhances| PA
PA -->|STEP_UP_REQUIRED| PR
PR -->|COMPLETED, returns updated| KNST
KNST -->|Used to finalize| PT
end
P -->|Implements| BF
P -->|Retrieves and forwards| KNST
AP -->|Forwards to Klarna| KNST
K -->|Issues and manages| KNST
K -->|Returns updated| KNST
class KNST primaryEntity
class PA secondaryEntity
class PR secondaryEntity
class PT secondaryEntity
The token enables interoperability by connecting:
- Conversion Features: Token is issued when customers interact with Sign in with Klarna, Express checkout, or On-site messaging. The token captures this context.
- Payment Authorization: When the token carries prior customer context, authorization may complete immediately without step-up.
- Payment Request: When step-up is required, the Payment Request returns an updated token upon completion that must be used to finalize the Payment Authorization.
- Payment Transaction: Created when Payment Authorization succeeds, using the token to preserve customer context.
Token issuance
The Acquiring Partner can obtain a
klarna_network_session_token through the following channels:- Provided by the Partner: The Partner retrieves the token from Conversion Features interactions (Sign in with Klarna, Express checkout, or On-site messaging) and forwards it to the Acquiring Partner.
- Exchanged from a Customer Token: The Acquiring Partner exchanges an existing Customer Token for a
klarna_network_session_tokento carry the customer's saved context into a new session. - Delivered after a Payment Request reaches
COMPLETED: When step-up is required, authorizePayment
creates a Payment Request in STEP_UP_REQUIRED. Once the customer completes the Klarna Purchase Journey, Klarna delivers an updatedklarna_network_session_tokenin two ways:- The
payment.request.state-changewebhook payload includesklarna_network_session_tokenwhen the request transitions toCOMPLETED. - Reading the Payment Request returns the same token in the
state_context.klarna_network_session_tokenfield.
The Acquiring Partner uses this updated token to finalize the Payment Authorization and create the Payment Transaction. - Generated through the Network Session API: Use generateKlarnaNetworkSessionToken to obtain a new
klarna_network_session_tokenthat enables stateful Klarna features for a session. - Requested from the Klarna Web SDK or Mobile SDK: After SDK initialization, the SDK issues a new
klarna_network_session_tokenthat the Acquiring Partner retrieves to proceed with API calls.
Token lifecycle
stateDiagram-v2
[*] --> Issued: SDK init or Conversion Features interaction
Issued --> Active: Used in API calls
Active --> Active: Forwarded through payment flows
Active --> Invalidated: Payment Transaction created
Active --> Invalidated: Used to initialize Klarna Web SDK
Active --> Invalidated: Used to initialize Klarna Mobile SDK
Invalidated --> Issued: Request new token from SDK
Active --> Expired: Timeout or session end
Active --> Issued: Partner requests new token
Token usage
The Acquiring Partner includes the
klarna_network_session_token in the following API calls and SDK operations:- Authorize a payment transaction: Include the token in the
Klarna-Network-Session-Tokenheader when calling the authorizePayment endpoint. The token carries customer context that may allow authorization to complete immediately without step-up. - Fetch payment presentation: Include the token in the
Klarna-Network-Session-Tokenheader when calling the Payment Presentation API. The token enables personalized payment methods based on the customer's session context. - Initialize the Klarna Web SDK or Mobile SDK: Pass the token during SDK initialization to transfer the customer's session context to the SDK, enabling continuity from prior Conversion Features interactions or payment flows.
Invalidation
The
klarna_network_session_token is invalidated after either of the following:- Payment Transaction creation: After the Acquiring Partner successfully creates a Payment Transaction using the token, the token is invalidated and cannot be reused.
- SDK initialization: After the token is used to initialize the Klarna Web SDK or Mobile SDK, the token is invalidated. The SDK issues a new
klarna_network_session_tokenthat the Acquiring Partner must retrieve from the SDK to proceed with subsequent API calls.
Expiration
The
klarna_network_session_token includes expiration information set by Klarna. Token validity depends on the context:- For Payment Authorization: When issued after a Payment Request completes (state
COMPLETED), the token is valid for 1 hour to finalize the Payment Authorization. Use it promptly to create the Payment Transaction. - For general session context: Tokens issued during Conversion Features interactions or SDK initialization have longer validity periods for maintaining session context.
When a token expires:
- It is ignored by Klarna's APIs (not rejected)
- The API call proceeds without the session context
- No error is returned
- A new token should be obtained for future calls
This design ensures API resilience — expired or invalid tokens don't cause integration failures.
Token updates
Klarna issues an updated call that finalizes the Payment Transaction.
klarna_network_session_token after a Payment Request reaches the COMPLETED state. The updated token is delivered in the payment.request.state-change webhook payload and is also available in the read Payment Request response under state_context.klarna_network_session_token. Replace the previous token with this value in subsequent calls — most importantly, in the Klarna-Network-Session-Token header of the follow-up authorizePayment call that finalizes the Payment Transaction.Interoperability
The token enables interoperability by preserving customer context as the session flows from Partner-implemented Conversion Features to Acquiring Partner-processed payments. When properly forwarded through all integration points, the token delivers:
- Higher conversion: Klarna leverages previous customer interactions to streamline authorization, potentially enabling immediate approval without step-up.
- Reduced friction: Customers don't re-authenticate or re-enter information already provided to Klarna.
- Consistent experience: The customer journey feels seamless across Partner and Acquiring Partner touchpoints.
When customers interact with Conversion Features before Payment Authorization, the token carries context that can reduce step-up rates and improve conversion.
Frequent use cases
The Klarna network session token is used to:
- Enable Conversion features continuity: Preserve customer context from Sign in with Klarna, Express checkout, or On-site messaging into Payment Authorization
- Finalize Payment Authorization after step-up: Use the updated token returned after Payment Request completion to create a Payment Transaction
- Forward session context: Partners pass tokens to Acquiring Partners, who forward to Klarna in all API calls
- Maintain session across operations: Include tokens in post-purchase operations (captures, refunds) to preserve customer context
Critical: No validation required
Partners and Acquiring Partners should not parse, decode, or validate the token. Expired or invalid tokens are gracefully ignored by Klarna's APIs without causing errors. Simply pass the token through as-is in all API calls.
Related articles
API & SDK references