Payment Request

Understand Payment Request as the step-up mechanism in Klarna's payment authorization. This resource explains when Payment Requests are created, how they enable the Purchase Journey, and how to manage their lifecycle.

Overview

Klarna creates a Payment Request only when additional customer interaction is required to complete a Payment Authorization. This occurs in step-up scenarios where the customer needs to review purchase details, provide consent, or complete verification steps before the payment authorization can be approved.

Payment Requests serve as the bridge between the initial payment authorization attempt and the customer's interaction with Klarna's Purchase Journey. They hold all the details that the customer will review and approve, ensuring a secure and compliant payment experience.

What is a Payment Request

A Payment Request is a Klarna resource that represents a pending payment authorization requiring customer interaction. Klarna creates it automatically when a Payment Authorization cannot be immediately approved and returns a STEP_UP_REQUIRED result.

The Payment Request contains:

Transaction details (amount, currency, line items)
Customer information
Payment context from the original authorization attempt
A unique payment_request_id and payment_request_url
Payment Request state and expiration details

Step-up scenarios

Klarna triggers a step-up when additional customer interaction is needed. This can occur for several reasons:

Consent required: The customer needs to explicitly consent to the payment authorization or tokenization.
Verification needed: Additional identity verification or authentication is required for compliance or risk management.
Customer review: The customer should review and confirm purchase details before Klarna can approve the payment authorization.
First-time customer: A new customer to Klarna may need to complete onboarding steps.

When step-up is required, the Acquiring Partner receives a STEP_UP_REQUIRED result in the Payment Authorization response, along with a payment_request object containing the necessary details to launch the Purchase Journey.

The Purchase Journey

The Purchase Journey is Klarna's customer-facing flow where customers review and approve payment authorizations during step-up scenarios. The Acquiring Partner launches this journey using the method configured in step_up_config — either by redirecting the customer to the payment_request_url (HANDOVER) or via the Klarna Web SDK using the paymentRequestId (SDK).

sequenceDiagram autonumber participant AP as Acquiring Partner participant K as Klarna participant C as Customer AP->>K: Payment Authorization API K->>AP: STEP_UP_REQUIRED + payment_request AP->>C: Launch Purchase Journey (HANDOVER or SDK) C->>K: Complete Purchase Journey K->>C: Display purchase details and collect consent C->>K: Approve purchase K->>AP: Webhook notification (payment authorization approved) AP->>K: Create Payment Transaction

Launch methods

The Purchase Journey is launched using the method specified in step_up_config when calling authorizePayment API :

HANDOVER: The Acquiring Partner redirects the customer to the payment_request_url. On mobile, the app_return_url is used to bring the customer back to the Partner's app after completion or after redirects to third-party apps (e.g., the Klarna app or a banking app).
SDK: The Klarna Web SDK launches the Purchase Journey using the paymentRequestId returned from the authorization response. Used by Partners integrating Klarna's hosted checkout pages or embedded elements.

Lifecycle

Payment Requests progress through several states during their lifecycle. By default, a Payment Request remains open for 3 hours before expiring. You can override this default 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 Purchase Journey.
`IN_PROGRESS`	The customer is in Klarna's Purchase Journey reviewing and approving the payment authorization.
`COMPLETED`	The customer has completed the 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 Acquiring Partner before authorization.
`DECLINED`	Payment Request was declined during the authorization process (e.g., 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 -->|Acquiring Partner cancels request| CANCELED1[CANCELED]:::primaryEntity Decision1 -->|Acquiring 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 -->|Acquiring 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 how to monitor Payment Request state changes and retrieve the Klarna Network Session Token, see the Monitoring Payment Requests section below.

Monitoring Payment Requests

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

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 that Acquiring Partners proactively cancel Payment Requests that haven't resulted in successful transactions, especially if the Partner's timeout is less than Klarna's default of 3 hours.

Relationship to Payment Authorization

Payment Requests are created as part of the Payment Authorization flow when step-up is required:

1.
Acquiring Partner calls authorizePayment endpoint with step_up_config
2.
Klarna determines step-up is needed
3.
Response includes result: STEP_UP_REQUIRED and a payment_request object
4.
Acquiring Partner launches the Purchase Journey
5.
Customer completes the Purchase Journey
6.
Acquiring Partner finalizes the payment authorization and Klarna creates a Payment Transaction.

The Payment Request bridges the initial authorization attempt and the final authorization decision after customer interaction.

Interoperability

Payment Requests benefit from interoperability when the customer has previously interacted with Conversion features. The Klarna Network Session Token preserves this context, potentially enabling faster approval or reduced friction during the Purchase Journey.

Payment Authorization

Custom Payment Request expiry

Klarna Network Session Token