Payment Tokenization

Payment Tokenization enables customers to securely save their payment method with Klarna for future transactions. Instead of storing raw payment credentials, Klarna issues a secure digital token that represents the customer's payment agreement. This enables seamless repeat purchases like subscriptions and on-demand services while maintaining security and control through defined token scopes.

What is payment tokenization

Payment Tokenization is the process of creating a secure digital token that represents a customer's saved payment method and authorization to charge it. Instead of storing or transmitting sensitive payment credentials, the Acquiring Partner uses this token to initiate future payment authorizations. Each token has defined scopes that determine when and how it can be used, ensuring compliance with payment regulations and customer consent requirements.

Core components:

Customer Token: A unique identifier (for example, krn:customer-token:eu1:abc123) that represents the customer's saved payment method
Token Scopes: Permissions that define whether the token can be used for customer-initiated or Acquiring Partner-initiated charges

How it differs from traditional card tokenization:

Unlike traditional card tokenization that simply replaces a card number, Klarna's tokenization represents an agreement between the customer and Klarna that encompasses credit evaluation, payment preferences, and authorization scope. When the Acquiring Partner uses a Klarna token, it is not just referencing payment credentials — it is invoking a pre-established relationship with defined terms.

Why use tokenization

Tokenization enables recurring payment experiences while reducing friction and maintaining security. Understanding when to use tokenization helps the Acquiring Partner design the right payment flow for each use case.

Use cases

Use Case	Description	Token Scope	Initiation Pattern
Subscriptions	Recurring charges at regular intervals (monthly, annually) without customer interaction. Requires explicit consent and transparent communication about billing schedule.	`payment:customer_not_present`	Acquiring Partner-initiated
On-demand services	Customer-initiated purchases using a saved payment method. Common for ride-hailing, streaming, food delivery, or e-commerce where customers want one-click checkout.	`payment:customer_present`	Customer-initiated
Free trial with subscription	Save a payment method during the free trial period, then automatically charge when the trial ends. Requires clear disclosure of trial terms and billing start date.	`payment:customer_not_present`	Acquiring Partner-initiated (after trial)
Wallet or account linking	Save a payment method to a digital wallet or account for future purchases. No immediate charge. Enables fast checkout across multiple purchases.	`payment:customer_present`	Customer-initiated (each use)
Mixed payments	Combine a one-time purchase with a subscription (for example, buying hardware with a service subscription). Creates token while completing the initial transaction.	`payment:customer_not_present`	Combined (initial), then Acquiring Partner-initiated

Benefits

For customers:

Seamless checkout: One-click payments without re-entering payment details
Flexible payment methods: Access to Klarna's payment methods (Pay Later, Pay in installments)
Transparent control: Clear understanding of authorization scope and the ability to revoke consent
Reduced friction: Faster repeat purchases with saved preferences

For Acquiring Partners:

Higher conversion: Reduced checkout friction increases completion rates
Predictable revenue: Automated recurring payments for subscriptions
Lower operational costs: Reduced payment processing overhead for repeat customers
Better customer retention: Smooth payment experience encourages repeat business

Token scopes

Token scopes define what actions can be performed with a token. Choosing the correct scope is critical for authorization success and regulatory compliance.

Scope	Customer Presence	Authorization Behavior	Use Cases	Compliance Requirements
`payment:customer_present`	Customer actively initiates and approves each transaction	May succeed immediately (one-click) or require step-up authentication for additional verification	On-demand purchases, wallet payments, customer-initiated charges	Customer must actively approve each transaction. Suitable for Strong Customer Authentication (SCA) requirements.
`payment:customer_not_present`	The acquiring partner initiates without customer interaction	Succeeds or fails immediately. No step-up possible; different risk models apply	Subscriptions, recurring charges, scheduled payments	Requires explicit consent, documented recurring payment agreement, transparent billing communication, clear cancellation process

Choosing the correct token scope:

Use payment:customer_present when the customer will actively participate in each transaction. This scope enables the best authorization rates for one-time or irregular purchases because Klarna can request step-up authentication if needed.
Use payment:customer_not_present when charges occur automatically without customer interaction. While this scope could technically work for customer-initiated scenarios, it may limit the payment methods Klarna can offer, potentially reducing authorization rates.

Authorizing with tokens

Once the Acquiring Partner has a customer token, it can be used to authorize payment transactions. The authorization pattern depends on the token scope and customer presence.

Aspect	Customer-Initiated	Partner-Initiated
Customer presence	Required – actively completing purchase	Not present – automated charge
Token scope	`payment:customer_present`	`payment:customer_not_present`
Step-up configuration	Always include `step_up_config`	Never include `step_up_config`
Possible results	`APPROVED`, `STEP_UP_REQUIRED`, `DECLINED`	`APPROVED`, `DECLINED` only
Risk evaluation	Standard risk models; step-up available	Customer-not-present risk models; stricter evaluation
Approval optimization	Include Klarna Network Session Token when available	Maintain consistent billing patterns; notify before charges
Common scenarios	On-demand purchases; one-click checkout	Subscription renewals; scheduled payments

Customer-initiated authorization

Used when the customer actively initiates a purchase using their saved payment method. The customer is present and can complete step-up authentication if required.

Requirements:

Token must have payment:customer_present scope
Include step_up_config to allow step-up if needed
Customer must be available to complete Klarna Purchase Journey
Can use Klarna Network Session Token if available to improve approval rates

Authorization flow:

sequenceDiagram participant Customer participant Partner participant Acquiring Partner participant Klarna Customer->>Partner: Initiates purchase with saved payment Partner->>Acquiring Partner: Authorize payment with customer_token Acquiring Partner->>Klarna: authorizePayment (customer_token + amount + step_up_config) Klarna->>Klarna: Evaluate authorization Check risk, fraud, credit alt Immediate Approval (One-click) Klarna->>Acquiring Partner: APPROVED Payment Transaction created Acquiring Partner->>Partner: Payment success Partner->>Customer: Order confirmed else Step-up Required Klarna->>Acquiring Partner: STEP_UP_REQUIRED Payment Request created Acquiring Partner->>Partner: Requires customer verification Partner->>Customer: Launch Purchase Journey Customer->>Klarna: Completes verification Klarna->>Partner: Completion webhook with new Klarna Network Session Token Partner->>Acquiring Partner: Retry with new Klarna Network Session Token Acquiring Partner->>Klarna: authorizePayment (new Klarna Network Session Token) Klarna->>Acquiring Partner: APPROVED Acquiring Partner->>Partner: Payment success Partner->>Customer: Order confirmed else Declined Klarna->>Acquiring Partner: DECLINED Acquiring Partner->>Partner: Payment failed Partner->>Customer: Select different payment method end

Example request:

JSON

1 2 3 4 5 6 7 8 9 10

POST /v2/accounts/{partner_account_id}/payment/authorize
Content-Type: application/json
Klarna-Customer-Token: krn:customer-token:eu1:abc123

{
  "currency": "USD",
  "request_payment_transaction": {
    "amount": 4599,
    "payment_transaction_reference": "order-20250208-001"
  },

When step-up occurs:

First-time use of token with new device
High-value transaction above normal patterns
Risk signals indicate additional verification needed
Payment option requires authentication (for example, bank verification)
Regulatory requirements (Strong Customer Authentication)

Partner-initiated authorization

Used when the Acquiring Partner automatically charges the customer without active participation. Common for subscription renewals and scheduled payments.

Requirements:

Token must have payment:customer_not_present scope
Do NOT include step_up_config (the customer cannot complete it)
Authorization succeeds or fails immediately (no step-up possible)
Must comply with subscription regulations and customer notification requirements

Authorization flow:

sequenceDiagram participant System as Partner System participant Acquiring Partner participant Klarna participant Customer Note over System: Subscription renewal date System->>Acquiring Partner: Authorize recurring payment Acquiring Partner->>Klarna: authorizePayment (customer_token + amount) No step_up_config Klarna->>Klarna: Evaluate with customer_not_present risk model alt Authorization Approved Klarna->>Acquiring Partner: APPROVED Payment Transaction created Acquiring Partner->>System: Payment success System->>Customer: Email: Payment successful else Authorization Declined Klarna->>Acquiring Partner: DECLINED result_reason provided Acquiring Partner->>System: Payment failed System->>Customer: Email: Payment failed, update payment method System->>System: Retry logic or subscription pause end

Example request:

JSON

1 2 3 4 5 6 7 8 9 10

POST /v2/accounts/{partner_account_id}/payment/authorize
Content-Type: application/json
Klarna-Customer-Token: krn:customer-token:eu1:xyz789

{
  "currency": "USD",
  "request_payment_transaction": {
    "amount": 999,
    "payment_transaction_reference": "subscription-renewal-feb-2025"
  },

Partner-initiated authorization best practices:

Notify before charging: Send email notification 3-5 days before renewal
Handle declines gracefully: Implement retry logic with exponential backoff
Update customer promptly: Notify immediately if authorization fails
Respect cancellations: Stop charging immediately when the customer cancels
Maintain transparency: Clearly communicate billing schedule and amounts
Store token securely: Protect customer tokens with the same safeguards as payment credentials — a compromised token can authorize real charges

Tokenization scenarios

Tokens are created using authorizePayment API

. Tokenization can occur standalone (save a payment method only) or combined with an initial payment authorization.

Scenario	When to Use	Request Configuration	Outcome
Tokenization only	Save a payment method without immediate charge. Used for free trials, wallet setup, or account creation.	No `amount` field. Include `request_customer_token` with desired scope.	Customer token created. No payment transaction.
Tokenization combined with payment authorization	Create token while processing the first payment authorization. Used for subscription signup with initial payment.	Include `amount` and `request_customer_token`.	Both customer token and payment transaction created.

Request examples:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "currency": "USD",
  "supplementary_purchase_data": {
    "ondemand_service": {
      "currency": "USD",
      "average_amount": 3500,
      "minimum_amount": 100,
      "maximum_amount": 15000,
      "purchase_interval": "WEEK",
      "purchase_interval_frequency": 1

Payment Authorization: Core authorization operation for tokenization and authorizing payment transactions
Payment Transaction: The authorized payment resource created when using tokens
Customer Token: Technical resource reference for customer tokens
Klarna Network Session Token: Context token that enhances authorization approval rates
authorizePayment specification: Complete API reference for payment authorization and tokenization