For PartnersFor Acquiring Partners
Klarna

Customer token

A customer token represents a customer's saved Klarna payment method and their consent to be charged later. This page explains how to create, use, manage, and store customer tokens.
7 min read

Overview

A customer token is a unique identifier issued by Klarna that represents a customer's saved Klarna payment method and their consent to be charged later. Once you have a token, you can charge the customer without re-authorizing each transaction.
You create a customer token during a Klarna Payments checkout by setting the right intent and (for recurring use cases) including a subscription object on order_lines. Klarna mints the token at the end of the flow via purchaseTokenAPI and returns it as token_id. You then store that value against your customer record and pass it as the {customerToken} path parameter on every Customer Token API call — most importantly createOrderAPI to charge the token later.
Tokens do not expire. They remain valid until you, the customer, or Klarna explicitly cancels them.

When to use

Three use cases map cleanly to three token-creation intents:
Use caseintent at creationCharged via
Subscription — sign up once, charge renewals on your scheduletokenize (free trial, order_amount: 0) or buy_and_tokenize (paid signup with first month)Charge a subscription
On-demand — let the customer add Klarna to a wallet and pay with one click latertokenize (no upfront charge) or buy_and_tokenize (with first purchase)Charge an on-demand payment via SDK or via HPP
Mixed payments — customer pays a one-time item at checkout, you tokenize a Pay Now funding source for later add-ons or recurring chargesbuy_and_default_tokenizeMixed payments
Subscription tokens must include a subscription object on each recurring order_lines entry at creation. On-demand and mixed-payment tokens are created without that object — for mixed payments, the subscription object is added on follow-up charges as needed.
Integration requirement
Choose intent carefully — it cannot be changed after token creation. Subscription tokens (created with a subscription object on order_lines) are merchant-initiated and do not support step-up; on-demand tokens (created without a subscription object) are customer-initiated and may trigger step-up at Klarna's discretion. Using a token outside its intended pattern leads to authorization failures.

Create a customer token

Customer tokens are created at the end of a Klarna Payments checkout:
  1. 1.
    Step 1: Initiate a payment — call createCreditSession with the appropriate intent. For subscriptions, include the subscription object on each recurring order_line.
  2. 2.
    Step 2: Checkout — load the SDK and let the customer authorize.
  3. 3.
    Step 3: Create an order — required when the intent includes a purchase at signup (buy_and_tokenize, buy_and_default_tokenize).
  4. 4.
    Create the customer tokenAPI — POST to /payments/v1/authorizations/{authorizationToken}/customer-token to mint the token. Klarna returns the token_id — store this value, this is the customer token.
Sample purchaseToken request
JSON
1 2 3 4 5 6 7 8 9 10
POST /payments/v1/authorizations/{authorizationToken}/customer-token Authorization: Basic <credentials> Content-Type: application/json { "purchase_country": "US", "locale": "en-US", "billing_address": { "given_name": "Jane", "family_name": "Doe",
Sample purchaseToken success response
JSON
1 2 3 4 5 6 7 8 9 10
{ "billing_address": { "given_name": "Jane", "family_name": "Doe", "email": "jane.doe@example.com", "street_address": "123 Main Street", "postal_code": "90210", "city": "Beverly Hills", "region": "CA", "phone": "+1-555-0198",
Integration requirement
Inform the customer. You must tell the customer that you are creating a saved Klarna payment method and how you will charge it later. Include this in your terms and conditions, in the signup flow, and on the page where they confirm.

Charge a customer token

To charge an active token, call createOrder on the customer tokenAPI with the cart for the current charge:
TEXT
1
POST /customer-token/v1/tokens/{customerToken}/order
The behavior on charge depends on the use case the token was created for:
  • Subscription renewals are merchant-initiated. Klarna evaluates and either approves or fails the charge; step-up does not run. Failures are handled through your normal dunning process. See Charge a subscription.
  • On-demand charges are customer-initiated. Set step_up: SUPPORTED so Klarna can request additional customer interaction when needed. See Charge an on-demand payment via SDK or via HPP.
  • Follow-up charges after mixed checkout charge the tokenized Pay Now funding source. See Mixed payments.

Customer token lifecycle

stateDiagram-v2 [*] --> ACTIVE: purchaseToken ACTIVE --> ACTIVE: Successful charges ACTIVE --> CANCELLED: patchCustomerToken, customer or Klarna revokes CANCELLED --> [*]: Cannot be reactivated
StatusCan charge?What triggers it
ACTIVEYesSuccessful purchaseToken.
CANCELLEDNoExplicit cancellation by you (via patchCustomerToken), by the customer, or by Klarna. Final state — cannot be reactivated.
In addition to the documented status values, Klarna may temporarily refuse charges on an otherwise-active token — for example, because the underlying funding source has become unusable, or because Klarna has placed the token under a risk hold. These cases surface as error codes on createOrder (most commonly TOKEN_SUSPENDED or PAYMENT_METHOD_REJECTED) rather than as a distinct token status. Always check status before a customer-initiated charge so you can surface a useful message instead of a 4xx; for merchant-initiated renewals, treat any failure as a dunning event.

Customer token operations

The Customer Token API exposes three operations for reading, charging, and ending a token. Use readCustomerToken to inspect a token's current state and saved payment method, createOrder to charge it, and patchCustomerToken to cancel it.
OperationEndpointWhen to use
readCustomerTokenAPIGET /customer-token/v1/tokens/{customerToken}Confirm the token is ACTIVE before a charge; surface the saved payment method to the customer.
createOrderAPIPOST /customer-token/v1/tokens/{customerToken}/orderDrive a renewal, an on-demand charge, or a follow-up charge after mixed checkout. See Charge a customer token for the request pattern.
patchCustomerTokenAPIPATCH /customer-token/v1/tokens/{customerToken}/statusEnd the customer's saved payment method when they cancel a subscription or close their account. The only supported status transition is to CANCELLED, which is final — see Customer token lifecycle.
For full request and response schemas, see the Customer Token API referenceAPI.
readCustomerToken returns the current status of the token and the details of the saved payment method:
FieldDescription
statusCurrent token state. ACTIVE tokens can be charged. See Customer token lifecycle for the full set of states.
payment_method_typeThe payment method tokenized for the customer, for example INVOICE.
cardPresent when the token is backed by a card. Contains brand, expiry_date, and masked_number — use these to surface the saved payment method to the customer.
direct_debitPresent when the token is backed by a direct debit. Contains masked_number.
The token identifier itself is not returned by readCustomerToken — it is the token_id you received when the token was minted by purchaseToken. Pass it as the {customerToken} path parameter on every Customer Token API call.
Sample readCustomerToken response
JSON
1 2 3 4 5 6 7 8 9 10
{ "card": { "brand": "VISA", "expiry_date": "12/2030", "masked_number": "**1234" }, "direct_debit": { "masked_number": "**124" }, "payment_method_type": "INVOICE",
Sample patchCustomerToken request
JSON
1 2 3 4 5 6 7
PATCH /customer-token/v1/tokens/{customerToken}/status Authorization: Basic <credentials> Content-Type: application/json { "status": "CANCELLED" }

Storage and security

  • Store the token_id returned by purchaseToken against your customer record — do not store it client-side or in logs.
  • Map your internal customer/subscription id (used in merchant_reference1 on charges) to the token so you can reconcile settlement reports.
  • Implement access controls limiting which services can read the token.
  • Audit-log every read and charge using the token.
  • Treat the token as long-lived but not permanent — handle CANCELLED gracefully (drop the subscription, prompt re-tokenization on next interaction).
Jump to section...