Klarna Network Session Token

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.

The Klarna network session token connects customer interactions across multiple touchpoints and resources:

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.

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_token to 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 updated klarna_network_session_token in two ways:

  • The payment.request.state-change webhook payload includes klarna_network_session_token when the request transitions to COMPLETED.
  • Reading the Payment Request returns the same token in the state_context.klarna_network_session_token field.

  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_token that 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_token that the Acquiring Partner retrieves to proceed with API calls.

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-Token header 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-Token header 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.

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_token that the Acquiring Partner must retrieve from the SDK to proceed with subsequent API calls.

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.

Klarna issues an updated 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.

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.

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