Payment Request

Learn how to create and manage Payment Requests with Klarna: the standard first step for Partners to start a payment, drive the Klarna Purchase Journey, and obtain the token needed to authorize the transaction.

Overview

Creating a Payment Request is the standard first step for Partners to initiate a payment with Klarna. The Payment Request represents a pending purchase that the customer reviews and approves through Klarna Purchase Journey. Once approved, Klarna issues a Klarna Network Session Token used to authorize the payment and create the resulting Payment Transaction.

Some flows skip createPaymentRequest API

because they already hold a valid token: authorizations with a stored Customer Token and authorizations that reuse a Klarna Network Session Token issued by a Boost feature call authorizePayment API

directly.

The end-to-end flow is linear:

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna C->>P: Proceed to checkout P->>K: Create Payment Request K->>P: payment_request_id, payment_request_url, state=SUBMITTED P->>C: Redirect to payment_request_url C->>K: Complete Purchase Journey K->>P: Webhook payment.request.state-change.completed Note over K,P: klarna_network_session_token P->>K: authorizePayment (with klarna_network_session_token) K->>P: Payment Transaction created

What is a Payment Request

A Payment Request is a Klarna resource that represents a pending payment ready for customer interaction.

It contains:

Transaction details (amount, currency, supplementary_purchase_data, line items)
Customer information (when provided)
The customer interaction configuration (HANDOVER, return URLs)
A unique payment_request_id and payment_request_url
Payment Request state and expiration details

Create a Payment Request

A Payment Request can be created in two ways. The server-to-server API approach is the recommended path for most integrations.

Option 1: Server-to-server API (recommended)

Partners call createPaymentRequest API

from their backend. Klarna validates the request, generates a unique payment_request_id, and returns the Payment Request along with the URL the customer should be sent to.

This approach gives Partners full control over the payment flow and is independent of any client-side SDK. Use it whenever the checkout can call Klarna server-side.

Minimum request

Provide the amount, currency, and a customer_interaction_config describing how the customer will be handed over to Klarna Purchase Journey:

JSON

1 2 3 4 5 6 7 8

{
  "currency": "USD",
  "amount": 1000,
  "customer_interaction_config": {
    "method": "HANDOVER",
    "return_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
  }
}

Include supplementary_purchase_data. The following sub-fields are contractually required: line_items, purchase_reference, customer, and shipping. See Supplementary purchase data for the full set of fields.

Response

A successful call returns the created Payment Request in SUBMITTED state:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
  "currency": "USD",
  "amount": 1000,
  "state": "SUBMITTED",
  "state_context": {
    "customer_interaction": {
      "method": "HANDOVER",
      "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
      "payment_request_url": "https://pay.klarna.com/l/ZjW2Xipgh0tjbrBGD7hzJM"

Option 2: Klarna Web SDK (client-side)

When integrating with the Klarna Web SDK, the SDK can submit a Payment Request from the browser on behalf of Partners. This is convenient when Partners have no backend that can call Klarna directly, or when the entire checkout flow stays in the client.

Using the Web SDK to create the Payment Request still results in the same resource, the same lifecycle, and the same klarna_network_session_token once the customer completes the Klarna Purchase Journey.

For checkout integrations, Option 1 is preferred whenever possible: it offers stronger control, easier debugging, and clearer ownership of the request lifecycle.

Route to a specific Payment Account

When the Partner's Klarna setup includes more than one Payment Account (for example, multiple legal entities, brands, or store IDs), the acquiring_config block tells Klarna which one this Payment Request belongs to. When omitted, Klarna uses the default account configured for the Partner.

Provide one of the following routing variants:

Variant	Fields	When to use
Account-only	`payment_account_id`	A single Payment Account is operated per legal entity, and Klarna picks the matching Payment Acquiring Account automatically.
Acquiring-account	`payment_acquiring_account_id` + `payment_account_reference`	A specific Payment Acquiring Account must be targeted explicitly. For example, when the same legal entity has multiple acquiring configurations.

JSON

1 2 3 4 5 6 7 8 9 10

{
  "currency": "USD",
  "amount": 1000,
  "customer_interaction_config": {
    "method": "HANDOVER",
    "return_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}"
  },
  "acquiring_config": {
    "payment_account_id": "krn:partner:global:account:test:HGBY07TR"
  }

The same acquiring_config block, extended with settlement_currency, is also available on authorizePayment API

when Klarna should settle the resulting Payment Transaction in a specific currency. See Request settlement currency.

Update or cancel before customer interaction

While the Payment Request is in SUBMITTED state, the following actions are available:

updatePaymentRequest: adjust amount, currency, or supplementary purchase data when the customer changes their cart.
cancelPaymentRequest: explicitly cancel the Payment Request when the customer abandons checkout or the session times out.

The Klarna Purchase Journey

The Klarna Purchase Journey is Klarna's customer-facing flow where customers review and approve the payment. Partners launch it by sending the customer to the payment_request_url returned in the Payment Request.

Launch methods

The launch method is set on customer_interaction_config.method at Payment Request creation time. Choose the one that matches the customer experience:

HANDOVER (default): Redirect the customer to the payment_request_url returned in the Payment Request. Works for both web and mobile (native apps can open the URL via a universal link). On mobile, configure app_return_url so the customer is brought back to the Partner's app when the journey hands off to a third-party app (for example, a bank app or the Klarna app).
QR_CODE: Display the QR code returned in state_context.customer_interaction so the customer can continue the journey on a different device. Useful for in-store, contact center, or smart-TV checkouts.

Lifecycle

Payment Requests progress through several states during their lifecycle. By default, a Payment Request remains open for 3 hours before expiring. This default can be overridden with the custom Payment Request expiry feature.

States

State	Description
`SUBMITTED`	Initial state. Payment Request has been created and is waiting for the customer to enter the Klarna Purchase Journey.
`IN_PROGRESS`	The customer is in Klarna Purchase Journey reviewing and approving the payment authorization.
`COMPLETED`	The customer has completed the Klarna Purchase Journey and approved the payment authorization. A Klarna Network Session Token is issued to authorize the final transaction.
`EXPIRED`	Payment Request expired without completion. The default lifetime is 3 hours, configurable via `interaction_expiry`.
`CANCELED`	Payment Request was canceled by the Partner before authorization.
`DECLINED`	Payment Request was declined during the authorization process (for example, no payment methods available for the customer).

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 -->|Partner cancels request| CANCELED1[CANCELED]:::primaryEntity Decision1 -->|Partner updates request| SUBMITTED2[SUBMITTED]:::secondaryEntity Decision1 -->|Request expired| 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 cancels| SUBMITTED3[SUBMITTED]:::secondaryEntity Decision2 -->|Partner cancels request| CANCELED2[CANCELED]:::primaryEntity Decision2 -->|Request expired| EXPIRED2[EXPIRED]:::primaryEntity Decision2 -->|"Customer rejected - no payment methods available"| DECLINED[DECLINED]:::primaryEntity end

For information on monitoring Payment Request state changes and retrieving the Klarna Network Session Token, see the Monitoring Payment Requests section below.

Monitoring Payment Requests

Partners must monitor Payment Request state changes to know when the customer has completed the Klarna Purchase Journey and to retrieve the Klarna Network Session Token needed to authorize the payment.

Klarna webhooks (required): Subscribe to payment.request.state-change.completed webhooks to receive notifications when the state changes to COMPLETED.
readPaymentRequest: Retrieve the current Payment Request state and the klarna_network_session_token from the state_context when state is COMPLETED.

Klarna recommends proactively canceling Payment Requests that have not resulted in successful transactions, especially when the checkout session timeout is shorter than Klarna's default of 3 hours. Use cancelPaymentRequest API

to cancel them explicitly.

Authorize the payment

Once the Payment Request reaches COMPLETED and the klarna_network_session_token has been retrieved, call authorizePayment API

with the token and the final purchase details. The call returns APPROVED, STEP_UP_REQUIRED, or DECLINED.

For request parameters, sample payloads, and how to handle each result, see Authorize a customer-initiated payment (server-side) or Authorize a customer-initiated payment (Web SDK).

Use a Klarna Network Session Token from a Boost feature

When the customer interacts with a Boost feature integrated via the Klarna Web SDK (Express checkout, Sign in with Klarna, or On-site messaging), the SDK issues a Klarna Network Session Token that already carries the customer's context, consent, and purchase intent.

Boost-issued Klarna Network Session Tokens bypass the upfront Payment Request. Because a valid klarna_network_session_token is already available, createPaymentRequest API

is skipped entirely and authorizePayment API

is called directly. Klarna creates the Payment Request server-side as part of the authorize call. This is the same authorizePayment-first pattern used for Customer Token authorizations.

How to authorize with a Boost-issued Klarna Network Session Token

1.
Retrieve the token from the SDK when the customer completes the Boost interaction (for example, after Express checkout returns control to the Partner's page).
2.
Call authorizePayment from the backend with:
- 2.1.
  The Klarna-Network-Session-Token header set to the SDK-issued token.
- 2.2.
  currency and request_payment_transaction (amount, reference, optional capture: "NOW").
- 2.3.
  supplementary_purchase_data for the final cart contents.
- 2.4.
  Required: step_up_config with customer_interaction_config.method = HANDOVER and a return_url. Boost interactions do not include the full Klarna Purchase Journey, so Klarna typically requires additional customer interaction before approving the authorization. Without step_up_config, Klarna returns DECLINED rather than STEP_UP_REQUIRED, removing the opportunity to recover via a Klarna Purchase Journey.
- 2.5.
  Optionally acquiring_config to route to a specific Payment Account or request a settlement_currency.
3.
Handle the result. The same three outcomes apply as for any other authorize call (APPROVED, STEP_UP_REQUIRED, DECLINED). For parameter details, sample payloads, and full result handling, including the step-up recovery pattern, see Authorize a customer-initiated payment (server-side).

Klarna Network Session Token

Customer Token

Sharing supplementary purchase data

Build Payment Presentation with the Klarna Web SDK

Request settlement currency