Payment Authorization overview

Compare the two ways Partners can authorize Klarna payments — Klarna Web SDK and server-side integration — and understand the end-to-end flow from creating a Payment Request to finalizing the Payment Transaction.

Payment Authorization is the process that turns a customer's intent to pay with Klarna into a final Payment Transaction. After the customer selects Klarna and clicks the payment button, Partners drive the customer through the Klarna Purchase Journey, retrieve the Klarna Network Session Token, and call Klarna's Payment Authorization API to create the Payment Transaction.

This page summarizes the end-to-end flow, the two integration paths available to Partners, and how to handle the possible authorization outcomes. For the underlying concepts (Payment Request lifecycle, Klarna Network Session Token, supplementary purchase data), see the Payment Request resource.

The end-to-end flow

For Partners, payment authorization follows a linear flow built around the Payment Request:

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna C->>P: Select Klarna and click Pay P->>K: createPaymentRequest K-->>P: payment_request_id, customer_interaction (HANDOVER URL or SDK) P->>C: Launch Purchase Journey (HANDOVER or SDK) C->>K: Complete Purchase Journey K-->>P: payment.request.state-change.completed (Klarna Network Session Token in state_context) P->>K: authorizePayment with Klarna Network Session Token K-->>P: APPROVED, STEP_UP_REQUIRED, or DECLINED Note over P,K: On APPROVED, Klarna creates the Payment Transaction P->>C: Redirect to confirmation page

Create a Payment Request with createPaymentRequest, including the customer interaction method, amount, and supplementary purchase data.
The customer completes the Klarna Purchase Journey, where Klarna handles authentication, payment method selection, and approval.
The Klarna Network Session Token is delivered. The Klarna Network Session Token is the context token that proves the customer has completed the Klarna Purchase Journey and consented to the payment. Klarna issues it when the Payment Request transitions to COMPLETED. Partners obtain it from the payment.request.state-change.completed Klarna webhook payload or by reading the Payment Request's state_context.
Authorize the payment with authorizePayment using the Klarna Network Session Token. Klarna creates the Payment Transaction on APPROVED.

Integration paths

There are two ways to integrate Klarna Payment Authorization into the checkout: Klarna Web SDK and server-side integration. Both paths follow the same authorization logic — createPaymentRequest, retrieve the Klarna Network Session Token, then authorizePayment — but differ in how the Klarna Purchase Journey is launched and how the customer is brought back to the checkout.

Klarna Web SDK (recommended)

In a Klarna Web SDK integration, the Partner's frontend embeds the Klarna Web SDK and mounts the Klarna payment button in the payment selector. When the customer clicks the button, the SDK invokes the initiate callback, the Partner's backend creates the Payment Request, and the SDK launches the Klarna Purchase Journey in a popup, modal, or redirect (depending on initiationMode). Once the customer completes the Klarna Purchase Journey, the Partner's backend calls authorizePayment API

with the Klarna Network Session Token received via webhook.

When to use: Choose this path when the Partner's checkout frontend can host the Klarna Web SDK. The Klarna Purchase Journey opens as a popup, modal, or inline element so the customer stays on the Partner's checkout page, the SDK handles every STEP_UP_REQUIRED outcome automatically, and the same integration unlocks Boost features (Express checkout, Sign in with Klarna, on-site messaging) without additional setup.

For the presentation step (initialize the SDK, render the payment selector and the Klarna payment button), see Build Payment Presentation with the Klarna Web SDK.
For the authorization flow (initiate callback, Payment Request creation, Klarna Network Session Token handling, and authorizePayment orchestration), see Authorize a customer-initiated payment (Web SDK).

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant FE as Partner frontend (Web SDK) participant BE as Partner backend participant K as Klarna C->>FE: Select Klarna and click the payment button FE->>FE: SDK invokes the initiate callback FE->>BE: POST /api/payment-request (paymentOptionId, klarnaNetworkSessionToken) BE->>K: createPaymentRequest (payment context, customer_interaction_config) K-->>BE: payment_request_url BE-->>FE: { paymentRequestUrl } FE->>K: SDK launches the Klarna Purchase Journey (modal/popup/redirect) C->>K: Complete the Klarna Purchase Journey K-->>BE: Webhook payment.request.state-change.completed Note over K,BE: klarna_network_session_token BE->>K: authorizePayment with Klarna-Network-Session-Token header K-->>BE: APPROVED, STEP_UP_REQUIRED, or DECLINED BE-->>FE: Authorization result FE->>C: Redirect to confirmation or error page

Server-side integration

In a server-side integration, the Partner's backend orchestrates the full authorization flow without embedding the Klarna Web SDK in the checkout. The Partner creates the Payment Request directly via createPaymentRequest API

, redirects the customer to the payment_request_url returned by Klarna, and finalizes the authorization with authorizePayment API

after receiving the Klarna Network Session Token via webhook.

When to use: Choose this path when the checkout is fully server-rendered and adding a frontend JavaScript dependency isn't desirable, or when the runtime environment can't host the Klarna Web SDK. The Klarna Purchase Journey opens as a full-page redirect rather than a popup or modal, the Partner's backend handles every STEP_UP_REQUIRED outcome by driving the customer through a new Klarna Purchase Journey, and Boost features (Express checkout, Sign in with Klarna, on-site messaging) require a separate Klarna Web SDK integration if needed later.

For the implementation walkthrough (create the Payment Request, redirect to the Klarna Purchase Journey, handle the webhook, call authorizePayment), see Authorize a customer-initiated payment (server-side).
For the presentation step in a server-side checkout, see Build Payment Presentation with the Payment Presentation API.

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna C->>P: Select Klarna and click Pay P->>K: createPaymentRequest (HANDOVER, return_url, supplementary_purchase_data) K-->>P: payment_request_id, payment_request_url P->>C: Redirect to payment_request_url C->>K: Complete the Klarna Purchase Journey K->>C: Redirect to return_url K-->>P: Webhook payment.request.state-change.completed Note over K,P: klarna_network_session_token P->>K: authorizePayment with Klarna-Network-Session-Token header K-->>P: APPROVED, STEP_UP_REQUIRED, or DECLINED P->>C: Show confirmation or error page

Authorization outcomes

The authorizePayment API

response returns one of three results. Partners must handle them as follows:

Result	Meaning	Required action
`APPROVED`	Klarna approved the transaction. The Payment Transaction is created and ready for capture.	Update the order state, redirect the customer to the confirmation page, and follow up with capture or refund operations as needed.
`STEP_UP_REQUIRED`	Klarna needs additional customer interaction before approving. A Payment Request is created (or reused) for the customer to complete a Klarna Purchase Journey.	Drive the customer back into the Klarna Purchase Journey using the returned `customer_interaction`. When it completes, call authorizePayment again with the new Klarna Network Session Token.
`DECLINED`	Klarna declined the transaction.	Surface a clear error in the checkout and offer the customer a different payment method.

Even when the recommended flow is followed (create the Payment Request first, then authorize with the resulting Klarna Network Session Token), authorizePayment can still return STEP_UP_REQUIRED. Klarna's risk signals may require additional customer interaction before approval. All three outcomes must always be handled.

Webhooks

Klarna webhooks track Payment Request state changes asynchronously. Partners handle the following events for authorization:

Event	When it fires	Required action
`payment.request.state-change.in-progress`	The customer started the Klarna Purchase Journey.	Optional: update the checkout UI to reflect the in-progress state.
`payment.request.state-change.completed`	The customer completed the Klarna Purchase Journey. The payload includes the `klarna_network_session_token`.	Call authorizePayment with the Klarna Network Session Token to finalize the transaction.
`payment.request.state-change.canceled`	The Payment Request was canceled (by the Partner or by the customer).	Clean up the local order state.
`payment.request.state-change.expired`	The Payment Request expired before the customer completed it.	Prompt the customer to restart the checkout.

For details on the Payment Request lifecycle and state diagram, see Payment Request → Lifecycle.

Cancellation and expiration

The Payment Request lifetime must stay aligned with the Partner's checkout session:

Keep session lifetimes aligned: When the Partner's checkout session terminates or expires, call cancelPaymentRequest to close the Payment Request. Aligning the two preserves session continuity and avoids handover issues with the Partner's own session-management logic.
Custom expiration window: The default Payment Request lifetime is 3 hours. Use interaction_expiry to align with the checkout session timeout (between 15 minutes and 48 hours).

Next steps

Authorize a customer-initiated payment with the Klarna Web SDK — see Authorize a customer-initiated payment (Web SDK).
Authorize a customer-initiated payment from the backend — see Authorize a customer-initiated payment (server-side).
Save a payment method for future authorizations. See Payment Tokenization overview.

Payment Request

Build Payment Presentation with the Klarna Web SDK

Authorize a customer-initiated payment (Web SDK)

Authorize a customer-initiated payment (server-side)

Build Payment Presentation with the Payment Presentation API