Create a Klarna Customer Token (Partner orchestrated)

Save a customer's Klarna payment method by creating a Klarna Customer Token yourself — adding request_customer_token to Klarna's Create Payment Request call — so you can charge it later for subscriptions or returning-customer purchases.

This guide explains how to save a customer's Klarna payment method — creating a Klarna Customer Token — where you orchestrate the request: you call Klarna's Create Payment Request yourself and add the request_customer_token object. Klarna issues the token and returns it to you on completion. A token is created once, with the customer present and consenting, and rides on top of a payment flow (with or without an initial purchase).

Prefer Solidgate to request the token? If you let Solidgate orchestrate Klarna, you can instead create the token through Solidgate's subscription routine — there is nothing Klarna-specific for you to send. See Create a Klarna Customer Token (Solidgate orchestrated). To compare all tokenized flows, see the Tokenized payments overview.

Prerequisites

Before you integrate, check that you meet the following prerequisites:

1.
Ensure that you have Klarna enabled with Solidgate.
2.
Decide which scope the token needs (see Configure the customer token scope):
- 2.1.
  payment:customer_present — for returning-customer, customer-initiated one-click charges.
- 2.2.
  payment:customer_not_present — for subscriptions and on-demand charges that run without the customer.
3.
Confirm you have access to the Klarna Partner Portal with an API key able to call the Klarna Payment Request API.
4.
Confirm that you have registered webhooks for payment.request.state-change.completed events following the Webhooks guidelines.
5.
Add Terms and Conditions covering tokenization / saved payment methods.

Integration overview

You present Klarna in your own checkout (Web SDK or Presentation API) and call Klarna's Create Payment Request with the request_customer_token object. Klarna issues the token and returns it through the completion webhook. Use this option when you already drive the Klarna payment request yourself — token creation is just an extra field on a call you already make.

For the full presentation setup, follow the build-the-checkout guide that matches how you render Klarna, and add request_customer_token to the request:

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna participant AP as Solidgate P->>K: Create payment request<br/>POST payment/requests Note over P,K: request_customer_token alt STEP_UP_REQUIRED K-->>P: Return payment_request_url P->>P: Launch Klarna purchase journey C->>K: Complete Klarna purchase journey end K->>P: Payment request completed event<br/>(webhook) Note over K,P: Klarna customer_token<br/>klarna_network_session_token P->>P: Store Klarna customer_token alt If there is a payment to complete P->>AP: Confirm payment Note over P,AP: klarna_network_session_token AP-->>P: Order completed notification P-->>C: Display confirmation message end

Integration details

Add `request_customer_token` to the Create Payment Request

When the customer consents, add the request_customer_token object to your Klarna Create Payment Request. You can create a token only or a token together with an initial purchase (by also including the payment transaction):

Field	Presence	Description
`request_customer_token.scopes`	required	A single-item array with the token scope — `payment:customer_present` or `payment:customer_not_present`. See Configure the customer token scope.
`request_customer_token.customer_token_reference`	optional	Your own reference for the token, returned on the completion event for reconciliation.
`currency`	required	Currency in ISO 4217 format.
`request_payment_transaction`	optional	Include only when you also take an initial purchase alongside token creation. Omit for a token-only request.

BASH

1 2 3 4 5 6 7 8 9 10

curl -X POST https://api-global.test.klarna.com/v2/payment/requests \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "USD",
    "request_customer_token": {
      "scopes": ["payment:customer_not_present"],
      "customer_token_reference": "customer-123-token"
    }
  }'

Configure the customer token scope

The token scope defines what the token can be used for later. Set it through request_customer_token.scopes.

Scope	Enables	Use it for
`payment:customer_present`	Tokenization where subsequent charges may go through immediately or require a step-up depending on risk.	Returning-customer, customer-initiated one-click charges at checkout.
`payment:customer_not_present`	Tokenization for charges that run without the customer present.	Partner-initiated charges — subscriptions and on-demand.

Retrieve the issued token

Klarna issues the Klarna Customer Token once the payment request reaches COMPLETED. Retrieve it by subscribing to the payment.request.state-change.completed webhook (required); the token is available under state_context.klarna_customer.customer_token. You may additionally call the Read Payment Request API API

for resilience. Store the token against the customer.

In the Partner-orchestrated flow you receive the Klarna Customer Token — the only charge credential for Partner-orchestrated charges. The Solidgate token is returned only when Solidgate creates the token; see Create a Klarna Customer Token (Solidgate orchestrated).

Charge the token later

Store the Klarna Customer Token against the customer. To charge the token later, continue to the tokenized payments overview and pick the charge flow that matches your scenario.

For token lifetime, scopes, and management (revoking or reading a token), see the Customer Token resource. Token management operations are out of scope for this guide.

Create a Klarna Customer Token (Solidgate orchestrated)

Tokenized payments overview

1. General

Build checkout form with Klarna WebSDK

API & SDK references

Read the state of a Payment Request