Payment Authorization for Server-side integration

Learn how to authorize a Payment Transaction with Klarna using a server-side-only integration when the customer is present during checkout. As an Acquiring Partner, you'll collect payment context from a Partner, call the authorizePayment endpoint, handle all authorization outcomes, manage step-up flows, and finalize the Payment Authorization.

Before starting, complete the following steps:

• Complete the Payment Presentation integration.

Then ensure you have:

• A valid Partner Account onboarded with Klarna
• Backend capability to receive and process Klarna webhooks
• Partner-facing APIs capable of forwarding redirect URLs and Klarna data without modification

Once the customer selects Klarna at checkout and clicks the Pay button:

1. 1.
   The Partner initiates Payment Authorization through the Acquiring Partner
2. 2.
   The Acquiring Partner forwards the payment context to Klarna by calling the authorizePayment endpoint
3. 3.
   Klarna evaluates the request and returns one of the following results:

   1. 3.1.
      APPROVED
   2. 3.2.
      DECLINED
   3. 3.3.
      STEP_UP_REQUIRED
4. 4.
   The Acquiring Partner handles the result and returns the outcome to the Partner
5. 5.
   If step-up is required, the customer completes the Klarna Purchase Journey
6. 6.
   The Acquiring Partner finalizes the authorization and returns the final result

Update the Partner-facing API to collect the following data points from the Partner for customer-initiated payment scenarios:

Requirements

• Use exact parameter names klarna_network_session_token and klarna_network_data in the Partner-facing API to ensure Partners can easily identify and use them.
• Forward all parameters unmodified to Klarna.
• Parameter validation must not be more restrictive than Klarna's authorizePayment.
• Support all printable UTF-8 characters.
• Supplementary purchase data handling:

  • Map your existing Partner-facing fields (line items, customer billing address, shipping, purchase reference) into supplementary_purchase_data when calling Klarna
  • Don't add new Partner-facing fields "just for Klarna" if you already have equivalent fields in your existing schema. Avoid forcing Partners to submit the same data twice using parallel structures

The authorizePayment endpoint is used to authorize a Payment Transaction with Klarna, for both customer-initiated and Partner-initiated scenarios.

• Call the authorizePayment endpoint and forward the complete payment context, including:

  • Amount and currency
  • Supplementary purchase data
  • Klarna parameters
  • Customer return URLs
• Configure step_up_config with HANDOVER to allow Klarna to trigger customer interaction when required.

In the request to the authorizePayment endpoint, specify the following parameters:

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/authorize \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Customer-Token: krn:partner:us1:test:identity:customer-token:ACZawkw7-2[...]' \
  -H 'Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": {
          "purchase_reference": "order-7f3a9b2e",
          "line_items": [
            {
              "name": "Wireless Bluetooth Headphones",

When performing customer-initiated authorization through the authorizePayment endpoint, Klarna returns a payment_transaction_response object. The result field inside this object indicates the outcome and determines your next action.

The result has the following possible values:

Here's the high-level diagram of the Payment Authorization results and resources it produces:

The response schema is as follows:

{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    "payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-[...]",
    "payment_request_reference": "acquiring-partner-request-reference-1234",
    "amount": 11800,
    "currency": "USD",
    "state": "SUBMITTED",
    "expires_at": "2025-01-02T13:00:00Z",
    "created_at": "2025-01-01T12:00:00Z",

Acquiring Partners must include return URLs in the step_up_config when calling authorizePayment to enable the step-up scenario.

These URLs, set inside the customer_interaction_config object, tell Klarna where to redirect the customer after they complete or stop the purchase journey.

If 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. This can be a URL managed by the Acquiring Partner (which handles redirection logic) or one collected directly from the Partner.

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

Partners must register a URL scheme (e.g., yourapp://klarna) or a universal link that resumes the payment flow. Klarna invokes this URL after the customer completes a native app-based step, such as biometric authentication or Klarna app login. Partners are expected to resume the mobile app in its last state without applying state changes or deep link navigations.

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

Map the Klarna authorization result to the Partner-facing API response according to the authorization outcome. The response may include a payment_request_url and/or a klarna_network_response_data parameter.

Requirements

• payment_request_url MUST be returned directly to the Partner in an existing field and MUST NOT be wrapped or hidden behind Acquiring Partner-managed redirects.
• Use exact parameter name klarna_network_response_data in the Partner-facing API to ensure Partners can easily identify and use the parameter. Treat this value as an opaque string; do not validate or infer its structure.

Below are examples of how Acquiring Partners can return the klarna_network_response_data parameter in their Partner-facing APIs depending on the authorization outcome.

{
  "payment_id": "pr_27234RBQD9NAKD032BN",
  "amount": 17800,
  "currency": "USD",
  "status": "open",
  "url": "https://pay.test.klarna.com/na/requests/6bbf6775-[...]/start",
  ...
  "additional_data": {
    "klarna_network_response_data": "{\"content_type\":\"vnd.klarna.network-data.v1+json\",\"content\":{\"operation\":\"payment_request\",\"response\":{\"result\":\"STEP_UP_REQUIRED\",\"payment_request\":{\"payment_request_id\":\"krn:payment:us1:request:552603c0-fe8b-4ab1-[...]\",\"payment_request_url\":\"https://pay.test.klarna.com/na/requests/6bbf6775-[...]/start\"}}}}"
  }
}

Acquiring Partners should expose Klarna's payment_request_url directly to Partners rather than routing through an Acquiring Partner-owned URL.

Using an intermediate redirect under the Acquiring Partner's domain causes the following issues:

When step-up is triggered, authorizePayment returns a STEP_UP_REQUIRED result along with a Payment Request containing the payment_request_url and klarna_network_response_data which the Partner needs in order to launch the Klarna Purchase Journey, either through a redirect or a pop-up experience.

The purchase journey allows the customer to authenticate with Klarna (via login, one-time passwords, etc.), choose a payment method, and accept the payment.

Phone collection in the Klarna purchase journey

Upon completion:

• Klarna redirects the customer to the return_url in customer_interaction_config, except when a pop-up experience is used and the customer stops the flow.
• Klarna issues a klarna_network_session_token to the Acquiring Partner to finalize the payment.

This step only applies when the authorizePayment endpoint returns STEP_UP_REQUIRED.

To retrieve the required token(s), Klarna provides multiple integration methods. Subscribing to Klarna webhook events is required and may be combined with additional methods to improve resilience.

Using webhooks ensures reliable completion handling, particularly when the customer closes the browser before returning, network interruptions occur during redirects, or post-processing is required before notifying the customer.

The klarna_network_session_token represents the Klarna session context and must be included in the Klarna-Network-Session-Token header when calling the Payment Authorize API.

Partners can obtain this token through:

• Step-up completion: Issued after a customer completes the Klarna Purchase Journey, used to finalize the Payment Authorization.
• Customer token exchange or prequalification flows: Obtained through other Klarna mechanisms, enabling fresh authorization requests (for example, Partner-initiated payments using a Customer Token).

Subscribe to the payment.request.state-change.completed webhook event using the Klarna webhook guidelines. Klarna sends this event when the Payment Request reaches the COMPLETED state.

This event indicates that the customer has finished the step-up interaction and that the Acquiring Partner can proceed with finalizing the authorization.

Sample payload

{
  "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-[...]",
    "webhook_id": "krn:partner:global:notification:webhook:120e5b7e-abcd-4def-[...]",
    "live": false

As an alternative method, retrieve the Klarna token(s) by calling the readPaymentRequest .

Once the Payment Request reaches the COMPLETED state, the token(s) are available in the state_context object of the Payment Request.

Sample payload

{
  "payment_request_id": "krn:payment:us1:request:552603c0-fe8b-4ab1-[...]",
  "state": "COMPLETED",
  "previous_state": "IN_PROGRESS",
  "state_context": {
    "klarna_network_session_token": "krn:network:us1:test:session-token:eyJhbGciOiJIU..."
  },
  "expires_at": "2025-02-26T17:25:34.534721775Z",
  "created_at": "2025-02-24T17:25:34.534721775Z",
  "updated_at": "2025-02-24T17:25:34.534721775Z",
  "payment_request_reference": "acquiring-partner-request-reference-1234",
  "amount": 11800,

After receiving the klarna_network_session_token from webhook or polling, finalize the authorization by calling the Payment Authorize API again with the new token.

Call authorizePayment using:

• The newly obtained klarna_network_session_token in the Klarna-Network-Session-Token request header
• The same payment context (amount, currency, supplementary_purchase_data, klarna_network_data) used in the initial authorization
• The same payment_transaction_reference to link the requests Example finalization request:

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/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",
        "supplementary_purchase_data": { ... },
        "klarna_network_data": "{\"content_type\":\"vnd.klarna.network-data.v1+json\",\"content\":{\"operation\":\"payment_request\",\"request\":{\"supplementary_purchase_data\":{...}}}",
        "request_payment_transaction": {
          "amount": 11800,
          "payment_option_id": "S0xBUk5BXzE3NzI3MjQ5MTQzMjk=",
          "payment_transaction_reference": "backend-transaction-ref-12345"

When finalization succeeds, Klarna returns APPROVED with the payment transaction:

{
  "payment_transaction_response": {
    "result": "APPROVED",
    "payment_transaction": {
      "payment_transaction_id": "krn:payment:us1:transaction:791bbb7b-813a-[...]",
      "amount": 11800,
      "currency": "USD",
      "payment_pricing": {...},
      "payment_funding": {
        "type": "GUARANTEED",
        "state": "FUNDED"
      }

Map the Klarna authorization result to the Partner-facing API response and return the klarna_network_response_data.

Requirements

• Treat this value as an opaque string; do not validate or infer its structure.
• Use exact parameter name klarna_network_response_data in the Partner-facing API to ensure Partners can easily identify and use the parameter
• All returned data MUST be forwarded without modification. Below is an example of how Acquiring Partners can return the Klarna Network Response Data parameter in their Partner-facing APIs.

{
  "payment_id": "pr_27234RBQD9NAKD032BN",
  "amount": 17800,
  "currency": "USD",
  "status": "completed"
  ...
  "additional_data": {
    "klarna_network_response_data": "{\"content_type\":\"vnd.klarna.network-data.v1+json\",\"content\":{\"operation\":\"payment_request\",\"response\":{\"result\":\"APPROVED\",\"payment_transaction\":{\"payment_transaction_id\":\"krn:payment:us1:transaction:791bbb7b-813a-[...]\"}}}}"
  }
}

After implementing Payment Authorization, explore these related topics:

• Manage Payment Transactions - Capture, refund, and cancel authorized payments