Understand how Partners save a customer's payment method with Klarna and reuse it to authorize future Payment Transactions for on-demand purchases, subscriptions, and partner-initiated authorizations.
Payment Tokenization is the process of securely saving a customer's Klarna payment method for future use. It produces a customer_token that Partners store and use to authorize subsequent Payment Transactions, either when the customer is actively initiating the payment (on-demand purchases, one-click checkout) or when the Partner is initiating the authorization on behalf of the customer (subscription renewals, scheduled authorizations).
To enable repeat purchases, subscriptions, or on-demand authorizations, Partners must first create a Customer Token through customer-present consent in the Klarna Purchase Journey. Once Klarna has issued the Customer Token, the Partner can subsequently use it to authorize future Payment Transactions on behalf of the customer.
Tokenization scenarios
Scenario
When to use
Tokenization only
Save a payment method without an immediate Payment Authorization (for example, free trials, wallet linking, or account setup). The Payment Request completion delivers the customer_token directly. No second API call is needed.
Tokenization combined with authorization
Save a payment method and authorize the first Payment Transaction in the same flow (for example, the first month of a subscription, or a one-off purchase that also enables on-demand re-authorizations). Klarna delivers both the customer_token and a Klarna Network Session Token, and Partners call authorizePayment to create the initial Payment Transaction.
End-to-end flow
For Partners, tokenization is built on the same Payment Request resource as a Payment Authorization. The flow always starts by creating a Payment Request with createPaymentRequest and asking Klarna to issue a token via request_customer_token. The customer completes the Klarna Purchase Journey to grant consent, and Klarna issues the customer_token to the Partner, either alone (tokenization only) or alongside a first Payment Transaction (tokenization combined with authorization). Detailed steps for each scenario are covered in Tokenization flows in detail.
Token scopes
The scopes set on request_customer_token define how the resulting token can be used. Partners must pick the scope that matches the use case. Klarna issues exactly one scope per token.
Scope
Authorization pattern
Typical use cases
payment:customer_present
The customer is actively initiating the payment when re-authorizing. Subsequent authorizations start with createPaymentRequest and the customer completes the Klarna Purchase Journey before authorizePayment.
The Partner initiates the authorization without customer interaction. The authorization happens directly without redirecting the customer anywhere.
Subscription renewals, membership billing, scheduled or metered authorizations.
Tokenization flows in detail
The simplest tokenization flow saves a payment method without an immediate Payment Transaction. Partners create a Payment Request with request_customer_token and withoutrequest_payment_transaction (or amount). When the customer approves, Klarna issues the token via the Payment Request completion. There is no second authorize call.
Sequence diagram
sequenceDiagram
autonumber
participant C as Customer
participant P as Partner
participant K as Klarna
C->>P: Initiate tokenization
P->>K: createPaymentRequest (request_customer_token, scopes, customer_interaction_config)
K-->>P: payment_request_id, payment_request_url (state SUBMITTED)
P->>C: Redirect to payment_request_url (or launch via Web SDK)
C->>K: Authenticate and approve tokenization
K-->>P: Webhook payment.request.state-change.completed
Note over K,P: state COMPLETED, customer_token in state_context.klarna_customer
P->>C: Confirm tokenization success
Flow steps
The customer initiates tokenization on the Partner's frontend (subscription signup, "save for later", wallet linking).
request_customer_token and the desired scopes (typically payment:customer_not_present for subscriptions or payment:customer_present for on-demand).
currency.
customer_interaction_config (HANDOVER + return_url). The Klarna Purchase Journey is mandatory because the customer must consent to the token.
Klarna returns a Payment Request in SUBMITTED state with a payment_request_url.
Launch the Klarna Purchase Journey, either by redirecting the customer to payment_request_url (server-side integration) or via the Klarna Web SDK.
The customer authenticates and approves tokenization.
Klarna sends a payment.request.state-change.completed webhook. The payload, and state_context.klarna_customer.customer_token on the Payment Request, carry the issued customer_token.
Both integration paths use the same API model: a Payment Request followed (when needed) by an authorize call. What differs is how the Klarna Purchase Journey is launched.
Path
How the Klarna Purchase Journey is launched
When to use
Server-side integration
The Partner's backend creates the Payment Request, returns the payment_request_url to the frontend, and the customer's browser is redirected. After the journey, Klarna sends the customer back to the configured return_url.
The Klarna Web SDK is embedded in the checkout. The SDK calls the Partner's backend (which still creates the Payment Request) and orchestrates the Klarna Purchase Journey in a popup or modal, with no full-page redirect.
Single-page web checkouts where the Klarna Purchase Journey should happen in-context.
In both paths, the API contract is identical: createPaymentRequest with request_customer_token, then, for combined tokenization, authorizePayment with the Klarna Network Session Token after the customer completes the Klarna Purchase Journey.
Authorize a payment with the customer token
Once a customer_token is issued, Partners reuse it on subsequent authorizations by passing it in the Klarna-Customer-Token request header. The pattern depends on whether the customer is initiating the payment or the Partner is initiating it on the customer's behalf.
When the customer is actively initiating the payment (for example, completing a one-click purchase or buying a ride), start with createPaymentRequest and pass the stored token in the Klarna-Customer-Token header. The customer completes the Klarna Purchase Journey for that Payment Request, as for any customer-initiated payment, and the Partner then finalizes the Payment Transaction with authorizePayment.
Klarna-Customer-Token header containing the stored customer_token.
currency and amount.
supplementary_purchase_data describing this purchase.
customer_interaction_config with method = HANDOVER and a return_url (and optionally app_return_url for mobile).
The Partner launches the Klarna Purchase Journey for the Payment Request, using the Klarna Web SDK or a redirect.
When the customer completes the Klarna Purchase Journey, Klarna delivers a Klarna Network Session Token on the payment.request.state-change.completed webhook.
The Partner's backend calls authorizePayment with the Klarna Network Session Token in the Klarna-Network-Session-Token header to create the Payment Transaction. Persist the payment_transaction_id on APPROVED.
Use scope payment:customer_present. For the full authorization contract, including results and step-up handling, see Authorize a customer-initiated payment.
Sequence diagram
sequenceDiagram
autonumber
participant C as Customer
participant FE as Partner frontend
participant BE as Partner backend
participant K as Klarna
C->>FE: Triggers a one-click purchase / on-demand authorization
FE->>BE: Initiate authorization (amount, token reference)
BE->>K: createPaymentRequest with Klarna-Customer-Token header
K-->>BE: Payment Request (SUBMITTED) + paymentRequestUrl
BE->>FE: payment_request_id / paymentRequestUrl
FE->>K: Launch Purchase Journey (Web SDK or redirect)
C->>K: Completes Purchase Journey
K-->>BE: Webhook payment.request.state-change.completed (klarna_network_session_token)
BE->>K: authorizePayment with Klarna-Network-Session-Token header
K-->>BE: APPROVED / STEP_UP_REQUIRED / DECLINED
BE->>FE: Show result
When the Partner is initiating the authorization on behalf of the customer (for example, a monthly subscription renewal), call authorizePaymentdirectly with the Klarna-Customer-Token header and withoutstep_up_config. There is no customer available to complete a step-up Klarna Purchase Journey, so step-up is not a valid recovery path.
Klarna-Customer-Token header containing the stored customer_token.
currency and request_payment_transaction.amount.
supplementary_purchase_data describing this purchase, including the subscriptions[] or ondemand_service context.
Klarna evaluates the authorization and returns APPROVED or DECLINED. STEP_UP_REQUIRED is not a possible outcome for partner-initiated authorizations, and step_up_config should not be included.
On APPROVED, Klarna creates the Payment Transaction. Persist the payment_transaction_id and continue with capture/refund as needed.
Use scope payment:customer_not_present.
Token-based authorization flow
Customer-initiated token authorizations start with createPaymentRequest, like any customer-initiated payment, with the stored token in the Klarna-Customer-Token header. Partner-initiated token authorizations call authorizePayment directly with the Klarna-Customer-Token header and no step_up_config.
The customer completes the Klarna Purchase Journey for the Payment Request
Never
Possible authorize results
APPROVED, DECLINED, STEP_UP_REQUIRED
APPROVED, DECLINED
Webhooks
Subscribe to Klarna webhooks to receive tokenization outcomes asynchronously. The events relevant to tokenization are the standard Payment Request state-change events. The tokenization context lives in the payload.
The customer completed consent for the combined flow. The payload sets state = COMPLETED and includes the klarna_network_session_token.
Call authorizePayment with the Klarna Network Session Token to finalize the Payment Transaction. The response carries both customer_token_response and payment_transaction_response.
payment.request.state-change.canceled
The customer canceled before approving. The payload sets state = CANCELED.
Clean up local state. No token is issued.
payment.request.state-change.expired
The Payment Request expired before completion. The payload sets state = EXPIRED.
Prompt the customer to retry. No token is issued.
Subscribe to events via the Webhooks registration guide. As a fallback, the Payment Request can always be read directly to pick up the customer_token or klarna_network_session_token from state_context.
Token storage and security
Treat customer_token values as sensitive credentials. They allow authorizations on behalf of the customer until they expire or are revoked.
Practice
Description
Store securely
Persist customer_token values in encrypted storage. Restrict access to the systems that authorize Payment Transactions.
Associate with the customer
Link each token to the relevant customer record, including the issuing scope and the issuance timestamp.
Track scope and intent
Record the token's scope (payment:customer_present or payment:customer_not_present) and the business intent (subscription, wallet, on-demand) so the right token can be picked at authorization time.
Honor lifecycle events
When a customer cancels their subscription or removes their saved payment method, stop using the token and delete it or mark it as inactive.
Do not expose tokens
Never return raw customer_token values to frontends, mobile clients, or third parties. Reference them by an internal identifier instead.
For the conceptual model and lifecycle of the resource, see Customer Token.