For PartnersFor Acquiring Partners
Klarna

Payment Tokenization Overview

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

ScenarioWhen to use
Tokenization onlySave 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 authorizationSave 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 authorizePaymentAPI 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 createPaymentRequestAPI 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.
ScopeAuthorization patternTypical use cases
payment:customer_presentThe customer is actively initiating the payment when re-authorizing. Subsequent authorizations start with createPaymentRequestAPI and the customer completes the Klarna Purchase Journey before authorizePaymentAPI.One-click checkout, ride-hailing, food delivery, in-app purchases.
payment:customer_not_presentThe 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 without request_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).
  • The Partner's backend calls createPaymentRequestAPI with:
    • 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.
  • Store the token securely and confirm success to the customer.

Integration paths

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.
PathHow the Klarna Purchase Journey is launchedWhen to use
Server-side integrationThe 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.Server-rendered checkouts, native mobile apps, and any flow that does not embed the Klarna Web SDK. See the canonical pattern in Authorize a customer-initiated payment (server-side).
Klarna Web SDKThe 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: createPaymentRequestAPI with request_customer_token, then, for combined tokenization, authorizePaymentAPI 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.

Customer-initiated authorization (on-demand, one-click)

When the customer is actively initiating the payment (for example, completing a one-click purchase or buying a ride), start with createPaymentRequestAPI 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 authorizePaymentAPI.
  • The Partner's backend calls createPaymentRequestAPI with:
    • 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 authorizePaymentAPI 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

Partner-initiated authorization (subscriptions, scheduled billing)

When the Partner is initiating the authorization on behalf of the customer (for example, a monthly subscription renewal), call authorizePaymentAPI directly with the Klarna-Customer-Token header and without step_up_config. There is no customer available to complete a step-up Klarna Purchase Journey, so step-up is not a valid recovery path.
  • The Partner's backend calls authorizePaymentAPI with:
    • 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 createPaymentRequestAPI, like any customer-initiated payment, with the stored token in the Klarna-Customer-Token header. Partner-initiated token authorizations call authorizePaymentAPI directly with the Klarna-Customer-Token header and no step_up_config.

Comparison

AspectCustomer-initiatedPartner-initiated
Token scopepayment:customer_presentpayment:customer_not_present
Starting callcreatePaymentRequestAPI with Klarna-Customer-TokenauthorizePaymentAPI with Klarna-Customer-Token
Authorize callauthorizePaymentAPI with the Klarna-Network-Session-Token from the payment.request.state-change.completed webhookThe starting call authorizes the payment
step_up_configSee Authorize a customer-initiated paymentDo not include
Customer interactionThe customer completes the Klarna Purchase Journey for the Payment RequestNever
Possible authorize resultsAPPROVED, DECLINED, STEP_UP_REQUIREDAPPROVED, 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.
EventWhen it firesRequired action
payment.request.state-change.completed (tokenization only)The customer completed consent. The payload sets state = COMPLETED and exposes the customer_token at state_context.klarna_customer.customer_token.Store the token securely. No further API call is needed.
payment.request.state-change.completed (tokenization combined)The customer completed consent for the combined flow. The payload sets state = COMPLETED and includes the klarna_network_session_token.Call authorizePaymentAPI 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.canceledThe customer canceled before approving. The payload sets state = CANCELED.Clean up local state. No token is issued.
payment.request.state-change.expiredThe 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.
PracticeDescription
Store securelyPersist customer_token values in encrypted storage. Restrict access to the systems that authorize Payment Transactions.
Associate with the customerLink each token to the relevant customer record, including the issuing scope and the issuance timestamp.
Track scope and intentRecord 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 eventsWhen 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 tokensNever 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.
Related articles
Payment Request
Integrate Payment Presentation
Authorize customer-initiated transactions
Set up your webhooks
Customer Token
Support
Partner support•Service Status
Cookies|Terms & Conditions|Copyright Klarna AB 2026
Jump to section...