Payment Tokenization Overview

Understand how to create customer tokens for future transactions, handle tokenization scenarios, and manage the step-up consent flow across integration paths.

10 min read

Payment Tokenization is the process of securely saving a customer's payment method for future use. It creates a customer token that Acquiring Partners store and use to authorize subsequent transactions — either when the customer is present (on-demand payments) or not present (subscriptions, recurring charges).

Tokenization always requires the customer to complete a step-up flow through the Klarna Purchase Journey to provide explicit consent.

Overview

Payment Tokenization follows a consistent pattern across both integration paths (server-side integration and hosted checkout):

1.
Tokenization request – Call authorizePayment with request_customer_token and token scopes
2.
Step-up response – Klarna always returns STEP_UP_REQUIRED because customer consent is mandatory for tokenization
3.
Klarna Purchase Journey – The customer completes consent in the Klarna Purchase Journey
4.
Token delivery – Klarna sends a webhook with the customer_token
5.
Final authorization (if combined with payment) – Call authorizePayment again to complete the initial Payment Authorization

Tokenization scenarios:

Scenario	Description
Tokenization only	Save a payment method without an immediate charge. Used for free trials, wallet linking, or account setup. The webhook delivers the `customer_token` directly — no further API call is needed.
Tokenization combined with authorization	Create a token while processing the first Payment Authorization. The webhook delivers both the `customer_token` and a `klarna_network_session_token` to finalize the initial payment.

Token scopes:

Scope	Authorization pattern	Use cases
`payment:customer_present`	On-demand charges when the customer is actively using the service	Ride-hailing, food delivery, in-app purchases
`payment:customer_not_present`	Recurring charges without customer interaction	Subscriptions, membership renewals, scheduled billing

Tokenization flow components:

Component	Description
Payment Authorization API	Klarna API endpoint for requesting tokenization. Refer to authorizePayment for the complete documentation
Customer Token	Token issued by Klarna representing a saved payment method, used for future authorizations
Payment Request	Entity created when Klarna requires step-up verification. Tracks the tokenization state during the Klarna Purchase Journey
Payment Transaction	Final transaction entity created when tokenization is combined with an initial Payment Authorization
Klarna Purchase Journey	Customer-facing interface for consent collection and verification
Klarna web SDK	JavaScript SDK that launches the Klarna Purchase Journey in a pop-up window (hosted checkout path)
Klarna webhooks	Asynchronous notifications delivering the customer token and authorization outcomes

Integration paths and flow

There are two ways to handle Payment Tokenization: server-side integration and hosted checkout. Both paths follow the same tokenization logic but differ in who manages the customer-facing experience and the Klarna Purchase Journey.

Server-side integration

In a server-side integration, Partners manage the customer-facing experience and redirect the customer to the Klarna Purchase Journey using the payment_request_url. The Acquiring Partner backend handles the authorizePayment API

calls and webhook processing.

When to use: Partners control their own checkout and tokenization flow, want to manage how the Klarna Purchase Journey is launched (redirect or SDK pop-up), and need flexibility in their user experience. Partners handle their own state management and error handling. This path requires the Partner to manage customer redirects, handle asynchronous webhook notifications, and implement state management for the step-up flow.

Flow steps

1.
The customer initiates tokenization (subscription signup, wallet linking, or account setup)
2.
The Partner sends a tokenization request to the Acquiring Partner API
3.
The Acquiring Partner calls authorizePayment with request_customer_token and token scopes
4.
Klarna returns STEP_UP_REQUIRED with a payment_request_url
5.
The Acquiring Partner returns the payment_request_url to the Partner
6.
The Partner redirects the customer to the Klarna Purchase Journey
7.
The customer provides consent in the Klarna Purchase Journey

If tokenization only:

Klarna sends a webhook with the customer_token
The Acquiring Partner stores the token securely and returns the internal token identifier to the Partner
The Partner confirms success to the customer

If tokenization combined with authorization:

Klarna sends a webhook with the customer_token and klarna_network_session_token
The Acquiring Partner calls authorizePayment again with the klarna_network_session_token to finalize the initial Payment Authorization
Klarna returns the Payment Authorization result (APPROVED or DECLINED)
The Acquiring Partner stores the token securely and returns the result to the Partner
The Partner confirms the outcome to the customer

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant P as Partner participant AP as Acquiring Partner participant K as Klarna C->>P: Initiate tokenization P->>AP: Request tokenization AP->>K: Call Payment Authorize API Note over AP,K: request_customer_token + step_up_config K-->>AP: STEP_UP_REQUIRED (payment_request_url) AP-->>P: Return payment_request_url P->>K: Redirect customer to Klarna Purchase Journey K->>C: Display Klarna Purchase Journey C->>K: Customer provides consent alt Tokenization only K->>AP: Webhook notification (customer_token) Note over K,AP: Tokenization complete AP-->>P: Return internal token identifier P->>C: Token saved successfully else Tokenization combined with authorization K->>AP: Webhook notification (customer_token + klarna_network_session_token) AP->>K: Call Payment Authorize API (final) Note over AP,K: Final authorization call alt Approved K-->>AP: Authorization approved K->>K: Create payment transaction AP-->>P: Return token identifier + authorization result P->>C: Token saved, payment completed else Declined K-->>AP: Authorization declined AP-->>P: Return token identifier + failure result P->>C: Token saved, payment failed end end

Hosted checkout

In a hosted checkout and embedded elements integration, Acquiring Partners manage the complete tokenization flow including presenting payment methods via the Klarna web SDK and handling the Klarna Purchase Journey. The Klarna web SDK automatically launches the Klarna Purchase Journey when step-up is required.

When to use: The Acquiring Partner controls the checkout experience and wants to manage the complete tokenization flow, including automatic handling of step-up scenarios via the Klarna web SDK. This simplifies Partner integration with fewer touchpoints and provides a consistent customer experience, but requires the Acquiring Partner to host and manage the payment form, handle webhook processing, and manage tokenization state.

Flow steps

1.
The customer initiates tokenization on the Acquiring Partner's checkout
2.
The Acquiring Partner initializes the Klarna web SDK with the appropriate intent (SUBSCRIBE, SIGNUP, ADD_TO_WALLET, or PAY)
3.
The customer selects a Klarna payment method and clicks the payment button
4.
The Klarna web SDK triggers the initiate callback with the klarnaNetworkSessionToken and paymentOptionId
5.
The Acquiring Partner backend calls authorizePayment with request_customer_token and token scopes
6.
Klarna returns STEP_UP_REQUIRED with a payment_request_id
7.
The Klarna web SDK automatically launches the Klarna Purchase Journey
8.
The customer provides consent in the Klarna Purchase Journey

If tokenization only:

Klarna sends a webhook with the customer_token
The Acquiring Partner stores the token securely and maps it to an internal identifier
The Acquiring Partner frontend confirms success to the customer

If tokenization combined with authorization:

Klarna sends a webhook with the customer_token and klarna_network_session_token
The Acquiring Partner calls authorizePayment again with the klarna_network_session_token to finalize the initial Payment Authorization
Klarna returns the Payment Authorization result (APPROVED or DECLINED)
The Acquiring Partner stores the token securely and confirms the outcome to the customer

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant AP as Acquiring Partner participant SDK as Klarna Web SDK participant K as Klarna AP->>SDK: Initialize Web SDK with intent SDK->>AP: Return payment methods C->>SDK: Select Klarna and click payment button SDK->>AP: Trigger initiate callback Note over SDK,AP: klarnaNetworkSessionToken, paymentOptionId AP->>K: Call Payment Authorize API Note over AP,K: request_customer_token + step_up_config K-->>AP: STEP_UP_REQUIRED (payment_request_url) AP->>SDK: Return paymentRequestUrl SDK->>C: Launch Klarna Purchase Journey C->>K: Customer provides consent alt Tokenization only K->>AP: Webhook notification (customer_token) Note over K,AP: Tokenization complete AP->>C: Token saved successfully else Tokenization combined with authorization K->>AP: Webhook notification (customer_token + klarna_network_session_token) AP->>K: Call Payment Authorize API (final) Note over AP,K: Final authorization call alt Approved K-->>AP: Authorization approved K->>K: Create payment transaction AP->>C: Token saved, payment completed else Declined K-->>AP: Authorization declined AP->>C: Token saved, payment failed end end

Responsibilities by integration path

Server-side integration (Partner implements)

Partner's frontend:

Collects customer consent intent (subscription signup, wallet linking)
Redirects the customer to the Klarna Purchase Journey via the payment_request_url
Handles customer return after the Klarna Purchase Journey completes
Displays tokenization result to the customer

Partner's backend:

Sends tokenization requests to the Acquiring Partner API with token scopes and payment context
Receives tokenization results and step-up details
Processes notifications about tokenization state
Manages tokenization state throughout the flow

Acquiring Partner backend:

Calls authorizePayment with request_customer_token and token scopes
Returns the payment_request_url to the Partner for customer redirect
Processes webhook notifications from Klarna
Stores the customer_token securely and maps it to an internal identifier
Calls authorizePayment again for final authorization (combined scenario only)
Returns the internal token identifier and authorization result to Partners

Hosted checkout (Acquiring Partner implements)

Acquiring Partner frontend:

Initializes the Klarna web SDK with the appropriate intent (SUBSCRIBE, SIGNUP, ADD_TO_WALLET, or PAY)
Presents Klarna payment methods via the Klarna web SDK
The Klarna web SDK automatically launches the Klarna Purchase Journey for customer consent
Handles client-side notifications from the Klarna web SDK
Displays tokenization and authorization results to the customer

Acquiring Partner backend:

Receives tokenization triggers from the frontend
Calls authorizePayment with request_customer_token and token scopes
Returns the payment_request_id to the frontend for SDK-managed step-up
Processes webhook notifications from Klarna
Stores the customer_token securely and maps it to an internal identifier
Calls authorizePayment again for final authorization (combined scenario only)
Manages tokenization state and transaction records

Klarna web SDK:

Presents payment methods with tokenization-appropriate intents
Manages the payment button and initiate callback
Automatically launches the Klarna Purchase Journey for customer consent
Handles client-side notifications and state updates
Provides event handlers for completion, abort, and error scenarios

Payment Authorize API for tokenization

The authorizePayment API

operation is used for both tokenization scenarios. The request configuration determines the tokenization behavior.

Scenario	Key parameters	Description
Tokenization only	`request_customer_token` with scopes, `currency`, `step_up_config`	Saves a payment method without an immediate charge. Do not include `request_payment_transaction` or `amount`.
Tokenization combined with authorization	`request_customer_token` with scopes, `request_payment_transaction` with `amount`, `currency`, `step_up_config`	Creates a token alongside an initial Payment Authorization. Include both token and transaction request parameters.

Webhook integration

Klarna webhooks deliver customer tokens and authorization outcomes:

Webhook Event	Trigger	Payload	Required Action
Payment Request completed (tokenization only)	Customer completes consent	`customer_token`	Store the token securely, return the internal token identifier to the Partner
Payment Request completed (combined)	Customer completes consent	`customer_token` + `klarna_network_session_token`	Store the token, call authorizePayment for final authorization
Authorization approved	Klarna creates the payment transaction	Payment transaction details	Update payment status, return result to the Partner
Authorization declined	Klarna declines the authorization	Decline reason	Return failure result to the Partner (token remains valid)

Token storage and management

After receiving the customer_token from Klarna:

Step	Description
Store securely	Persist the `customer_token` in a secure, encrypted storage system
Map to internal identifier	Create an internal token identifier that maps to the Klarna `customer_token`. Return this internal identifier to the Partner — never expose the raw Klarna token.
Associate with customer	Link the token to the customer record for future use
Track token scope	Record the token scope (`payment:customer_present` or `payment:customer_not_present`) to ensure correct usage in future authorizations

Integrate Payment Tokenization

Jump to section...