Authorize a customer-initiated payment (Web SDK)
Authorize a customer-initiated payment when the Klarna Web SDK is embedded in the checkout. The SDK orchestrates the Klarna Purchase Journey through the Klarna payment button; the Partner's backend creates the Payment Request and finalizes the authorization.
Overview
Use this guide when the Klarna Web SDK is embedded in the checkout and the Partner wants to launch the Klarna Purchase Journey from the Klarna payment button, keeping the customer on the page in a popup or modal instead of redirecting them away.
The underlying API calls are the same as in the server-side flow: createPaymentRequest
, retrieve the . What differs is the orchestration: the SDK handles the customer-facing Klarna Purchase Journey through the
, retrieve the klarna_, then authorizePayment. What differs is the orchestration: the SDK handles the customer-facing Klarna Purchase Journey through the initiate callback on the Klarna payment button, while the Partner's backend remains responsible for creating the Payment Request and authorizing the payment.Server-rendered checkout alternative
When the checkout is server-rendered and the Web SDK is not embedded, follow Authorize a customer-initiated payment (server-side) instead. That guide covers the same underlying API calls using a full-page redirect to the Klarna Purchase Journey and a webhook to deliver the Klarna Network Session Token.
Scope of this guide
This guide focuses on the orchestration that follows: creating the Payment Request, retrieving the Klarna Network Session Token, and authorizing the payment. For displaying Klarna in the payment selector and configuring the Klarna payment button, see Build Payment Presentation with the Klarna Web SDK.
Prerequisites
Before starting, ensure the following are in place:
- A valid Klarna Partner Account with API credentials. Production accounts come with the Partner's agreement with Klarna. For testing, create a test account as described in Before you test.
- The Klarna Web SDK initialized in the checkout, with Klarna rendered in the payment selector and the Klarna payment button mounted. See Build Payment Presentation with the Klarna Web SDK.
- Backend capability to receive and process Klarna webhooks. See Webhooks registration.
- A subscription to the
payment.webhook event.request. state-change. completed - A
return_on the Partner's domain that Klarna can redirect the customer to when the Klarna Purchase Journey ends in aurl REDIRECTorDEVICE_flow.BEST
Completed Express Checkout
Skip the Payment Request after a completed one-step Express Checkout. The customer has already confirmed payment and shipping, so call authorizePayment directly with the Klarna Network Session Token that Express Checkout issued, including , with the token in the
directly with the Klarna Network Session Token that Express Checkout issued, including step_. A step-up is unlikely on this path. A customer-present payment with a stored Customer Token also starts with createPaymentRequest, with the token in the Klarna-Customer-Token header.End-to-end flow
When the customer selects Klarna in the checkout and clicks the Klarna payment button:
- The Web SDK invokes the
initiatecallback configured on the payment button. - The SDK passes the callback one object with
klarnaNetworkSessionTokenandpaymentOptionId. The Partner's frontend posts both to its own backend. - The Partner's backend calls createPaymentRequest with the payment context and
customer_, and returns the resultinginteraction_ config payment_to the frontend.request_ url - The frontend resolves the
initiatecallback with{ paymentRequestUrl }. The SDK launches the Klarna Purchase Journey in a popup, modal, or redirect depending on the configuredinitiationMode(DEVICE_is the recommended default). See Step 3: Configure how the Klarna Purchase Journey is launched.BEST - The customer completes the Klarna Purchase Journey (authentication, payment method selection, confirmation).
- The Payment Request transitions to
COMPLETEDand Klarna sends apayment.webhook carrying therequest. state-change. completed klarna_.network_ session_ token - The Partner's backend calls authorizePayment with the
Klarna-Network-Session-Tokenheader to create the Payment Transaction. Includestep_when the transaction can change between the Payment Request and the authorize call and the customer stays in the checkout, so Klarna can returnup_ config STEP_with a new Payment Request instead ofUP_ REQUIRED DECLINED. Omit it when nothing changes and the Partner authorizes from the completion webhook. See Payment Authorization. - When Klarna returns
STEP_, the customer clicks the Klarna payment button again and theUP_ REQUIRED initiatecallback returns the new Payment Request's URL, so the SDK launches the Klarna Purchase Journey for it. After the customer completes it, a new Klarna Network Session Token arrives via webhook and the backend calls authorizePayment again.
sequenceDiagram
autonumber
participant C as Customer
participant FE as Partner frontend (Web SDK)
participant BE as Partner backend
participant K as Klarna
C->>FE: Clicks Klarna payment button
FE->>FE: SDK invokes initiate({ klarnaNetworkSessionToken, paymentOptionId })
FE->>BE: POST /api/payment-request (klarna_network_session_token, paymentOptionId)
BE->>K: createPaymentRequest (HANDOVER, return_url, supplementary_purchase_data)
K->>BE: payment_request_url
BE->>FE: { paymentRequestUrl }
FE->>K: SDK launches Klarna Purchase Journey (modal/popup/redirect)
C->>K: Customer completes 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 (optional step_up_config)
alt APPROVED
K->>BE: APPROVED, payment_transaction
BE->>FE: Confirmation
FE->>C: Show success page
else DECLINED
K->>BE: DECLINED
BE->>FE: Decline
FE->>C: Show failure / alternative payment page
else STEP_UP_REQUIRED (only if step_up_config was sent)
K->>BE: STEP_UP_REQUIRED, new Payment Request
BE->>FE: Ask the customer to continue with Klarna
C->>FE: Clicks Klarna payment button again
FE->>BE: initiate fetches the step-up paymentRequestUrl
BE->>FE: { paymentRequestUrl }
FE->>K: SDK launches step-up Purchase Journey
C->>K: Customer completes step-up Purchase Journey
K-->>BE: Webhook with new klarna_network_session_token
BE->>K: authorizePayment again with new Klarna Network Session Token
K->>BE: APPROVED / DECLINED
BE->>FE: Result
FE->>C: Show success / failure page
end
The : the Web SDK links the customer's session to the Payment Request itself.
initiate callback is configured on the Klarna payment button when it is mounted. The SDK invokes it the moment the customer clicks the button and passes it one object with klarnaNetworkSessionToken and paymentOptionId. Use the callback to forward both to the backend, create the Payment Request, and resolve the callback with the resulting paymentRequestUrl. The Klarna Network Session Token doesn't need to go on createPaymentRequest: the Web SDK links the customer's session to the Payment Request itself.JAVASCRIPT
1
2
3
4
5
6
7
8
9
10
async function initiateKlarnaPayment({ klarnaNetworkSessionToken, paymentOptionId }) {
try {
// Forward both values to the backend, which creates the Payment Request
const response = await fetch('/api/payment-request', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ klarnaNetworkSessionToken, paymentOptionId })
});
if (!response.ok) throw new Error('Network or server error');For details on configuring the
paymentButton. parameters, see Build Payment Presentation with the Klarna Web SDK, Step 7: Configure the Klarna payment button.From the backend endpoint called by the with the payment context and a
initiate callback, call createPaymentRequest with the payment context and a customer_. For Web SDK integrations, set method = HANDOVER and provide a return_ (and optionally an app_ for native apps). The same fields apply as in the server-side flow. See Payment Request for the full resource model and Supplementary purchase data for the recommended data points.Include at minimum:
| Parameter | Required | Description |
|---|---|---|
currency | Yes | Currency in ISO 4217 format. |
amount | Conditional | Total amount of the Payment Request, including tax and discounts. Required unless request_ is provided. Omit it only when the Payment Request creates a Customer Token without an initial charge. |
customer_ | Yes | Set to HANDOVER. The SDK orchestrates how the Klarna Purchase Journey is launched (modal, popup, or redirect) based on initiationMode. |
customer_ | Yes | URL on the Partner's domain where Klarna redirects the customer when the SDK falls back to a redirect. It's used by the recommended DEVICE_ mode on mobile and by REDIRECT mode. |
customer_ | Optional | Application URL scheme that returns the customer to the Partner's native app after a mid-flow handover to a third-party app (for example, a bank app or the Klarna app). Not a substitute for return_. |
payment_ | Recommended | The Partner's own reference for the Payment Request, used for reconciliation. |
supplementary_ | Recommended | Additional purchase context (line items, customer, shipping, purchase reference). Improves underwriting and fraud detection and powers customer communication. See Supplementary purchase data. |
acquiring_ | Conditional | Routes the Payment Request to a specific Payment Account or Payment Acquiring Account. Required when the Partner's Klarna setup includes more than one account. Provide either payment_ (account-only routing) or payment_ together with payment_ (acquiring-account routing). When omitted, Klarna uses the default account configured for the Partner. |
Sample request
SHELL
1
2
3
4
5
6
7
8
9
10
curl https://api-global.test.klarna.com/v2/payment/requests \
-H 'Authorization: Basic <API key>' \
-H 'Content-Type: application/json' \
-d '{
"currency": "USD",
"amount": 11800,
"payment_request_reference": "partner-request-reference-1234",
"customer_interaction_config": {
"method": "HANDOVER",
"return_url": "https://partner.example/klarna-redirect?id={klarna.payment_request.id}",Sample response
A successful call returns the created Payment Request in
SUBMITTED state. For the full list of states a Payment Request can transition through, see Payment Request: States. The backend returns state_ to the frontend so the initiate callback can resolve with it and the SDK can launch the Klarna Purchase Journey. Fill line_, customer and shipping in the request as described in Supplementary purchase data.JSON
1
2
3
4
5
6
7
8
9
10
{
"payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
"payment_request_reference": "partner-request-reference-1234",
"currency": "USD",
"amount": 11800,
"state": "SUBMITTED",
"state_context": {
"customer_interaction": {
"method": "HANDOVER",
"payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",The Web SDK launches the Klarna Purchase Journey using the
initiationMode parameter set on the Klarna payment button. It controls whether the journey opens in a popup, an in-page iframe, or as a full-page redirect.initiationMode | Description |
|---|---|
DEVICE_ | Default and recommended. Selects the best launch method per device: on the page on desktop (popup, with a full-screen iframe as fallback), redirect on mobile and in native WebViews. Requires return_ in customer_. |
ON_ | Launches the Klarna Purchase Journey on the same page in a popup (or full-screen iframe as fallback). The customer never leaves the page. |
REDIRECT | Redirects the customer to the Klarna Purchase Journey. Requires return_ in customer_. |
For details on the rest of the
paymentButton. configuration parameters and a sample integration, see Build Payment Presentation with the Klarna Web SDK, Step 7: Configure the Klarna payment button.Track the Klarna Purchase Journey with Web SDK events
Register event handlers on the
KlarnaPayment SDK interface to track the lifecycle of the Klarna Purchase Journey on the client side. See complete, abort and error in the Klarna Web SDK reference.| Event handler | Purpose |
|---|---|
on("complete", callback) | Triggered when the customer completes the purchase. During a redirect flow, fires once the success page loads. |
on("abort", callback) | Triggered when the customer cancels the Klarna Purchase Journey. |
on("error", callback) | Triggered when initiate() (including a click on the payment button), fetch() or cancel() fails. The error is still thrown afterwards, so try/catch around your own calls keeps working. A failed button click has no caller to catch it, so handle it here. Not triggered when the customer closes the payment window, which is a cancellation rather than an error, or for presentation(). |
JAVASCRIPT
1
2
3
4
5
6
klarna.Payment.on("complete", (paymentRequest) => {
console.log("Payment request completed");
// By default, Klarna will redirect to the submitted return_url upon completion.
// Return false if you want to prevent the redirection to the success page.
return true;
});Integration requirement
Use Web SDK events to enhance the customer experience, for example, displaying clear error messages when a purchase is canceled, or disabling page interactions while Payment Authorization is in progress.
Never use SDK events to trigger Payment Authorization. Always rely on Klarna webhooks to receive the
klarna_ and finalize the payment after the customer completes the purchase.Once the customer completes the purchase, Klarna issues a
klarna_ and the Payment Request transitions to COMPLETED. This token is used in Step 5 to finalize the authorization.Klarna provides multiple methods to retrieve the token. Subscribing to the webhook event is required and may be combined with reading the Payment Request as a fallback for resilience.
Integration requirement
The
klarna_ is valid for only 1 hour and must be used within this time frame to finalize the authorization. See Klarna Network Session Token: Expiration for the expiration model and where to read the expiration timestamp.Method: Subscribe to the payment.request.state-change.completed webhook (required)
Klarna sends this event when the Payment Request reaches the
COMPLETED state, indicating that the customer has approved the purchase and the authorization can be finalized. Subscribe via the Webhooks registration guide.Sample payload
JSON
1
2
3
4
5
6
7
8
9
10
{
"metadata": {
"event_type": "payment.request.state-change.completed",
"event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
"event_version": "v2",
"occurred_at": "2024-01-01T12:00:00Z",
"correlation_id": "2d1557e8-17c3-466c-924a-bbc3e91c2a02",
"subject_account_id": "krn:partner:global:account:test:HGBY07TR",
"recipient_account_id": "krn:partner:global:account:test:LWT2XJSE",
"product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-[...]",Method: Read the Payment Request (optional fallback)
As a fallback (for example, when the webhook is delayed or the handler missed it) retrieve the token by calling readPaymentRequest. Once the Payment Request reaches the
. Once the Payment Request reaches the COMPLETED state, the token is available in state_.Sample response
JSON
1
2
3
4
5
6
7
8
9
10
{
"payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-[...]",
"payment_request_reference": "partner-request-reference-1234",
"state": "COMPLETED",
"previous_state": "IN_PROGRESS",
"state_context": {
"klarna_network_session_token": "krn:network:us1:test:session-token:eyJhbGciOiJIU..."
},
"currency": "USD",
"amount": 11800,Finalize the payment by calling authorizePayment with the
with the klarna_ in the Klarna-Network-Session-Token request header. Klarna creates the Payment Transaction and returns the result.The customer's selected payment method is carried by the Klarna Network Session Token. There is no need to send
payment_.Include at minimum:
| Parameter | Required | Description |
|---|---|---|
Klarna-Network-Session-Token (header) | Yes | The Klarna Network Session Token received in Step 4. |
currency | Yes | Same currency used in the Payment Request. |
request_ | Yes | The final amount for the purchase, including tax or shipping calculated after the Payment Request was created. When it differs from the Payment Request, Klarna asks for approval of the new amount. If Klarna can't approve it without the customer, result_ is AMOUNT_, on STEP_ when step_ is included and on DECLINED otherwise. |
request_ | Recommended | The Partner's own reference for the Payment Transaction, used for reconciliation. |
supplementary_ | Recommended | The final purchase details: the final line_ and the shipping address the customer ends up with. After Express Checkout, use the shipping returned on the completed Payment Request. Sending the final values keeps the transaction eligible for the merchant protection program. |
acquiring_ | Conditional | Routes the Payment Transaction to a specific Payment Account or Payment Acquiring Account, and optionally requests the currency Klarna uses to settle the transaction. Use the same Payment Account as on the Payment Request: a different one returns STEP_ with result_ set to ACQUIRING_. Adding a Payment Account the Payment Request didn't have, or adding settlement_ (ISO 4217), isn't a mismatch. An unsupported settlement_ returns a 400 validation error. See Request settlement currency. |
step_ | Conditional | Include it when the transaction can change between the Payment Request and this call, and keep the customer in the checkout until the result arrives. Klarna can then return STEP_ with a new Payment Request. Omit it when nothing changes and you authorize from the completion webhook. Set customer_ and provide a return_, plus an app_ for native apps. See Payment Authorization. |
Sample request
SHELL
1
2
3
4
5
6
7
8
9
10
curl https://api-global.test.klarna.com/v2/payment/authorize \
-H 'Authorization: Basic <API key>' \
-H 'Content-Type: application/json' \
-H 'Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU...' \
-d '{
"currency": "USD",
"request_payment_transaction": {
"amount": 11800,
"payment_transaction_reference": "partner-transaction-reference-1234"
},Handle the authorization result
Klarna returns a
payment_ object. The result field indicates the outcome and determines the next action:| Result | Description | Next steps |
|---|---|---|
APPROVED | The authorization succeeded and a payment_ was created. | Store the payment_ and proceed with post-purchase operations (capture, refund, etc.). Show the customer a confirmation page. |
DECLINED | The authorization was not approved. No transaction is created. Common causes include an expired Klarna Network Session Token when step_ wasn't included, a currency that differs from the one on the Payment Request, or a risk decision that another Klarna Purchase Journey can't resolve. result_ says why, for example KLARNA_. | Show the customer a decline or alternative payment page. |
STEP_ | Klarna requires additional customer interaction before approving. Only returned when step_ was included in the authorize request. result_ says why, for example AMOUNT_ or KLARNA_. The response includes a new Payment Request with state_. | Pass the new paymentRequestUrl back to the Web SDK so it can launch the step-up Klarna Purchase Journey. When the customer completes it, a new Klarna Network Session Token arrives via webhook. Call authorizePayment again with the new token. |
Step-up requires opt-in
Include
step_ when the transaction can change on the authorize call and the customer is still in the checkout. When nothing changes, authorize from the completion webhook without it. See Payment Authorization for both patterns.The response schema is as follows:
JSON
1
2
3
4
5
6
7
8
9
10
{
"payment_transaction_response": {
"result": "APPROVED",
"payment_transaction": {
"payment_transaction_id": "krn:payment:us1:transaction:6debe89e-98c0-[...]",
"payment_transaction_reference": "partner-transaction-reference-1234",
"amount": 11800,
"currency": "USD",
"payment_pricing": {...},
"payment_funding": {When authorizePayment returns call that returns
returns STEP_, Klarna creates a new Payment Request that drives the customer through an additional Klarna Purchase Journey to resolve the cause named in result_. The integration loops once more through Step 3, Step 4, and Step 5, using the new Payment Request, and ends with a second authorizePayment call that returns APPROVED or DECLINED.Pass the new Payment Request to the frontend
Store
payment_ from the STEP_ response, and return it when the frontend asks for it. Return a JSON response that the initiate callback can use:JAVASCRIPT
1
2
3
4
5
// Backend
res.json({
paymentRequestUrl:
response.payment_request.state_context.customer_interaction.payment_request_url
});Launch the step-up Klarna Purchase Journey
The step-up can't be started from the backend, and the returns. The Web SDK only calls
initiate callback from Step 1 has already resolved by the time authorizePayment returns. The Web SDK only calls initiate when the customer clicks the Klarna payment button, so show the customer the button again, with a short explanation that Klarna needs them to confirm the purchase. When they click it, the initiate callback fetches the step-up paymentRequestUrl from the backend and returns it. The Web SDK launches the step-up Klarna Purchase Journey using the same initiationMode configured on the button:JAVASCRIPT
1
2
3
4
5
6
7
// Frontend: initiate callback for the step-up, called when the customer clicks the button again
async function initiateKlarnaStepUp() {
const response = await fetch('/api/klarna-step-up'); // Returns the stored step-up URL
if (!response.ok) throw new Error('Network or server error');
const { paymentRequestUrl } = await response.json();
return { paymentRequestUrl };
}The customer completes the additional verification in the Klarna Purchase Journey, and the new Payment Request transitions to
COMPLETED.Receive the new Klarna Network Session Token
A second
payment. webhook is delivered, carrying a fresh klarna_ for the new Payment Request. Handle it with the same webhook handler used in Step 4.Retry authorizePayment with the new token
Call authorizePayment again, using the new
again, using the new klarna_ in the Klarna-Network-Session-Token header. Send the same currency, request_, acquiring_, and supplementary_ used in the original authorize call. Klarna returns APPROVED or DECLINED. STEP_ is not returned a second time once the customer has gone through the step-up Klarna Purchase Journey.Step-up loop is not a restart
Treat the step-up loop as a single recoverable detour, not a full restart. Reuse the Payment Transaction reference, supplementary data, and routing from the first authorize call. Only the Klarna Network Session Token changes between the two requests.
Jump to section...