API and SDKsSupport
Token creation - Monitor the state

As explained in the previous section, whenever a step-up scenario is triggered:

  1. The customer accepts the payment: The customer enters Klarna Purchase Journey to complete authentication and accept the payment
  2. The customer returns to your platform: Upon completion, Klarna redirects the customer to the provided return_url.
  3. Klarna notifies Acquiring Partner of payment completion
    1. The payment request transitions to state = COMPLETED.
    2. Klarna issues Klarna token(s).

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

  • Subscribe to payment.request.state-change.* webhook events to monitor payment request created as part of the step-up scenario
  • Handle COMPLETED, CANCELED, DECLINED and EXPIRED states properly.
  • Proactively cancel payment requests which have not resulted in successful transactions.
  • Optionally leverage available dynamic placeholders when making use of an internal return_url.

Monitoring the state for tokenization is similar to that for one-time payments; the key difference is the type of token received at the end—customer_token for tokenization and payment_token for one-time payments.

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:

StateDescriptionNext action

SUBMITTED

Initial state. Payment requests can be updated until the customer enters Klarna Journey.The Acquiring Partner returns the Klarna Payment request data points as defined in the Handle Step-up scenario section.

IN_PROGRESS

The customer is actively in Klarna’s purchase journey.Listen for state changes via webhook.

COMPLETED

Customer completed the flow.If a payment was requested, use payment_token to create the transaction.
No action required if only customer_token creation was requested.

EXPIRED

Payment request expired (t≥48h).Final state. No action.

CANCELED

Payment request canceled by Acquiring Partner before authorization.Final state. No action.

DECLINED

Payment request has been Declined during authorization.Final state. No action.

State transition diagram

flowchart LR classDef default fill:#F9F8F5,color:#0B051D classDef start fill:#0B051D,stroke:#0B051D,color:#FFFFFF classDef temp fill:#FFA8CD,stroke:#0B051D classDef final fill:#BF7E9A,stroke:#0B051D classDef cond fill:#E4E3DF,stroke:#0B051D Start((Start)):::start --> Submitted1["SUBMITTED"]:::temp subgraph Submission_Handling [Submission handling] direction TB Submitted1 --> Decision1{ }:::cond Decision1 -->|Customer enters<br/>Purchase Journey| IN_PROGRESS:::temp Decision1 -->|Acquiring Partner<br/>cancels request| Cancel1[CANCELED]:::final Decision1 -->|Acquiring Partner<br/>updates request| Submitted2[SUBMITTED]:::temp Decision1 -->|"Request expired<br/>(≥ 48h)"| EXPIRED1[EXPIRED]:::final end subgraph Purchase_Journey_Outcome [Purchase journey outcome] direction TB IN_PROGRESS --> Decision2{ }:::cond Decision2 -->|Klarna accepts<br/>purchase| COMPLETED:::final Decision2 -->|Customer aborts| Submitted3[SUBMITTED]:::temp Decision2 -->|Acquiring Partner<br/>cancels request| Cancel2[CANCELED]:::final Decision2 -->|"Request expired<br/>(≥ 48h)"| EXPIRED2[EXPIRED]:::final Decision2 -->|"Customer rejected - no payment methods available<br/>"| DECLINED[DECLINED]:::final end

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

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

Subscribe to webhook events

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

Consult the API reference 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. It will be stored in the state_context object of the payment request once in state = COMPLETED.

Sample response -State COMPLETED

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 payment_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:

PlaceholderDescription

{klarna.payment_request.payment_token}

The payment 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-Interoperability-Token: eyJhbGciOiJIU...' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": { .. },
        "interoperability_data":  "<serialized-json>",
        "request_payment_transaction": {
          "amount": 11800,

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 payment_token misuse.
  • Payment 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?payment_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

For security reasons customer_token is not supported as a placeholder in the return_url.