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.

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

The customer_token_response is returned as part of the authorizePayment response when the payment request reaches the COMPLETED state and request_customer_token was included in the request.

{
  "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 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.

Customer tokens are created during payment authorization by including request_customer_token in the authorizePayment 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.

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

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.

Customer tokens have a simple two-state lifecycle:

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

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