Payment Authorization Overview
Understand how to authorize Payment Transactions, handle step-up scenarios, and monitor Payment Request states through the complete authorization flow.
11 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 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 calls and webhook processing.
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_andrequest_ id 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 operation is the core endpoint for requesting Payment Authorizations.
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_ 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_ from the authorization response |
| Redirect mode | Redirect the customer to the Klarna Purchase Journey via the payment_ | payment_ from the authorization response, return_ 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. The default is 3 hours, configurable between 15 minutes and 48 hours via
interaction_. If the customer doesn't complete the Klarna Purchase Journey within this window, cancel the authorization and restart when the customer returns.expiry
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.
Jump to section...