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.

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 conversion 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.

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 API

directly with the Klarna Network Session Token that Express Checkout issued, including step_up_config. A step-up is unlikely on this path. A customer-present payment with a stored Customer Token also starts with createPaymentRequest API

, with the token in the Klarna-Customer-Token header.

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 method 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 when the transaction can change between the Payment Request and the authorize call and the customer stays in the checkout, so Klarna can return STEP_UP_REQUIRED with a new Payment Request instead of DECLINED. Omit it when nothing changes and the Partner authorizes from the completion webhook. 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 when the transaction can change) 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`	Conditional	Total amount of the Payment Request, including tax and discounts. Required unless `request_customer_token.scopes` is provided. Omit it only when the Payment Request creates a Customer Token without an initial charge.
`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.

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

Use the same Payment Account on createPaymentRequest API

and on authorizePayment API

. A different Payment Account on the authorize call returns STEP_UP_REQUIRED with result_reason set to ACQUIRING_CONFIGURATION_MISMATCH. Adding settlement_currency, or adding a Payment Account the Payment Request didn't have, isn't a mismatch.

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. An unsupported settlement currency returns a 400 validation error before authorization, reported on acquiring_config.settlement_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-[...]",

Info

The completed event can carry more than the token. After Express Checkout, shipping carries the address the customer chose in the Klarna Purchase Journey. Build the authorizePayment API

body in Step 4 from that address and the totals it produces, rather than replaying the values sent on the Payment Request. When the Payment Request also issues a Customer Token, klarna_customer carries it.

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	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_reason` is `AMOUNT_MISMATCH`, on `STEP_UP_REQUIRED` when `step_up_config` is included and on `DECLINED` otherwise.
`request_payment_transaction.payment_transaction_reference`	Recommended	The Partner's own reference for the Payment Transaction, used for reconciliation.
`supplementary_purchase_data`	Required	The final purchase details: the final `line_items` and the shipping address the customer ends up with. After Express Checkout, use the `shipping` returned on the completed Payment Request. The contractually required sub-fields (`line_items`, `purchase_reference`, `customer`, `shipping`) must be present. Sending the final values keeps the transaction eligible for the merchant protection program.
`acquiring_config`	Required	Routes the Payment Transaction to a Payment Account, and optionally requests the settlement currency. Use the same Payment Account as on the Payment Request: a different one returns `STEP_UP_REQUIRED` with `result_reason` set to `ACQUIRING_CONFIGURATION_MISMATCH`. Adding a Payment Account the Payment Request didn't have, or adding `settlement_currency` (ISO 4217), isn't a mismatch. An unsupported `settlement_currency` returns a `400` validation error. See Configure acquiring_config.
`step_up_config`	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_UP_REQUIRED` with a new Payment Request. Omit it when nothing changes and you authorize from the completion webhook. Set `customer_interaction_config.method = HANDOVER` and provide a `return_url`, plus an `app_return_url` 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_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 when `step_up_config` 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_reason` says why, for example `KLARNA_NETWORK_SESSION_TOKEN_EXPIRED`.	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. `result_reason` says why, for example `AMOUNT_MISMATCH` or `KLARNA_NETWORK_SESSION_TOKEN_EXPIRED`. 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

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

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.

Integrate Payment Presentation

Authorize customer-initiated transactions

Express Checkout integration

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)