Payment Authorization Overview

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

15 min read

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 all integration paths (server-side integration, hosted checkout, and mobile integration):

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 Mobile SDK	iOS, Android, and React Native SDK that launches the Klarna Purchase Journey inside the Partner's app
Klarna webhooks	Asynchronous notifications about Payment Request state changes and authorization outcome

Integration paths and flow

There are three ways to handle Payment Authorization: server-side integration, hosted checkout, and mobile integration. All 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

Mobile integration

In a mobile integration, Acquiring Partners provide their own Mobile SDK that embeds the Klarna Mobile SDK as an internal dependency. The Acquiring Partner backend calls authorizePayment API

, and when step-up is required, the Acquiring Partner's Mobile SDK launches the Klarna Purchase Journey natively inside the Partner's app.

When to use: The Acquiring Partner distributes a Mobile SDK (e.g., a unified payment sheet, drop-in UI, or custom component library) that Partners embed in their iOS, Android, or React Native apps. Partners integrate only the Acquiring Partner's Mobile SDK and, on iOS and React Native, provide their app's URL scheme, while the Acquiring Partner maintains the Klarna Mobile SDK dependency, handles webhook processing, and manages authorization state.

Flow steps

1.
The customer selects Klarna and taps the payment button in the Acquiring Partner's payment sheet
2.
The Acquiring Partner's Mobile SDK sends the payment to the Acquiring Partner backend
3.
The Acquiring Partner backend calls authorizePayment with payment context, acquiring_config.payment_account_id, and step_up_config (including app_return_url)
4.
Klarna processes the authorization request and returns the result

If approved immediately:

Klarna creates the Payment Transaction
The Acquiring Partner backend confirms the result to its Mobile SDK
The Partner app displays the confirmation screen

If step-up is required:

Klarna returns payment_request_id to the Acquiring Partner backend, which passes it to its Mobile SDK
The Acquiring Partner's Mobile SDK launches the Klarna Purchase Journey with the Klarna Mobile SDK
The customer completes verification in the Klarna Purchase Journey, and Klarna returns the customer to the Partner app via app_return_url
Klarna notifies the Acquiring Partner backend via webhook when complete
The Acquiring Partner backend calls authorizePayment again to finalize
Klarna creates the Payment Transaction
The Partner app displays the confirmation screen

If declined:

Klarna returns a declined status
The Acquiring Partner's Mobile SDK displays an error message and prompts the customer for an alternative payment method

Sequence diagram

sequenceDiagram autonumber participant C as Customer participant P as Partner app participant SDK as Acquiring Partner Mobile SDK participant AP as Acquiring Partner backend participant K as Klarna Note over C,K: Payment Presentation integration (previous step) C->>SDK: Select Klarna and tap pay SDK->>AP: Process payment AP->>K: Call Payment Authorize API K->>K: Process authorization alt Approved immediately K-->>AP: Authorization approved AP-->>SDK: Authorization confirmed SDK->>P: Payment complete P->>C: Display confirmation screen else Step-up required K-->>AP: Step-up required with payment_request_id AP-->>SDK: Return payment_request_id SDK->>K: Launch Klarna Purchase Journey (Klarna Mobile SDK) K->>C: Display Klarna Purchase Journey C->>K: Complete verification K->>P: Return to Partner app via app_return_url K->>AP: Webhook notification Note over K,AP: Step-up completed AP->>K: Finalize authorization K-->>AP: Authorization approved AP-->>SDK: Authorization confirmed SDK->>P: Payment complete P->>C: Display confirmation screen else Declined K-->>AP: Authorization declined AP-->>SDK: Authorization declined SDK->>C: Prompt for alternative payment method 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

Mobile integration (Acquiring Partner implements)

Acquiring Partner Mobile SDK:

Embeds and initializes the Klarna Mobile SDK
Sends the payment to the Acquiring Partner backend when the customer taps the payment button
Launches the Klarna Purchase Journey with the payment_request_id when step-up is required
Notifies the Partner app of the authorization outcome

Acquiring Partner backend:

Calls authorizePayment for initial authorization, including step_up_config with app_return_url
Returns payment_request_id to the Mobile SDK when step-up is required
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

Partner app:

Integrates the Acquiring Partner's Mobile SDK
Provides the app's custom URL scheme as the app return URL (iOS and React Native)
Displays the confirmation or error screen

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
Mobile SDK	Launch the Klarna Purchase Journey in the Partner's app by passing `payment_request_id` to the Klarna Mobile SDK	Klarna Mobile SDK embedded in the Acquiring Partner's Mobile SDK, `payment_request_id` from the authorization response, `app_return_url` 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. The default is 3 hours, configurable between 15 minutes and 48 hours via interaction_expiry. If the customer doesn't complete the Klarna Purchase Journey within this window, 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.

Mobile integration: The Acquiring Partner's Mobile SDK must detect context changes, and the Acquiring Partner backend must restart authorization with updated data.

Customer initiated Payment Authorization

Custom Payment Request expiry

Jump to section...