Payment Authorization Overview

Understand how to authorize Payment Transactions, handle step-up scenarios, and monitor Payment Request states through the complete authorization flow.

Payment Authorization is the process that occurs after a customer selects Klarna and clicks the "Pay" button. Klarna processes the authorization request and returns one of three outcomes: approved, step-up required, or declined.

When Klarna approves the authorization, it creates the final Payment Transaction.

Overview

Payment Authorization follows a consistent pattern across both integration paths (server-side integration and hosted checkout):

1.
Initial authorization – Call authorizePayment with payment context and customer data
2.
Step-up response – Klarna returns whether additional customer verification is required
3.
Klarna Purchase Journey (if step-up required) – The customer completes verification in the Klarna Purchase Journey
4.
Final authorization (if step-up required) – Call authorizePayment again to finalize the transaction
5.
Transaction completion – Klarna creates the Payment Transaction and the customer proceeds to confirmation

Payment Authorization outcomes:

Outcome	Description
Approved	Klarna approves the authorization without additional verification. Klarna creates the Payment Transaction and the customer proceeds to confirmation.
Step-up required	Klarna requires additional customer verification. The Partner or Acquiring Partner launches the Klarna Purchase Journey, and the final authorization call completes the transaction after the customer completes verification.
Declined	Klarna declines the authorization. The Partner returns the customer to checkout with an error message.

Authorization flow components:

Component	Description
Payment Authorization API	Klarna API endpoint for creating and finalizing Payment Authorizations. Refer to authorizePayment for the complete documentation
Payment Request	Entity created when Klarna requires step-up verification. Tracks the authorization state during the Klarna Purchase Journey.
Payment Transaction	Final transaction entity created when authorization succeeds
Klarna Purchase Journey	Customer-facing interface for step-up authentication and verification
Klarna web SDK	JavaScript SDK that launches the Klarna Purchase Journey in a pop-up window
Klarna webhooks	Asynchronous notifications about Payment Request state changes and authorization outcome

Integration paths and flow

There are two ways to handle Payment Authorization: server-side integration and hosted checkout. Both paths follow the same authorization logic but differ in who manages the Klarna Purchase Journey.

Server-side integration

In a server-side integration, Partners manage the customer-facing experience and launch the Klarna Purchase Journey when step-up is required. The Acquiring Partner backend handles the authorizePayment API calls and webhook processing.

When to use: Partners control their own checkout and payment authorization flow, want to integrate the Klarna web SDK into their frontend, and need flexibility in how they present the Klarna Purchase Journey. Partners manage their own authorization state and error handling. This path requires the Partner to integrate and manage the Klarna web SDK, handle asynchronous webhook notifications, and implement state management for multi-step flows.

Flow steps

1.
The customer selects Klarna and clicks Pay on the Partner's checkout
2.
The Partner sends a Payment Authorization request to the Acquiring Partner API
3.
The Acquiring Partner calls authorizePayment with payment context
4.
Klarna processes the authorization request and returns the result

If approved immediately:

Klarna creates the Payment Transaction
The Acquiring Partner notifies the Partner via webhook
The Partner redirects the customer to the confirmation page

If step-up is required:

Klarna returns a payment_request_id and payment_request_url
The Acquiring Partner returns step-up details to the Partner
The Partner launches the Klarna Purchase Journey using the Klarna web SDK
The customer completes verification in the Klarna Purchase Journey
Klarna notifies the Acquiring Partner via webhook when complete
The Acquiring Partner calls authorizePayment again to finalize
Klarna creates the Payment Transaction
The Acquiring Partner notifies the Partner via webhook
The Partner redirects the customer to the confirmation page

If declined:

Klarna returns a declined status
The Acquiring Partner returns error details to the Partner
The Partner displays an error message and returns the customer to checkout

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant P as Partner participant AP as Acquiring Partner participant K as Klarna Note over C,K: Payment Presentation integration (previous step) C->>P: Select Klarna and click Pay button P->>AP: Request Payment Authorization AP->>K: Call Payment Authorize API Note over AP,K: First authorization call alt Approved immediately K-->>AP: Authorization approved K->>K: Create payment transaction AP->>P: Webhook notification Note over AP,P: Authorization completed P->>C: Redirect to confirmation page else Step-up required K-->>AP: Step-up required (payment_request_id) AP-->>P: Return step-up details P->>K: Launch Klarna Purchase Journey (SDK) K->>C: Display Klarna Purchase Journey C->>K: Complete verification K->>AP: Webhook notification Note over K,AP: Step-up completed AP->>K: Call Payment Authorize API (final) Note over AP,K: Final authorization call K-->>AP: Authorization approved K->>K: Create payment transaction AP->>P: Webhook notification Note over AP,P: Authorization completed P->>C: Redirect to confirmation page else Declined K-->>AP: Authorization declined AP->>P: Webhook notification Note over AP,P: Authorization declined P->>C: Return to checkout with error end

Hosted checkout

In a hosted checkout and embedded elements integration, Acquiring Partners manage the complete authorization flow including launching the Klarna Purchase Journey when step-up is required. The Acquiring Partner frontend uses the Klarna web SDK to handle the Klarna Purchase Journey seamlessly.

When to use: The Acquiring Partner controls the checkout experience and wants to manage the complete authorization flow, including automatic handling of step-up scenarios via the Klarna web SDK. This simplifies Partner integration with fewer touchpoints and provides a consistent customer experience, but requires the Acquiring Partner to host and manage the payment form, handle webhook processing, and manage authorization state.

Flow steps

1.
The customer selects Klarna and clicks Pay on the Acquiring Partner checkout
2.
The Acquiring Partner frontend triggers Payment Authorization via the Klarna web SDK
3.
The Acquiring Partner backend calls authorizePayment with payment context
4.
Klarna processes the authorization request and returns the result

If approved immediately:

Klarna creates the Payment Transaction
Klarna notifies the Acquiring Partner backend via webhook
The Acquiring Partner frontend redirects the customer to the confirmation page

If step-up is required:

Klarna returns step-up details to the Acquiring Partner backend
The Klarna web SDK automatically launches the Klarna Purchase Journey in the Acquiring Partner frontend
The customer completes verification in the Klarna Purchase Journey
Klarna notifies the Acquiring Partner backend via webhook when complete
The Acquiring Partner backend calls authorizePayment again to finalize
Klarna creates the Payment Transaction
Klarna notifies the Acquiring Partner backend via webhook
The Acquiring Partner frontend redirects the customer to the confirmation page

If declined:

Klarna returns a declined status
Klarna notifies the Acquiring Partner backend via webhook
The Acquiring Partner frontend displays an error message and returns the customer to checkout

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant P as Partner participant AP as Acquiring Partner participant K as Klarna Note over C,K: Payment Presentation integration (previous step) C->>AP: Select Klarna and click Pay button AP->>K: Trigger authorization via SDK K->>K: Process authorization Note over K: Payment Authorize API call alt Approved immediately K-->>AP: Authorization approved K->>K: Create payment transaction K->>AP: Webhook notification Note over K,AP: Authorization completed AP->>C: Redirect to confirmation page else Step-up required K-->>AP: Step-up required AP->>K: Launch Klarna Purchase Journey (SDK) K->>C: Display Klarna Purchase Journey C->>K: Complete verification K->>AP: Webhook notification Note over K,AP: Step-up completed AP->>K: Finalize authorization via SDK Note over AP,K: Final authorization call K-->>AP: Authorization approved K->>K: Create payment transaction K->>AP: Webhook notification Note over K,AP: Authorization completed AP->>C: Redirect to confirmation page else Declined K-->>AP: Authorization declined K->>AP: Webhook notification Note over K,AP: Authorization declined AP->>C: Return to checkout with error end

Responsibilities by integration path

Server-side integration (Partner implements)

Partner's frontend:

Integrates the Klarna web SDK and triggers Payment Authorization when the customer clicks Pay
Launches the Klarna Purchase Journey in a pop-up when step-up is required
Listens for client-side notifications from the Klarna web SDK
Redirects customer to confirmation or error pages

Partner's backend:

Sends authorization requests to the Acquiring Partner API
Receives authorization results and step-up details
Processes webhook notifications about authorization state
Manages authorization state throughout the authorization flow

Acquiring Partner backend:

Calls authorizePayment for initial authorization
Includes payment context (amount, customer data)
Processes webhook notifications from Klarna
Calls authorizePayment again for final authorization after step-up
Returns the authorization result and transaction details to Partners
Handles errors and fallback logic

Hosted checkout (Acquiring Partner implements)

Acquiring Partner frontend:

Initializes the Klarna web SDK with payment context
Triggers authorization via the Klarna web SDK when the customer clicks Pay
The Klarna web SDK automatically launches the Klarna Purchase Journey for step-up scenarios
Handles client-side notifications from the Klarna web SDK
Redirects customer to confirmation or error pages

Acquiring Partner backend:

Receives authorization triggers from the frontend
Calls authorizePayment for initial authorization
Processes webhook notifications from Klarna about payment request state changes
Calls authorizePayment again for final authorization after step-up
Manages authorization state and transaction records
Handles errors and retry logic

Klarna web SDK:

Manages authorization API calls
Automatically launches the Klarna Purchase Journey in a pop-up for step-up
Handles client-side notifications and state updates
Provides callbacks for authorization completion

Payment Authorize API

The authorizePayment API operation is the core endpoint for requesting Payment Authorizations.

Call Type	When to Use	Key Parameters
Initial authorization	When the customer clicks the Pay button	Payment context (`amount`, `currency`), customer data, Klarna data points
Final authorization	After step-up completion (webhook notification received)	`klarna_network_session_token` received via webhook, updated payment context if needed

Klarna Purchase Journey

The Partner or Acquiring Partner launches the Klarna Purchase Journey when Klarna requires step-up verification:

Integration Method	Description	Requirements
SDK pop-up (recommended)	Launch the Klarna Purchase Journey in a pop-up window using the Klarna web SDK	Klarna web SDK integrated in frontend, `payment_request_id` from the authorization response
Redirect mode	Redirect the customer to the Klarna Purchase Journey via the `payment_request_url`	`payment_request_url` from the authorization response, `return_url` provided by the Partner or Acquiring Partner in the authorization request

Launch modes:

Web: Pop-up window via Klarna web SDK
iOS: ASWebAuthenticationSession
Android: Custom Tabs

Webhook integration

Klarna webhooks provide asynchronous notifications about Payment Request state changes and authorization outcome:

Webhook Event	Trigger	Required Action
Payment Request completed	The customer completes the step-up journey	Call authorizePayment for final authorization
Authorization approved	Klarna creates the Payment Transaction successfully	Update payment status, redirect customer to confirmation
Authorization declined	Klarna declines the authorization	Return customer to checkout with error message

State management

Track Payment Authorization through these states:

State	Description	Next Actions
Pending authorization	Initial authorization call in progress	Wait for response from authorizePayment
Step-up required	Klarna requires additional verification	Launch the Klarna Purchase Journey, monitor webhooks
Step-up in progress	The customer is completing verification	Monitor webhooks for completion
Approved	Klarna created the Payment Transaction	Redirect customer to confirmation
Declined	Klarna declined the authorization	Display error, return to checkout

Dynamic updates

If the authorization context changes during the flow, the current authorization must be canceled and restarted with updated data:

Amount changes – If the cart total changes before or during authorization (e.g., the customer modifies the cart), cancel the current authorization and restart with the updated amount. Submitting a final authorization with a different amount than the initial call will result in a declined authorization.
Customer data changes – Include the most recent customer information (e.g., updated shipping address) in the new authorization call. Stale customer data can lead to declined authorizations or incorrect fraud assessments.
Payment Request expiration – Payment Requests created during step-up have a limited validity window. If the customer doesn't complete the Klarna Purchase Journey within this window (recommended timeout: 15 minutes), cancel the authorization and restart when the customer returns.

Server-side integration: Partners must detect context changes and restart the authorization flow with updated data.

Hosted checkout: The Acquiring Partner frontend must detect context changes and restart authorization. The Klarna web SDK supports context change detection and restart handling.

Payment Authorization for Server-side integration

Payment Authorization for Hosted Checkout integration