Monitor the payment request state

Ensure successful transactions with Klarna’s Hosted Checkout by monitoring Payment request states, retrieving payment tokens, and leveraging webhooks for real-time updates.

Token usage

Klarna now uses klarna_network_session_token as the required token to finalize a payment.

Existing integrations: Klarna previously relied on payment_token, which will continue to be returned in the current version for backward compatibility. Please note that payment_token will be removed in future versions, so if your integration currently uses it, plan to migrate to klarna_network_session_token.
New integrations: Acquiring Partners should ignore payment_token and use klarna_network_session_token exclusively.

Integration overview

This guide outlines how to monitor the Klarna Payment Request as part of the step up scenario. On a high level:

Understand payment request lifecycle in order to handle COMPLETED, CANCELED, DECLINED and EXPIRED states properly.
Monitor and retrieve the klarna_network_session_token by using one or a combination of the following methods:
- Subscribing to payment.request.state-change.* webhook events (required)
- Reading the payment request
- Optionally leverage available dynamic placeholders when making use of an internal return_url
Proactively cancel payment requests which have not resulted in successful transactions.

Integration details

Payment request lifecycle

During the checkout process, the Payment Request will transition to various states. Find below an overview of the possible payment request states together with a transition diagram:

State	Description	Next action
`SUBMITTED`	Initial state. Payment requests can be used with the SDK to launch the Klarna Purchase Journey	The Acquiring Partner uses the Klarna SDK to trigger the Klarna purchase journey as described in the section Handle Step-up scenario.
`IN_PROGRESS`	The customer is actively in Klarna’s purchase journey.	Listen for state changes via webhook.
`COMPLETED`	Customer completed the flow, pending final authorization.	Use `payment_token` to create the transaction
`EXPIRED`	Payment request expired (t≥3h).	Final state. No action.
`CANCELED`	Payment request canceled by Acquiring Partner before authorization.	Final state. No action.
`DECLINED`	Customer rejected the payment request or no payment methods are available during authorization.	Final state. No action.

State transition diagram

flowchart LR Start((Start)):::teritiaryEntity --> SUBMITTED1[SUBMITTED]:::secondaryEntity %% -------------------------------------------------- %% Submission Handling %% -------------------------------------------------- subgraph Submission_Handling [Submission handling] direction TB SUBMITTED1 --> Decision1{ }:::teritiaryEntity Decision1 -->|Customer enters Purchase Journey| IN_PROGRESS[IN_PROGRESS]:::secondaryEntity Decision1 -->|Acquiring Partner cancels request| CANCELED1[CANCELED]:::primaryEntity Decision1 -->|Acquiring Partner updates request| SUBMITTED2[SUBMITTED]:::secondaryEntity Decision1 -->|"Request expired (≥ 3h)"| EXPIRED1[EXPIRED]:::primaryEntity end %% -------------------------------------------------- %% Purchase Journey Outcome %% -------------------------------------------------- subgraph Purchase_Journey_Outcome [Purchase journey outcome] direction TB IN_PROGRESS --> Decision2{ }:::teritiaryEntity Decision2 -->|Klarna accepts purchase| COMPLETED[COMPLETED]:::primaryEntity Decision2 -->|Customer aborts| SUBMITTED3[SUBMITTED]:::secondaryEntity Decision2 -->|Acquiring Partner cancels request| CANCELED2[CANCELED]:::primaryEntity Decision2 -->|"Request expired (≥ 3h)"| EXPIRED2[EXPIRED]:::primaryEntity Decision2 -->|"Customer rejected - no payment methods available"| DECLINED[DECLINED]:::primaryEntity end

A Payment Request remains open for 3 hours. Klarna recommends Partners proactively cancel Payment Requests which have not resulted in successful transactions, especially if your Payment Request timeout is less than 3 hours.

Monitor and retrieve the payment_token

Klarna supports multiple integration methods. Acquiring Partners must implement Klarna webhook events at a minimum and may optionally combine them with other methods to enhance resilience. This approach ensures robustness, especially in cases where:

The customer closes the browser before returning
Network issues interrupt the redirect
Post-processing is required before informing the customer

For one-time payments, Klarna issues a klarna_network_session_token that can be used to authorize the payment. The klarna_network_session_token is valid for only 1 hour, so be sure to use it promptly to create the transaction.

Subscribe to webhook events (required)

Acquiring Partners can subscribe to the payment.request.state-change webhooks events using the guidelines here. Klarna will send webhook notifications whenever the payment request state is updated.

The webhook event payment.request.state-change.completed is triggered when the Payment Request reaches the state COMPLETED.

Sample payload

JSON

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

Consult the API reference Klarna Icon for a complete description of the webhook payload.

Read the payment request

The Klarna token(s) can also be retrieved through the Read Payment Request API Klarna Icon . It will be stored in the state_context object of the payment request once in state = COMPLETED.

Sample response - State COMPLETED

JSON

{
  "payment_request_id": "krn:payment:eu1:request:10be1d49-7beb-6b24-b9dd-8c14d0528503",
  "state": "COMPLETED",
  "previous_state": "IN_PROGRESS",
  "state_context": {
    "klarna_network_session_token": "krn:payment:eu1:klarna-network-session-token:31b543e0-6430-64df-970c-f1ae3cd9d8b0"
  },
  "expires_at": "2025-02-26T17:25:34.534721775Z",
  "created_at": "2025-02-24T17:25:34.534721775Z",
  "updated_at": "2025-02-24T17:25:34.534721775Z",
  "payment_request_reference": "acquiring-partner-request-reference-1234",
  "amount": 11836,

Placeholders in the `return_url`

As mentioned in the "Handle step-up scenario" section, return_url is not guaranteed to be called in all cases, and frontend redirection can be affected by network issues. Therefore, use return_url strictly to enhance the customer experience (by redirecting them to the appropriate page after completion or cancellation) or as a redundancy to retrieve the klarna_network_session_token in addition to using a webhook integration.

The return_url directs the customer back to the Partners website to the predefined url after a successful or abandoned authorization. By incorporating placeholders into the URL, Klarna can dynamically insert relevant transaction information, ensuring the URL contains all necessary details for processing.

This is particularly relevant whenever acquiring Partners make use of an internal return_url rather than the Partner's frontend URL when calling the Payment Authorize API.

Details about the available return_url placeholders are provided below:

Placeholder	Description
`{klarna.payment_request.klarna_network_session_token}`	The `klarna_network_session_token`, available when a payment request is successfully completed, and used to create a transaction.
`{klarna.payment_request.id}`	Klarna Payment Request identifier. Used in management of a Payment Request.
`{klarna.payment_request.state}`	State of the payment request - may be used as a hint.
`{klarna.payment_request.payment_request_reference}`	The provided reference to the payment request.

Sample request URL

SHELL

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-Klarna-Network-Session-Token: eyJhbGciOiJIU...' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": { .. },
        "interoperability_data":  "<serialized-json>",
        "request_payment_transaction": {
          "amount": 11800,
          "payment_transaction_reference": "acquiring-partner-transaction-reference-1234"
        },

Once the customer completes a payment and is redirected, the return_url will contain the payment request data points replacing the placeholders:

Klarna recommends that all Partners verify data received via redirect against webhook data to prevent klarna_network_session_token misuse.
Klarna Network tokens passed through the return_url are only valid for the account that completes the payment, ensuring protection against hijacking.

Example

HTTP

https://acquiringpartner.example/klarna-redirect?klarna_network_session_token=krn:payment:eu1:payment-token:31b543e0-6430-64df-970c-f1ae3cd9d8b0&request_id=krn:payment:eu1:request:10be1d49-7beb-6b24-b9dd-8c14d0528503&state=COMPLETED&reference=acquiring-partner-reference-12345

Cancel a payment request

Authorize the payment

API & SDK references

Read the state of a Payment Request

Cancel payment request

Create a server-to-server payment request

Update a Payment Request