Customer Token

Customer tokens enable the Acquiring Partner to charge a customer's saved payment method for subscriptions, recurring payments, and one-click checkout without requiring the customer to re-authorize each transaction.

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 traditional payment tokens that simply represent 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 a unique opaque string identifier that represents a customer's payment authorization
Scope-based permissions: Tokens include scopes that define when and how they can be used
No expiration: Tokens remain valid indefinitely unless explicitly revoked
Reusable: Single token enables multiple future transactions within scope permissions
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: Saved payment methods linked to customer accounts

See the Payment Tokenization deep-dive article for detailed information on tokenization flows and best practices.

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. Use this in the `Klarna-Customer-Token` header when authorizing payment transactions.	`krn:customer-token:eu1:<customer-token-id>`
`scopes`	array of strings	Authorization scopes defining when the token can be used. Contains either `payment:customer_present` or `payment:customer_not_present`.	`["payment:customer_not_present"]`
`customer_token_reference`	string (optional)	The Acquiring Partner's internal identifier for the token. Use this to reconcile tokens with the Acquiring Partner's customer records.	`"subscription-user-12345"`

Example token response

The customer_token_response is returned as part of the authorizePayment API

response when the payment request reaches the COMPLETED state and request_customer_token was included in the request.

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

Token scopes determine when and how a customer token can be used. If the Acquiring Partner attempts to authorize a payment transaction 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 verification	On-demand services, wallet payments, one-click checkout
`payment:customer_not_present`	Partner-initiated	No – the Acquiring Partner charges without customer interaction	No – the customer cannot complete verification	Subscriptions, recurring charges, scheduled payments

Scope selection guidelines:

Choose payment:customer_present when:

The customer will actively initiate each purchase
The customer is available to complete verification if 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 during payment authorization
Subscription or recurring payment pattern

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

Creating customer tokens

Customer tokens are created during payment authorization by including request_customer_token in the authorizePayment API

request. Tokenization must occur when the customer is actively present and can provide consent.

Tokenization can be performed in two ways:

Tokenization only: Save a payment method without immediate charge (for example, during free trial signup or wallet setup)
Tokenization combined with payment authorization: Create token while processing the first payment (for example, subscription signup with initial payment)

For detailed tokenization flows, requirements, and complete code examples, see the Payment Tokenization article.

Using customer tokens

Once created, customer tokens are used to authorize payment transactions by including the token in the Klarna-Customer-Token header when calling authorizePayment API

The authorization pattern depends on the token scope:

Customer-initiated authorization (scope: payment:customer_present): Used for on-demand purchases where the customer actively initiates each transaction. Include step_up_config to allow step-up authentication if needed.
Partner-initiated authorization (scope: payment:customer_not_present): Used for automatic recurring charges like subscription renewals. Never include step_up_config as the customer is not present.

For detailed authorization patterns, flows, best practices, and complete code examples, see the Payment Tokenization article.

Token lifecycle

Customer tokens have a simple two-state lifecycle:

stateDiagram-v2 [*] --> ACTIVE: Tokenization via authorizePayment ACTIVE --> ACTIVE: Successful authorizations ACTIVE --> REVOKED: Customer or Acquiring Partner 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, revoke token
`REVOKED`	Token has been canceled by the customer or the Acquiring Partner. 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 or the Acquiring Partner's interface
Acquiring Partner action: The Acquiring Partner revokes the token when the customer cancels a subscription or closes an account
Compliance: Klarna revokes the token due to account closure or regulatory requirements

Token expiration:

Customer tokens do not expire. Once created, they remain valid until explicitly revoked by the customer, the Acquiring Partner, or Klarna. Store tokens securely and use them as long as customer consent remains valid.

Storage and security

Security best practices:

Store customer_token securely
Implement access controls limiting token access to authorized services
Log all token usage for audit purposes
Never expose tokens in client-side code or public APIs

What to store:

customer_token: Required for authorizations
customer_token_reference: The Acquiring Partner's internal identifier
scopes: To validate usage patterns
Creation timestamp and last used timestamp
Associated customer and subscription identifiers

authorizePayment: Creates customer tokens (when request_customer_token is included) and authorizes payment transactions (when customer token is provided in header)
Token revocation: Currently managed through customer-facing interfaces or by ceasing token usage

Payment Tokenization: Deep-dive article covering tokenization concepts, flows, authorization patterns, and best practices
Payment Authorization: Core authorization operation that creates and uses customer tokens
Payment Transaction: The authorized payment resource created when using customer tokens
Klarna Network Session Token: Context token that enhances authorization approval rates during tokenization
authorizePayment specification: Complete API reference for tokenization and authorization using customer tokens