Authorize a customer-initiated payment (server-side)

Authorize a customer-initiated payment from the Partner's backend without embedding the Klarna Web SDK. Create the Payment Request, redirect the customer to the Klarna Purchase Journey, retrieve the Klarna Network Session Token, and finalize the authorization.

399 min read

Overview

This guide describes how to authorize customer-initiated payments via direct calls to the Klarna API, without embedding the Klarna Web SDK in the checkout frontend. The integration is driven entirely from the Partner's backend: the customer is redirected to Klarna's hosted Klarna Purchase Journey, completes it on Klarna's domain, and is sent back to the Partner's confirmation page once the Klarna Purchase Journey ends.

Klarna Web SDK recommended

Klarna recommends using the Klarna Web SDK for new integrations. The Klarna Web SDK is a JavaScript library that renders Klarna's payment presentation and the Klarna Buy button directly inside the checkout, and orchestrates the Klarna Purchase Journey in a popup or modal so the customer remains on the Partner's page. It also supports Boost features (Express checkout, Sign in with Klarna, on-site messaging) with the same integration. To use it, follow Build the checkout with Klarna Web SDK and Authorize a customer-initiated payment (Web SDK) instead.

Use this server-driven guide only when embedding the Klarna Web SDK on the frontend is not feasible.

What Partners will build

A backend that creates a Payment Request and stores the resulting payment_request_id.
A redirect step from the checkout to the Klarna Purchase Journey.
A webhook handler that consumes the payment.request.state-change.completed event to obtain the klarna_network_session_token.
A backend that finalizes the authorization with authorizePayment and creates the Payment Transaction.

Prerequisites

Before starting, ensure the following are in place:

A valid Klarna Partner account with API credentials.
Klarna rendered as a payment option in the checkout. The Partner can fetch presentation assets and instructions via the Payment Presentation API.
Backend capability to receive and process Klarna webhooks. See Webhooks registration.
A subscription to the payment.request.state-change.completed webhook event.
A return_url on the Partner's domain (and an app_return_url for native mobile apps) where Klarna redirects the customer after the Klarna Purchase Journey.

End-to-end flow

When the customer clicks the Klarna Buy button in the checkout:

Create a Payment Request by calling createPaymentRequest with the payment context and customer_interaction_config.method = HANDOVER. See Step 1: Create a Payment Request.
- Klarna responds with a payment_request_id and a payment_request_url.
Redirect the customer to the Klarna Purchase Journey at the returned payment_request_url. See Step 2: Redirect the customer to the Klarna Purchase Journey.
- The customer completes the Klarna Purchase Journey on Klarna's domain.
- Klarna redirects the customer back to the configured return_url once the Klarna Purchase Journey ends.
Receive the Klarna Network Session Token through the payment.request.state-change.completed webhook when the Payment Request transitions to COMPLETED. See Step 3: Receive the klarna_network_session_token.
Authorize the payment by calling authorizePayment with the Klarna-Network-Session-Token header. Include step_up_config so Klarna can return STEP_UP_REQUIRED (and a new Payment Request) instead of DECLINED when additional customer interaction is needed. See Step 4: Authorize the payment.
- On STEP_UP_REQUIRED, redirect the customer through the new Klarna Purchase Journey, wait for the new Klarna Network Session Token, and call authorizePayment again.

sequenceDiagram autonumber participant C as Customer participant P as Partner participant K as Klarna C->>P: Clicks the Klarna Buy button P->>K: createPaymentRequest (HANDOVER, return_url, supplementary_purchase_data, acquiring_config) K->>P: payment_request_id, payment_request_url P->>C: Redirect to payment_request_url C->>K: Completes 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 (step_up_config) alt APPROVED K->>P: APPROVED, payment_transaction P->>C: Show success page else DECLINED K->>P: DECLINED P->>C: Show failure / alternative payment page else STEP_UP_REQUIRED K->>P: STEP_UP_REQUIRED, new Payment Request P->>C: Redirect to new payment_request_url C->>K: Completes step-up Purchase Journey K-->>P: Webhook with new klarna_network_session_token P->>K: authorizePayment again with new Klarna Network Session Token K->>P: APPROVED / DECLINED P->>C: Show success / failure page end

From the backend, call createPaymentRequest API

with the payment context and a customer_interaction_config describing how Klarna should hand the customer over to the Klarna Purchase Journey. Set method = HANDOVER and provide a return_url (and an app_return_url for native apps).

Parameter	Requirement	Description
`currency`	Required	Currency in ISO 4217 format.
`amount`	Required	Total amount of the Payment Request, including tax and discounts.
`customer_interaction_config.method`	Required	Set to `HANDOVER` for the redirect-based flow.
`customer_interaction_config.return_url`	Required	URL on the Partner's domain where Klarna redirects the customer after the Klarna Purchase Journey.
`customer_interaction_config.app_return_url`	Recommended	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_url`.
`payment_request_reference`	Recommended	The Partner's own reference for the Payment Request, used for reconciliation.
`supplementary_purchase_data`	Required	Purchase context required by Klarna. The following sub-fields are contractually required: `line_items`, `purchase_reference`, `customer`, and `shipping`. See Supplementary purchase data.
`acquiring_config`	Required	Routes the Payment Request to a specific Payment Account. See Configure acquiring_config below.

Configure acquiring_config

Route Payment Requests and Payment Transactions to a specific Payment Account by configuring acquiring_config on createPaymentRequest API

and on authorizePayment API

in Step 4. This guidance applies to Partners with multiple Payment Accounts under a single Acquiring Account.

Recommended for integration

Set acquiring_config consistently on createPaymentRequest API

and on authorizePayment API

. Mismatched values may trigger an additional step-up Klarna Purchase Journey before authorization completes.

How acquiring_config works

The acquiring_config property identifies which Payment Account processes the Payment Transaction. There are two ways to identify a Payment Account.

Option 1: Acquiring Account + reference

Use the combination of payment_acquiring_account_id and payment_account_reference to identify the Payment Account. This option is useful when the Partner manages Payment Accounts by their own reference strings rather than Klarna-generated IDs.

Property	Description
`payment_acquiring_account_id`	Unique identifier assigned by Klarna to the Acquiring Account. KRN format.
`payment_account_reference`	The Partner's own unique reference for the Payment Account, used to identify it without relying on Klarna-generated IDs. Maximum 255 characters.

Option 2: Payment Account ID

Use payment_account_id on its own to identify the Payment Account directly. This option is simpler when the Partner already has the Klarna-assigned Payment Account ID.

Property	Description
`payment_account_id`	Unique Payment Account identifier assigned by Klarna. KRN format.

Settlement currency

On authorizePayment API

in Step 4, the Partner may additionally include settlement_currency (ISO 4217) inside acquiring_config to specify the currency Klarna uses to settle the Payment Transaction. When omitted, settlement defaults to the Payment Transaction currency. See Request settlement currency.

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}",

Custom Payment Request expiry

Optionally set customer_interaction_config.interaction_expiry to override the default 3-hour Payment Request lifetime. See Custom Payment Request expiry.

Sample response

A successful call returns the created Payment Request in SUBMITTED state, including the payment_request_url to redirect the customer to in Step 2:

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",

Redirect the customer to the payment_request_url returned in Step 1.

On completion, Klarna redirects the customer back to the return_url (or app_return_url on mobile) provided in customer_interaction_config, and issues a klarna_network_session_token used to finalize the authorization.

Return URLs

The return_url and app_return_url set inside customer_interaction_config tell Klarna where to send the customer after they complete or stop the Klarna Purchase Journey.

`return_url`

When the Klarna Purchase Journey is launched in a web environment, Klarna redirects the customer to the return_url after they finish, whether they complete or stop the flow.

`app_return_url`

On mobile, the customer may be redirected to a third-party app (such as a bank app) or the Klarna app during the Klarna Purchase Journey. The app_return_url brings the customer back to the Partner's mobile app when this happens.

Register a URL scheme (for example, yourapp://klarna) that resumes the payment flow. Klarna invokes this URL after the customer completes a native app-based step. Resume the mobile app in its last state without applying state changes or deep link navigations.

Interaction scenarios

The return_url and app_return_url are not mutually exclusive. Depending on the device and environment, either or both may be triggered:

Scenario	Description
Pure web flow	The customer starts the Klarna Purchase Journey in a desktop browser. After completing the flow, Klarna redirects them to `return_url`.
App-to-app flow	The Partner's native app opens the Klarna Purchase Journey using a universal link. When the Klarna app is installed, the customer goes directly into it. After completion, Klarna redirects them to `app_return_url`.
WebView flow with app handover	The Partner's native app starts the Klarna Purchase Journey in a System WebView. When the customer must continue in an external native app, `app_return_url` returns them to the Partner's app mid-flow. They then resume in the WebView and, on completion, are redirected to `return_url`.

Once the customer approves the purchase in the Klarna Purchase Journey, Klarna issues a klarna_network_session_token and the Payment Request transitions to COMPLETED. This token is used in Step 4 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_network_session_token is valid for only 1 hour and must be used within this time frame to finalize the authorization.

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-[...]",

Acknowledge the event before authorizing

Handle payment.request.state-change.completed in two stages. In the webhook handler, verify the event, persist the payload — including the klarna_network_session_token — durably against metadata.event_id, and return a 2xx response immediately. Run everything that follows asynchronously, after the acknowledgment is sent.

Don't do any of the following before the acknowledgment:

Call authorizePayment in Step 4.
Create the Payment Transaction or any record derived from it.
Show the customer a confirmation page or send a confirmation message.

When an event arrives with a metadata.event_id you have already recorded, confirm that it is recorded and return a 2xx response without repeating the work. Set up your webhooks defines the accepted acknowledgment responses and the retry schedule Klarna applies when one doesn't arrive.

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 API

. Once the Payment Request reaches the COMPLETED state, the token is available in state_context.klarna_network_session_token.

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 API

with the klarna_network_session_token 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_option_id.

Parameter	Requirement	Description
`Klarna-Network-Session-Token` (header)	Required	The Klarna Network Session Token received in Step 3.
`currency`	Required	Same currency used in the Payment Request.
`request_payment_transaction.amount`	Required	Same amount used in the Payment Request.
`request_payment_transaction.payment_transaction_reference`	Recommended	The Partner's own reference for the Payment Transaction, used for reconciliation.
`supplementary_purchase_data`	Required	Same supplementary data sent on the Payment Request. The contractually required sub-fields (`line_items`, `purchase_reference`, `customer`, `shipping`) must be present. Significant differences from the Payment Request may cause Klarna to require re-confirmation.
`acquiring_config`	Required	Routes the Payment Transaction to the same Payment Account used on the Payment Request. Add `settlement_currency` (ISO 4217) when settling in a currency that differs from the Payment Transaction `currency`. See Configure acquiring_config.
`step_up_config`	Recommended	Opts the Partner in to the `STEP_UP_REQUIRED` outcome. When included, Klarna can request additional customer interaction (returning a new Payment Request) instead of declining cases where it needs more risk signals. Without it, those cases are returned as `DECLINED`. Set `customer_interaction_config.method = HANDOVER` and provide a `return_url` (and an `app_return_url`) so Klarna knows where to send the customer back after the step-up Klarna Purchase Journey. 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_transaction_response object. The result field indicates the outcome and determines the next action:

Result	Description	Next steps
`APPROVED`	The authorization succeeded and a `payment_transaction` was created.	Store the `payment_transaction_id` 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, significant discrepancies between the Payment Request and the authorize call, or risk evaluation requiring additional customer interaction when `step_up_config` was not included in the request.	Show the customer a decline or alternative payment page.
`STEP_UP_REQUIRED`	Klarna requires additional customer interaction before approving. Only returned when `step_up_config` was included in the authorize request. The response includes a new Payment Request with `state_context.customer_interaction.payment_request_url`.	Redirect the customer to the new `payment_request_url`, wait for the new Klarna Network Session Token (via webhook or by reading the Payment Request), and call authorizePayment again with the new token.

Step-up config behavior

Without step_up_config in the authorize request, Klarna cannot return STEP_UP_REQUIRED. It returns DECLINED instead in cases where additional customer interaction would have been needed. Klarna recommends including step_up_config by default to recover those cases.

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": {

Klarna Network response data

klarna_network_response_data is only present in the response when klarna_network_data was sent in the request. Treat the value as opaque.

Next steps

With the Payment Transaction created, the customer-initiated payment is complete. From here:

Manage the Payment Transaction lifecycle (capture, refund, cancel). See Manage Payment Transactions.
Tokenize the customer's payment method to authorize the same customer's payments again later. See Payment Tokenization.
Compare integration paths and decide whether to switch to the Klarna Web SDK. See Payment Presentation Overview.

Build Payment Presentation with the Klarna Web SDK

Authorize a customer-initiated payment (Web SDK)

Build Payment Presentation with the Payment Presentation API

Set up your webhooks

Sharing supplementary purchase data

Jump to section...

Authorize a customer-initiated payment (server-side)

Overview

Prerequisites

End-to-end flow

Step 1: Create a Payment Request

Configure acquiring_config

How acquiring_config works

Option 1: Acquiring Account + reference

Option 2: Payment Account ID

Settlement currency

Sample request

Sample response

Step 2: Redirect the customer to the Klarna Purchase Journey

Return URLs

app_return_url

Interaction scenarios

Step 3: Receive the klarna_network_session_token

Method: Subscribe to the payment.request.state-change.completed webhook (required)

Acknowledge the event before authorizing

Method: Read the Payment Request (optional fallback)

Step 4: Authorize the payment

Sample request

Handle the authorization result

Next steps

`app_return_url`

Step 3: Receive the `klarna_network_session_token`

Method: Subscribe to the `payment.request.state-change.completed` webhook (required)