Customer Token

A customer token represents a customer's saved Klarna payment method and their consent to be charged. Partners use it to authorize subscriptions, recurring authorizations, and on-demand purchases without requiring the customer to re-authorize each transaction.

8 min read

What is a customer token

A customer_token is a unique, secure identifier issued by Klarna that represents a customer's saved payment method and their consent to be charged. Unlike a traditional payment token that simply represents card credentials, a Klarna customer token encompasses the customer's relationship with Klarna, including credit evaluation, payment preferences, and authorization scope.

Key characteristics:

Unique identifier: Each token is an opaque string identifier representing the customer's payment authorization.
Scope-based permissions: Tokens carry a scope that defines when and how they can be used.
No expiration: Tokens remain valid indefinitely unless explicitly revoked.
Reusable: A single token enables multiple future Payment Transactions within its scope.
Secure: Tokens never expose underlying payment credentials or customer details.

When to use customer tokens:

Subscriptions: Automatically charge customers at regular intervals without interaction.
On-demand services: Enable one-click payments for authenticated customers.
Recurring payments: Process scheduled payments without re-authorization.
Account-based checkout: Persist saved payment methods linked to customer accounts.

This page is the resource-level reference for the customer_token entity itself. For the end-to-end tokenization flow, see Payment Tokenization overview and the Payment Tokenization resource.

Token structure

Customer tokens have a simple structure with core properties and metadata.

Core properties

Property	Type	Description	Example
`customer_token`	string	Unique opaque identifier for the customer token. Treat this as an opaque string. Pass it in the `Klarna-Customer-Token` header when authorizing future Payment Transactions.	`krn:customer-token:eu1:a1b2c3d4-e5f6-7890-abcd-ef1234567890`
`scopes`	array of strings	Authorization scopes defining when the token can be used. Contains exactly one of `payment:customer_present` or `payment:customer_not_present`.	`["payment:customer_not_present"]`
`customer_token_reference`	string (optional)	The Partner's internal reference for the token. Use this to reconcile tokens with customer or subscription records.	`"subscription-user-12345"`

Example token response

The customer_token_response is returned in the response body of authorizePayment API

whenever request_customer_token was included, either on the upstream createPaymentRequest API

(after the Payment Request reaches the COMPLETED state) or directly on the authorizePayment API

call.

For tokenization-only flows (no initial payment), the issued token is also available on the Payment Request itself at state_context.klarna_customer.customer_token once the Payment Request transitions to COMPLETED. It can be picked up directly from the payment.request.state-change.completed webhook payload without a follow-up authorize call.

JSON

1 2 3 4 5 6 7 8 9 10

{
  "customer_token_response": {
    "result": "APPROVED",
    "customer_token": {
      "customer_token": "krn:customer-token:eu1:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "customer_token_reference": "subscription-user-12345",
      "scopes": ["payment:customer_not_present"]
    }
  }
}

Token scopes

The token's scope determines when and how it can be used. When a Payment Transaction is authorized with a scope that does not match the token, the authorization is declined.

Scope	Usage Pattern	Customer Presence Required	Step-up Possible	Use Cases
`payment:customer_present`	Customer-initiated	Yes, the customer actively approves each transaction	Yes, Klarna may require additional customer interaction	On-demand services, wallet payments, one-click checkout
`payment:customer_not_present`	Partner-initiated	No, the authorization runs without customer interaction	No, the customer cannot complete a step-up Klarna Purchase Journey	Subscriptions, recurring authorizations, scheduled payments

Recommended for integration

Scope selection guidelines:

Choose payment:customer_present when:

The customer will actively initiate each purchase.
The customer is available to complete a step-up Klarna Purchase Journey when needed.
Transactions are irregular or on-demand.

Choose payment:customer_not_present when:

Charges occur automatically on a schedule.
The customer will not be present at authorization time.
The pattern is a subscription or other recurring billing.

Selecting the wrong scope can lead to authorization failures. See the Payment Tokenization overview for detailed guidance.

Creating customer tokens

Customer tokens are created by including request_customer_token on createPaymentRequest API

, or directly on authorizePayment API

when authorizing with a Klarna Network Session Token issued by a Boost feature (Express checkout, Sign in with Klarna, On-site messaging). Tokenization always requires the customer to be actively present to give consent through the Klarna Purchase Journey.

A token can be issued in two ways:

Tokenization only: Save a payment method without an immediate charge (for example, free trial signup, wallet linking, or "save for later"). The token is delivered via the Payment Request completion. No follow-up authorize call is required.
Tokenization combined with payment authorization: Save the payment method and take an initial charge in the same customer session (for example, a subscription signup with a first installment). After the customer completes the Klarna Purchase Journey, call authorizePayment with the Klarna Network Session Token to issue the token and create the first Payment Transaction.

For full request shapes, sequence diagrams, and code examples, see:

Payment Tokenization overview: concepts and end-to-end flows.
Tokenization for server-side integration: backend-only implementation.
Tokenization for hosted checkout pages and embedded elements: Klarna Web SDK implementation.

Using customer tokens

Once a customer_token is available, Partners use it to authorize future Payment Transactions by passing it in the Klarna-Customer-Token request header. Both authorization patterns start with authorizePayment and bypass the upfront Payment Request, because the stored token already represents the customer's consent. What differs is whether step_up_config is included to opt in to step-up.

Customer-present authorizations (scope: `payment:customer_present`)

Used for on-demand purchases where the customer is actively using the Partner's service (one-click checkout, in-app purchases, ride-hailing).

1.
Call authorizePayment directly with the Klarna-Customer-Token header, the purchase amount, currency, supplementary_purchase_data, and step_up_config with customer_interaction_config.method = HANDOVER and a return_url (and optionally app_return_url for mobile).
2.
Klarna returns APPROVED, STEP_UP_REQUIRED, or DECLINED. On STEP_UP_REQUIRED, the response includes a new Payment Request. Launch the Klarna Purchase Journey using it, and after the customer completes the step-up Klarna Purchase Journey call authorizePayment again with the new Klarna Network Session Token to finalize.
3.
Always include step_up_config. Without it, Klarna returns DECLINED instead of STEP_UP_REQUIRED whenever additional customer interaction would have been needed, so recoverable cases will fail.

Customer-not-present authorizations (scope: `payment:customer_not_present`)

Used for automatic recurring authorizations such as subscription renewals or scheduled billing. The customer is not available, so step-up is not a valid recovery path.

1.
Call authorizePayment directly with:
- 1.1.
  Klarna-Customer-Token header containing the stored customer_token.
- 1.2.
  currency and request_payment_transaction.amount.
- 1.3.
  supplementary_purchase_data matching the original tokenization context (for example, the subscriptions[] block).
2.
Klarna evaluates the authorization and returns APPROVED or DECLINED. STEP_UP_REQUIRED is not a possible outcome here. Never include step_up_config.
3.
On APPROVED, persist the payment_transaction_id and continue with capture or refund as needed.

For the full comparison and request shapes, see Payment Tokenization overview: Authorize a payment with the customer token.

Token lifecycle

Customer tokens have a simple two-state lifecycle:

stateDiagram-v2 [*] --> ACTIVE: Tokenization via createPaymentRequest / authorizePayment ACTIVE --> ACTIVE: Successful authorizations ACTIVE --> REVOKED: Customer or Klarna revokes REVOKED --> [*]: Cannot be reactivated

Token states

State	Description	Can Authorize Payment Transactions	Actions Available
`ACTIVE`	Token is valid and ready for use. Remains in this state indefinitely unless revoked.	Yes	Authorize Payment Transactions
`REVOKED`	Token has been canceled by the customer or by Klarna. Cannot be reactivated. This is a final state.	No	None (final state)

Token revocation

Tokens can be revoked through:

Customer action: The customer removes the saved payment method through Klarna's portal.
Klarna action: Klarna revokes the token due to account closure, fraud signals, or regulatory requirements.

When the customer cancels their subscription or closes their account on the Partner's side, stop using the token and remove it (or mark it as inactive). There is no Partner-initiated revocation API.

Storage and security

Security best practices:

Store customer_token values in encrypted storage.
Implement access controls limiting token access to the services that issue authorizations.
Log all token usage for audit purposes.
Never expose tokens in client-side code, mobile clients, or any public API. Reference them by an internal identifier instead.

What to store: