Payment Tokenization for Hosted Checkout integration

Integrate Klarna's Payment Tokenization through hosted checkout. This guide shows how to request a customer token using the Klarna Web SDK and the Payment Authorize API, handle tokenization outcomes including step-up flows managed by the SDK, and securely store tokens for future transactions.

Overview

This guide covers how to create a customer token with Klarna using a hosted checkout integration when the customer is present to provide consent. As an Acquiring Partner, the frontend uses the Klarna Web SDK to present payment methods and collect the customer's selection. The backend then calls the authorizePayment API

with a tokenization request, handles the STEP_UP_REQUIRED response (which the SDK manages), and securely stores the resulting token for future use.

Where this fits in the integration flow:

1.
Payment Presentation — The frontend presents Klarna payment methods and collects the customer's selection (previous guide)
2.
Create a customer token (hosted checkout) — The backend receives the frontend request and calls the authorizePayment with tokenization parameters (this guide)
3.
Payment Tokenization resource — Conceptual overview of tokenization, token scopes, and authorization patterns

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

Prerequisites

Before starting tokenization through hosted checkout, ensure the following:

A working Payment Presentation implementation — the frontend can present Klarna payment methods and collect the customer's selection
A Partner Account onboarded with Klarna
An API Key and a Client ID associated with your Partner Account
Registered domains for loading the Klarna Web SDK
Backend capability to receive and process Klarna webhooks
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

Integration overview

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

1.
The Acquiring Partner presents Klarna payment methods using the Klarna Web SDK with the appropriate intent (for example, SUBSCRIBE, SIGNUP, or ADD_TO_WALLET)
2.
The customer selects a Klarna payment method and clicks the payment button
3.
The Klarna Web SDK triggers the initiate callback, providing the klarnaNetworkSessionToken and paymentOptionId
4.
The Acquiring Partner calls the authorizePayment with request_customer_token and step_up_config
5.
Klarna returns STEP_UP_REQUIRED because customer consent is always required for tokenization
6.
The Acquiring Partner returns the payment_request_id to the Klarna Web SDK, which launches the Klarna Purchase Journey for the customer to provide consent
7.
Klarna sends a webhook upon step-up completion. The payload differs by scenario:
- 7.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.
- 7.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 Authorization result to the Partner.

sequenceDiagram autonumber participant Customer participant APFrontend as Acquiring Partner (Frontend) participant APBackend as Acquiring Partner (Backend) participant WebSDK as Klarna Web SDK participant Klarna APFrontend->>WebSDK: Initialize Web SDK Note over APFrontend,WebSDK: clientId, partnerAccountId, klarnaNetworkSessionToken APFrontend->>WebSDK: Request payment presentation Note over APFrontend,WebSDK: amount, currency, intent WebSDK->>APFrontend: Return payment methods + instructions Customer->>APFrontend: Select Klarna payment method Customer->>WebSDK: Click payment button WebSDK->>APFrontend: Trigger initiate callback Note over APFrontend,WebSDK: klarnaNetworkSessionToken, paymentOptionId APFrontend->>APBackend: Request tokenization Note over APFrontend,APBackend: klarnaNetworkSessionToken, paymentOptionId APBackend->>Klarna: Call Payment Authorize API Note over APBackend,Klarna: request_customer_token + step_up_config Klarna->>APBackend: STEP_UP_REQUIRED Note over APBackend,Klarna: payment_request_id APBackend->>APFrontend: Return STEP_UP_REQUIRED + payment_request_url APFrontend->>WebSDK: Return paymentRequestUrl WebSDK->>Customer: Launch Klarna Purchase Journey Customer->>Klarna: Customer provides consent alt Tokenization only Klarna-->>APBackend: Webhook: payment request completed Note over APBackend,Klarna: Payload contains customer_token, no further API call needed Note over APBackend: Store customer_token securely, map to internal identifier APBackend->>APFrontend: Return success APFrontend->>Customer: Token saved successfully else Tokenization combined with authorization Klarna-->>APBackend: Webhook: payment request completed Note over APBackend,Klarna: Payload contains customer_token + klarna_network_session_token APBackend->>Klarna: Complete initial Payment Authorization Note over APBackend,Klarna: Call Payment Authorize API with Klarna Network Session Token Klarna->>APBackend: Payment Authorization result (APPROVED / DECLINED) Note over APBackend: Store customer_token securely, map to internal identifier APBackend->>APFrontend: Return result APFrontend->>Customer: Token saved, Payment Authorization completed end

Integration details

Step 1: Determine tokenization scenario

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 4. See the Payment Tokenization resource for detailed scenario descriptions and use cases.

Step 2: Collect payment context from the Partner

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

Update the Partner-facing API to collect the following fields for tokenization without an initial Payment Authorization:

Parameter	Required (Acquiring Partner)	Required (Partner)	Description
`currency`	Yes	Yes	Currency in ISO 4217 format for future transactions using the token.
`scopes`	Yes	Yes	Token scope defining the authorization pattern: `payment:customer_present` or `payment:customer_not_present`. See Token Scopes for guidance.
`supplementary_purchase_data`	Yes	Recommended	Additional details about the tokenization use case. Include this data to improve fraud assessment and customer communication.
`supplementary_purchase_data.subscriptions`	Yes	Conditional	Subscription details including subscription reference, billing plans, and free trial status. Mandatory when the token will be used for subscription charges, i.e. when token scope = `payment:customer_not_present`.
`supplementary_purchase_data.ondemand_service`	Yes	Conditional	On-demand service details describing the service the token will be used for. Mandatory when the token will be used for on-demand charges, i.e. when token scope = `payment:customer_present`.
`supplementary_purchase_data.customer`	Yes	Recommended	Information about the customer based on their previous interactions with the Partner. Used by Klarna to simplify sign-up and for fraud assessment.
`klarna_network_session_token`	Yes	Conditional	Encodes Klarna Network Session Token context (prequalification, sign-in state, or approval). Optional on the initial tokenization request; required for finalization after step-up completion.
`klarna_network_data`	Yes	Recommended	Additional data to enable custom features or data exchange supported by the Partner. Klarna accepts this passthrough field in a structured JSON format and forwards it to relevant systems for interoperability. Treat this value as an opaque string; do not validate or infer its structure.
`return_url`	Yes	Recommended	URL to redirect the customer after completing the step-up flow. Recommended for web flows.
`app_return_url`	Yes	Recommended	Mobile application return URL (app scheme with no action deeplink). The customer will be redirected to this URL after third-party redirects. Recommended for mobile app flows.

Token scope selection is critical

The token scope must match your intended authorization pattern. See Token Scopes for detailed guidance on choosing between payment:customer_present and payment:customer_not_present.

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

Do	Don't
Map existing line items into `supplementary_purchase_data.line_items`.	Introduce a parallel line-item structure such as `klarna_line_items`.
Map existing customer details into `supplementary_purchase_data.customer`.	Duplicate customer fields you already collect from Partners.
Map existing shipping data into `supplementary_purchase_data.shipping`.	Add a separate shipping object "just for Klarna".
Map your existing purchase reference into `supplementary_purchase_data.purchase_reference`.	Force Partners to submit the same purchase reference twice.

Supplementary purchase data scenarios

Acquiring Partners may receive supplementary purchase data (including line items, L2/L3 data for Card Network optimization, and transaction context) in one or both of the following ways:

Embedded in klarna_network_data: Forward as received without parsing or mapping
Provided as individual API fields: Map to the supplementary_purchase_data object when calling authorizePayment

flowchart LR Partner[Partner]:::tertiaryEntity LineItems[Line items,\nL2/L3 data,\netc]:::secondaryEntity KlarnaNetLeft[Klarna Network Data]:::secondaryEntity AP[Acquiring Partner's API]:::primaryEntity Supplementary[Supplementary\nPurchase Data]:::secondaryEntity KlarnaNetRight[Klarna Network Data]:::secondaryEntity Auth[Payment Authorization]:::primaryEntity %% Main flows Partner --> LineItems --> AP --> Supplementary --> Auth Partner --> KlarnaNetLeft --> AP --> KlarnaNetRight --> Auth

Step 3: Present Klarna payment methods using the Web SDK

Build the payment form using the Klarna Web SDK. This step follows the same process described in the Payment Presentation guide, with the following tokenization-specific considerations:

Configure the appropriate intent:

The intent parameter in the payment presentation request determines how Klarna presents payment methods. For tokenization scenarios, use the intent that matches the use case:

Intent	Use Case	Description
`SUBSCRIBE`	Subscriptions	Recurring charges at regular intervals. The customer saves a payment method for future automatic charges.
`SIGNUP`	Free trials, account setup	Save a payment method without an immediate charge. Typically used for free trial signups.
`ADD_TO_WALLET`	Wallet linking	Save a payment method to a digital wallet or account for future customer-initiated purchases.
`PAY`	Tokenization combined with authorization	Customer completes an initial purchase while also saving a payment method for future use.

Payment presentation request example:

JAVASCRIPT

1 2 3 4 5 6

const paymentPresentation = await klarna.Payment.presentation({
  amount: 999,        // omit for tokenization-only scenarios without an initial charge
  currency: "USD",
  locale: "en-US",
  intent: "SUBSCRIBE" // use the intent matching the tokenization use case
});

For the complete Web SDK initialization and payment form implementation, see the Payment Presentation guide.

Step 4: Implement the backend tokenization endpoint

The Acquiring Partner backend receives the authorization request from the frontend after the customer clicks the Klarna payment button. The initiate callback provides two parameters from the Klarna Web SDK:

klarnaNetworkSessionToken — the Klarna session context
paymentOptionId — the payment method the customer selected

Call the authorizePayment API

with the appropriate configuration based on the tokenization scenario.

When saving a payment method without an immediate charge:

Include request_customer_token with desired scopes
Do NOT include request_payment_transaction or amount in the request
Provide complete supplementary_purchase_data describing the intended use case
Configure step_up_config with HANDOVER to allow customer consent collection

Request example

JSON

1 2 3 4 5 6 7 8 9 10

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"
  },

API parameters

Optionally set step_up_config.customer_interaction_config.interaction_expiry to override the default 3-hour Payment Request lifetime. See Custom Payment Request expiry.

Step 5: Handle the initial response

The initial authorizePayment API

call always returns STEP_UP_REQUIRED for tokenization requests.

When requesting tokenization through the authorizePayment API

, 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.

Result	Description	Next steps
`STEP_UP_REQUIRED`	Tokenization always requires customer consent. Klarna creates a `payment_request` containing the `payment_request_id`.	Return the `payment_request_id` to the frontend. The Klarna Web SDK launches the Klarna Purchase Journey for the customer to provide consent. Customer interaction is required to complete tokenization.

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

Sample payload

JSON

1 2 3 4 5 6 7 8 9 10

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

Complete backend endpoint implementation

The backend processes the result and returns the payment_request_id to the frontend so the Klarna Web SDK can launch the Klarna Purchase Journey.

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

app.post('/api/authorize-tokenization', async (req, res) => {
  try {
    const { klarnaNetworkSessionToken, paymentOptionId } = req.body;

    const klarnaResponse = await callKlarnaAuthorizeAPI({
      klarnaNetworkSessionToken,
      paymentOptionId,
      currency: 'USD',
      requestCustomerToken: {
        scopes: ['payment:customer_not_present'],

Step 6: Implement `initiate` callback for tokenization

Configure the payment button's initiate callback to call the backend tokenization endpoint and return the paymentRequestUrl to the Klarna Web SDK.

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

async function initiateKlarnaTokenization(klarnaNetworkSessionToken, paymentOptionId) {
  try {
    const response = await fetch('/api/authorize-tokenization', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ klarnaNetworkSessionToken, paymentOptionId })
    });

    if (!response.ok) throw new Error('Network or server error');

What happens next:

When the frontend receives STEP_UP_REQUIRED with the paymentRequestUrl, the Klarna Web SDK automatically launches the Klarna Purchase Journey (see Step 5).

Return URLs for step-up scenario

Acquiring Partners must include return URLs in the step_up_config when calling authorizePayment API

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 Klarna Purchase Journey.

return_url

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.

app_return_url

On mobile, the customer may be redirected to a third-party app (such as a bank app) or the Klarna app during the Klarna 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.

Interaction scenarios

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

Scenario	Description
Pure web flow	The customer starts the Klarna Purchase Journey in a desktop browser. After completing the flow, Klarna redirects them to `return_url`.
App-to-app flow	The Partner's native app opens the Klarna Purchase Journey using a universal link. If the Klarna app is installed, the customer goes directly into it. After completion, Klarna redirects them to `app_return_url`.
WebView flow with app handover	The Partner's native app starts the Klarna Purchase Journey in a System WebView. If the customer must authenticate via an external banking app, `app_return_url` returns them to the Partner's app mid-flow. They then resume in the WebView and, on completion, are redirected to `return_url`.

If the Acquiring Partner already collects a suitable return_url or app_return_url from the Partner, do not request a second one — this would increase the minimum integration requirements for Klarna to work.

Step 7: Handle step-up scenario

A step-up occurs when Klarna requires additional customer interaction to complete a Payment Authorization — for example, when the customer needs to log in, authenticate, or select a payment method.

When step-up is triggered, authorizePayment API

returns a STEP_UP_REQUIRED result along with a Payment Request containing the payment_request_id which is required for the Klarna Web SDK to launch the Klarna Purchase Journey.

Configure `initiationMode`

The Klarna web SDK launches the Klarna Purchase Journey through the initiate function on the Klarna Payment button. The function returns a promise that resolves to an object containing the paymentRequestUrl:

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

const buttonConfig = {
  initiate: () => {
    // Call to Payment Authorize API returns STEP_UP_REQUIRED
    return { paymentRequestUrl: "https://pay.test.klarna.com/na/requests/2cb914b0-[...]/start" };
  },
  initiationMode: "DEVICE_BEST", // "DEVICE_BEST" (default) | "ON_PAGE" | "REDIRECT"
};

// Render and mount the button with the assigned configuration
paymentPresentation.paymentButton

The initiationMode parameter controls how the Klarna Purchase Journey is launched when your backend returns STEP_UP_REQUIRED. Configure this in your frontend payment button.

initiationMode	Description
`DEVICE_BEST`	Automatically selects the best way to launch the Klarna Purchase Journey depending on the device - this is the default and recommended value: Mobile: Always redirect Desktop: pop-up if possible, fallback to redirect Native webview: Always redirect Note: for this `initiationMode`, a `return_url` is required in the `customer_interaction_config` object when calling the Payment Authorize API.
`ON_PAGE`	The Klarna Purchase Journey is triggered on the same page. The customer never leaves the page. The Klarna Purchase Journey opens in a pop-up if possible and fallback to fullscreen iframe if necessary.
`REDIRECT`	The customer will be redirected to the Klarna Purchase Journey. Note: for this `initiationMode`, a `return_url` is required in the `customer_interaction_config` object when calling the Payment Authorize API.

When does this matter? The initiationMode parameter only affects the customer experience when your backend returns STEP_UP_REQUIRED. If your backend returns APPROVED, the customer proceeds directly to the confirmation page without launching the Klarna Purchase Journey.

For complete frontend implementation details, see the Payment Presentation guide.

Launching the Klarna Purchase Journey

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

Handle customer return after the Klarna Purchase Journey

Klarna redirects the customer to the return_url in customer_interaction_config, except when a pop-up experience is used and the customer stops the flow.

On completion, Klarna issues a klarna_network_session_token to the Acquiring Partner to finalize the payment.

Web SDK events

Acquiring Partners can register event handlers on the KlarnaPayment SDK interface to track Klarna Purchase Journey stages:

Event handler	Purpose
`on("complete", callback)`	Triggered when the customer accepts the purchase. During a redirect flow, the handler fires once the success page loads. Pending updates are triggered even if the handler is registered after the page loads, removing the need for polling.
`on("abort", callback)`	Triggered when the customer stops the Klarna Purchase Journey.
`on("error", callback)`	Triggered when an error occurs during the Payment Request lifecycle. When defined, all errors are emitted to this handler instead of being thrown.

Event handlers provide access to the following paymentRequest properties:

Property	Definition
`paymentRequestId`	Unique identifier of the Payment Request.
`state`	Current state of the Payment Request.
`previousState`	Previous state of the Payment Request.
`stateReason`	The reason the Payment Request is in its current state.
`stateContext`	State-specific context. The `klarna_network_session_token` is stored here when the Payment Request reaches the `COMPLETED` state.

JAVASCRIPT

1 2 3 4 5 6 7

klarna.Payment.on("complete", (paymentRequest) => {
  console.log("Payment request completed");
  // By default, Klarna will redirect to the submitted return_url upon completion.
  // Return false if you want to prevent the redirection to the success page.
  return true
});

Use Web SDK events to enhance the customer experience — for example, displaying clear error messages when a purchase is stopped, or disabling page interactions while payment authorization is in progress.

Never use SDK events to trigger payment authorization. Always rely on Klarna webhooks to receive the klarna_network_session_tokenand finalize the payment after the customer approves the purchase.

Step 8: Monitor step-up completion

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 8 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.

Sample payload

JSON

1 2 3 4 5 6 7 8 9 10

{
  "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-[...]",

Method: Read the Payment Request (optional/fallback)

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

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

Sample payload

JSON

1 2 3 4 5 6 7 8 9 10

{
  "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"
    }
  },

Step 9: Complete the initial Payment Authorization

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 API

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

SHELL

1 2 3 4 5 6 7 8 9 10

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"

If the klarna_network_session_token has expired (1-hour validity) or the payment context doesn't match the initial request, the finalization call returns DECLINED.

Klarna evaluates the payment request and returns one of the following results for payment_transaction_response:

Result	Description	Next steps
`APPROVED`	The Payment Authorization succeeded and a `payment_transaction` was created. The `customer_token` is returned in `customer_token_response` and is ready for future use.	Store the `customer_token` securely and return the Payment Authorization result to the Partner.
`DECLINED`	The Payment Authorization failed. No `payment_transaction` was created. The `customer_token` is still returned in `customer_token_response` and is valid for future use.	Return the failure result to the Partner. Store the `customer_token` securely — it remains valid despite the Payment Authorization failure.

Sample payload

JSON

1 2 3 4 5 6 7 8 9 10

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

Step 10: Return final authorization outcomes to the Partner

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.

JSON

1 2 3 4 5 6 7 8 9

{
  "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-[...]\"}}}}"
  }
}

Next steps

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