Payment Tokenization for Server-side integration

This guide covers how to create a customer token with Klarna using a server-side integration when the customer is present to provide consent. As an Acquiring Partner, the backend collects payment context from a Partner, calls the Payment Authorize API with a tokenization request, handles the STEP_UP_REQUIRED initial response, manages the step-up flow, and securely stores the token for future use.

For conceptual understanding of tokenization, token scopes, use cases, and authorization patterns, see the Payment Tokenization resource.

Before starting tokenization, ensure the following:

• A Partner Account onboarded with Klarna
• An API Key associated with your Partner Account
• Backend capability to receive and process Klarna webhooks
• Partner-facing APIs capable of forwarding redirect URLs and Klarna network data without modification
• A checkout or account setup flow where the customer is present and able to complete step-up interactions
• Clear customer consent for saving the payment method and future charges according to token scope

Once the customer initiates tokenization (for example, during subscription signup or account setup):

1. 1.
   The Partner initiates tokenization through the Acquiring Partner
2. 2.
   The Acquiring Partner forwards the tokenization request to Klarna by calling the authorizePayment
3. 3.
   Klarna returns STEP_UP_REQUIRED because customer consent is always required for tokenization
4. 4.
   The Acquiring Partner returns the payment_request_url to the Partner
5. 5.
   The customer completes the Klarna Purchase Journey to provide consent
6. 6.
   Klarna sends a webhook upon step-up completion. The payload differs by scenario:

   • 6.1.
     Tokenization only: The webhook contains the customer_token. No further API call is needed. The Acquiring Partner securely stores the customer token issued by Klarna, maps it to an internal identifier, and returns that internal customer token identifier to the Partner.
   • 6.2.
     Tokenization combined with authorization: The webhook contains both the customer_token and a klarna_network_session_token. The Acquiring Partner calls the Payment Authorize API again with the klarna_network_session_token to complete the initial Payment Authorization. Klarna returns the final result (APPROVED or DECLINED). The Acquiring Partner then securely stores the customer token issued by Klarna, maps it to an internal identifier, and returns the internal customer token identifier and payment result to the Partner.

Determine which tokenization scenario applies to the use case:

• Tokenization only: Save a payment method without an immediate charge
• Tokenization combined with authorization: Create a token while processing the first Payment Authorization

The appropriate request structure for each scenario is shown in Step 3. See the Payment Tokenization resource for detailed scenario descriptions and use cases.

Collect the necessary information from the Partner to request a customer token. The required fields depend on the tokenization scenario.

Requirements

• Use exact parameter names klarna_network_session_token and klarna_network_data in the Partner-facing API to ensure Partners can easily identify and use them.
• Forward all parameters unmodified to Klarna.
• Parameter validation must not be more restrictive than Klarna's authorizePayment.
• Support all printable UTF-8 characters.
• Supplementary purchase data handling:

  • Map your existing Tokenization settings to Klarna customer token scopes.
  • Map your existing Partner-facing fields (line items, customer billing address, shipping, order reference) into supplementary_purchase_data when calling Klarna.
  • Don't add new Partner-facing fields "just for Klarna" if you already have equivalent fields in your existing schema. Avoid forcing Partners to submit the same data twice using parallel structures

Call the Payment Authorize API with the appropriate configuration based on the tokenization scenario.

POST /v2/accounts/{partner_account_id}/payment/authorize
Content-Type: application/json
Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]

{
  "currency": "USD",
  "request_customer_token": {
    "scopes": ["payment:customer_not_present"],
    "customer_token_reference": "subscription-user-12345"
  },
  "supplementary_purchase_data": {
    "subscriptions": [{

The initial Payment Authorize API call always returns STEP_UP_REQUIRED for tokenization requests.

When requesting tokenization through the authorizePayment, Klarna returns response objects that correspond to the elements included in the request. The response contains a customer_token_response, and if an initial Payment Authorization was also requested, a payment_transaction_response will be included as well.

What you receive:

• customer_token_response.result: STEP_UP_REQUIRED
• payment_request object containing:

  • payment_request_id: Unique identifier for the step-up request
  • payment_request_url: URL to launch the Klarna Purchase Journey

{
  "customer_token_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    "payment_request_id": "krn:payment:us1:request:bcb5ca7d-[...]",
    "payment_request_reference": "acquiring-partner-request-reference-1234",
    "expires_at": "2026-04-01T19:53:15.738Z",
    "created_at": "2026-04-01T16:53:15.738Z",
    "updated_at": "2026-04-01T16:53:15.738Z",
    "state": "SUBMITTED",
    "supplementary_purchase_data": { },

Acquiring Partners must include return URLs in the step_up_config when calling authorizePayment to enable the step-up scenario.

These URLs, set inside the customer_interaction_config object, tell Klarna where to redirect the customer after they complete or stop the Purchase Journey.

If the Klarna Purchase Journey is launched in a web environment, Klarna redirects the customer to the return_url after they finish — whether they complete or stop the flow. This can be a URL managed by the Acquiring Partner (which handles redirection logic) or one collected directly from the Partner.

On mobile, the customer may be redirected to a third-party app (such as a bank app) or the Klarna app during the Purchase Journey. The app_return_url brings the customer back to the Partner's mobile app when this happens.

Partners must register a URL scheme (e.g., yourapp://klarna) or a universal link that resumes the payment flow. Klarna invokes this URL after the customer completes a native app-based step, such as biometric authentication or Klarna app login. Partners are expected to resume the mobile app in its last state without applying state changes or deep link navigations.

The return_url and app_return_url are not mutually exclusive. Depending on the device and environment, either or both may be triggered:

Map the Klarna authorization result to the Partner-facing API response according to the authorization outcome. The response may include a payment_request_url and/or a klarna_network_response_data parameter.

Requirements

• payment_request_url MUST be returned directly to the Partner in an existing field and MUST NOT be wrapped or hidden behind Acquiring Partner-managed redirects.
• Use exact parameter name klarna_network_response_data in the Partner-facing API to ensure Partners can easily identify and use the parameter. Treat this value as an opaque string; do not validate or infer its structure.

Below are examples of how Acquiring Partners can return the klarna_network_response_data parameter in their Partner-facing APIs depending on the authorization outcome.

{
  "payment_id": "pr_27234RBQD9NAKD032BN",
  "amount": 17800,
  "currency": "USD",
  "status": "open",
  "url": "https://pay.test.klarna.com/na/requests/aeba9923-[...]/start",
  "additional_data": {
    "klarna_network_response_data": "{\"content_type\":\"vnd.klarna.network-data.v2+json\",\"content\":{\"operation\":\"payment_request\",\"response\":{\"result\":\"STEP_UP_REQUIRED\",\"payment_request\":{\"payment_request_id\":\"krn:payment:us1:request:10b51071-[...]\",\"payment_request_url\":\"https://pay.test.klarna.com/na/requests/aeba9923-[...]/start\"}}}}"
  }
}

Acquiring Partners should expose Klarna's payment_request_url directly to Partners rather than routing through an Acquiring Partner-owned URL.

Using an intermediate redirect under the Acquiring Partner's domain causes the following issues:

When step-up is triggered, authorizePayment returns a STEP_UP_REQUIRED result along with a Payment Request containing the payment_request_url and klarna_network_response_data which the Partner needs in order to launch the Klarna Purchase Journey, either through a redirect or a pop-up experience.

The Purchase Journey allows the customer to authenticate with Klarna (via login, one-time passwords, etc.), choose a payment method, and accept the payment.

Phone collection in the Klarna Purchase Journey

When the payment.request.state-change.completed webhook arrives, tokenization is complete — the customer_token is available in the payload regardless of scenario. For the Tokenization only scenario, no further API call is needed: store the token and return the result to the Partner. For the Tokenization combined with authorization scenario, proceed to Step 6 to finalize the initial Payment Authorization.

To retrieve the required token(s), Klarna provides multiple integration methods. Subscribing to Klarna webhook events is required and may be combined with additional methods to improve resilience.

Using webhooks ensures reliable completion handling, particularly when the customer closes the browser before returning, network interruptions occur during redirects, or post-processing is required before notifying the customer.

Subscribe to the payment.request.state-change.completed webhook event using the Klarna webhook guidelines. Klarna sends this event when the Payment Request reaches the COMPLETED state.

This event indicates that the customer has finished the step-up interaction and that the Acquiring Partner can proceed with finalizing the authorization.

{
  "metadata": {
    "event_type": "payment.request.state-change.completed",
    "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
    "event_version": "v2",
    "occurred_at": "2026-04-01T16:55:17Z",
    "correlation_id": "2d1557e8-17c3-466c-924a-bbc3e91c2a02",
    "subject_account_id": "krn:partner:global:account:test:HGBY07TR",
    "recipient_account_id": "krn:partner:global:account:test:LWT2XJSE",
    "product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-[...]",
    "webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-[...]",
    "live": false

As an alternative method, retrieve the Klarna token(s) by calling the readPaymentRequest.

Once the Payment Request reaches the COMPLETED state, the token(s) are available in the state_context object of the Payment Request.

{
  "payment_request_id": "krn:payment:us1:request:bcb5ca7d-[...]",
  "state": "COMPLETED",
  "previous_state": "IN_PROGRESS",
  "state_context": {
    "klarna_customer": {
      "customer_token": "krn:partner:us1:test:identity:customer-token:Rt4iBjqKBM[...]",
      "customer_token_reference": "subscription-user-12345"
    }
  },
  "expires_at": "2026-04-01T19:53:15.738Z",
  "created_at": "2026-04-01T16:53:15.738Z",

This step applies only to the Tokenization combined with authorization scenario. Tokenization is already complete after step-up — the customer_token is delivered in the webhook payload.

To process the initial Payment Authorization, call the authorizePayment using:

• The newly obtained klarna_network_session_token in the Klarna-Network-Session-Token request header
• The same payment context (amount, currency, supplementary_purchase_data, klarna_network_data) used in the initial request
• The same payment_transaction_reference to link the requests

Finalization request example

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/authorize \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJFU[...]' \
  -d '{
        "currency": "USD",
        "request_payment_transaction": {
          "amount": 999,
          "payment_option_id": "S0xBUk5BXzE3NzI3MjQ5MTQzMjk=",
          "payment_transaction_reference": "subscription-first-payment-001"
        },
        "request_customer_token": {

Klarna evaluates the Payment Request and returns one of the following results for payment_transaction_response:

{
  "payment_transaction_response": {
    "result": "APPROVED",
    "payment_transaction": {
      "payment_transaction_id": "krn:payment:us1:transaction:5cb3e0e5-a6f0-[...]",
      "amount": 999,
      "currency": "USD",
      "payment_pricing": { "..." : "..." },
      "payment_funding": {
        "type": "GUARANTEED",
        "state": "FUNDED"
      }

Map the Klarna authorization result to the Partner-facing API response and return the klarna_network_response_data.

Requirements

• Treat this value as an opaque string; do not validate or infer its structure.
• Use exact parameter name klarna_network_response_data in the Partner-facing API to ensure Partners can easily identify and use the parameter.
• All returned data MUST be forwarded without modification.

Below is an example of how Acquiring Partners can return the klarna_network_response_data parameter in their Partner-facing APIs.

{
  "payment_id": "pr_27234RBQD9NAKD032BN",
  "amount": 999,
  "currency": "USD",
  "status": "completed",
  "additional_data": {
    "klarna_network_response_data": "{\"content_type\":\"vnd.klarna.network-data.v2+json\",\"content\":{\"operation\":\"payment_request\",\"response\":{\"result\":\"APPROVED\",\"payment_transaction\":{\"payment_transaction_id\":\"krn:payment:us1:transaction:5cb3e0e5-a6f0-[...]\"}}}}"
  }
}

• Payment Tokenization resource — Understand token scopes, authorization patterns, and lifecycle management
• Authorize Partner-initiated transactions — Use the stored customer token to charge customers when they are not present
• Manage payment transactions — Capture, refund, or cancel authorized payments