Authorize the payment

Authorize payments with Klarna seamlessly by integrating the Payment Authorize API. This guide outlines how to receive and forward required data, call the API, and handle all possible response flows.

Integration overview

Once the customer selects Klarna at checkout and click on the Pay button:

The Partner sends a request to the Acquiring Partner to create a Klarna payment session that contains purchase details, klarna_network_session_token and klarna_network_data.
The Acquiring Partner forwards the required payment context data to Klarna’s Payment Authorization API including:
1. supplementary_purchase_data
2. step_up_config
3. request_payment_transaction
Klarna returns one of the following responses:
1. STEP_UP_REQUIRED – customer needs to go through Klarna's purchase journey, either return the klarna payment_request_id or payment_request_url to the Partner.
2. APPROVED – transaction is completed, proceed to confirmation and store payment_transaction_id.
3. DECLINED – payment was denied, inform the Partner that the payment could not be completed, the Partner should invite the customer to select another payment method.

Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include Klarna Network parameters that preserve session context as well as supplementary purchase data which improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience.

Accept Klarna Network data points

When Partners optimize their integration with Klarna, they are likely to have Klarna Network data points to share with the Acquiring Partner. These data points enable interoperability between the Boost Features and Payment Presentation or Payment Authorization.

Parameter	Purpose
`klarna_network_session_token`	Encodes Klarna-specific session context (e.g., preselected payment option, pre-qualification results).
`klarna_network_data`	Submit supplementary purchase data directly to Klarna

These ensure consistent customer and transaction context throughout the payment flow and must be forwarded unaltered to Klarna.

Enable interoperability for Payment Presentation

Enable interoperability for Payment Authorization

Implementation requirements

Accept the Klarna Network parameters in the Partner-facing payment request API.
Forward the Klarna Network parameters unmodified to Klarna’s Payment Authorization API.
Validation can and should be implemented, but it must not be more restrictive than what is specified in Klarna’s Payment Authorize API. Make sure that all special characters permitted by the API specification are accepted.

The Partner-facing field should be named klarna_network_session_token/klarna_network_data, ensuring that it’s easy for any Partner to identify and use.
The Acquiring Partner can validate the input based on the provided guidelines but must not modify it. The input must always be forwarded as received, without any interference.

Below an example of how Acquiring Partners can accept the Klarna Network parameters in their Payment request API endpoint.

Sample request

JSON

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "klarna_network_session_token": "eyJhbGciOiJ...",
      "klarna_network_data": "{\"content_type\":\"application/vnd.klarna.interoperability-data.v2+json\",\"content\":{\"payment_request\":{...}}}"
    }
  }
}

Supplementary purchase data

Supplementary Purchase Data refers to additional transaction details shared with Klarna that provide greater context about a purchase. These data points—such as line items, subscription details, or industry-specific attributes—help improve underwriting accuracy, fraud assessment, and the customer’s post-purchase experience. They may be required in certain industries and support multiple use cases, including better acceptance rates, enhanced fraud prevention, improved customer experiences within the Klarna app, and more effective risk monitoring.

Payment Authorize

POST:/v2/accounts/{partner_account_id}/payment/authorize

Show recommended

Parameter	Required	Description
`supplementary_purchase_data`	No	Provide additional details about the transaction to help reduce fraud risk and enhance transparency. Include only the specific fields you wish to update within `supplementary_purchase_data` in update requests. Klarna processes t... Show more
`-purchase_reference`	No	Used for storing the customer-facing order number. It will be displayed to customers on the Klarna app and other communications. It will also be included in settlement reports for the purpose of reconciliation. If you are a direct merchant... Show more
`-customer`	No	This object provides information about the customer based on their previous interactions with the merchant. These data points may be used by Klarna to simplify sign-up and during fraud assessment, as well as for underwriting purposes to pro... Show more
`--given_name`	No	Provide the given name (first name) of the person associated with the transaction. Klarna uses this value for customer communication, fraud assessment, and delivery validation. Ensure the name is accurate and matches the individual's legal... Show more
`--family_name`	No	Provide the family name (last name) of the person associated with the transaction. Klarna uses this value for customer communication, fraud assessment, and delivery validation. Ensure the name is complete and correctly reflects the recipien... Show more
`--email`	No	E-mail address. Regex ^(?=.{1,64}@.{1,255}$)(?:[a-zA-Z0-9!#$%&'+/=?^_`{\|}~\p{IsLatin}\p{N}\p{S}-&&[^<>]]+(?:\.[a-zA-Z0-9!#$%&'+/=?^_`{\|}~\p{IsLatin}\p{N}\p{S}-&&[^<>]]+)*\|"(?:[\x01-\x08\x0B\x0C\x0E-\x1F\x21\x23-\x5B\x5D-\x7F]\|\[\x01-\x09... Show more
`--email_last_verified_at`	No	Date of the most recent email verification done in ISO 8601 with timezone e.g. 2024-01-01T12:00:00Z
`--phone`	No	Provide the phone number in local format. Ensure the number includes at least one digit and only contains valid characters: +, digits, spaces, parentheses, periods, or hyphens. The system validates format based on the customer's country. Tr... Show more
`--phone_last_verified_at`	No	Date of the most recent phone verification done in ISO 8601 with timezone e.g. 2024-01-01T12:00:00Z
`--address`	No	Domicile address of the customer (billing address). Klarna will only use this as an indicator for fraud and to simplify sign-up. The address will not be used for underwriting and will not be persisted on created Payment Transactions. Klarna... Show more
`---street_address`	No	Provide the first line of the street address, including the primary information, such as street name and number. Treat the value as an opaque string, do not validate or infer its structure.
`---street_address2`	No	Provide the second line of the street address if additional address details are needed. Klarna uses this field to capture supplementary information such as apartment, suite, or unit numbers. Treat the value as an opaque string, do not valid... Show more
`---postal_code`	No	Provide the postal code formatted according to the rules of the specified country. Treat the postal code as an opaque string, do not parse or validate its format beyond country-specific requirements.
`---city`	No	Provide the city or town name for the address indicated. Treat the city name as an opaque string, do not validate or infer its structure.
`---region`	No	State/county/province/region formatted according to country. Mandatory for US and AU market. Validations according to ISO 3166-2 format, e.g. US-OH, US-NJ, AU-ACT, etc.

Showing 15 of 60

Here you can find all required parameters for this operation authorizePayment

Data requirements

Depending on the business type, certain supplementary_purchase_data fields are required under the Klarna Network Rules. However, purchase_reference, line_items, customer and shipping whenever available must always be submitted, as they enable transaction-level traceability, power Klarna’s fraud prevention and underwriting models, dispute handling, and ensure a consistent customer experience across Klarna’s ecosystem.

Step 2: Call Klarna’s Payment Authorization API

The Payment Authorize API is used to authorize payments on Klarna Network — whether they are one-time purchases, tokenized payments, token charges, or a final authorization following a step-up flow. All requests must include the applicable supplementary_purchase_data as defined by Klarna Network Rules.

A one-time payment represents the most common scenario, where the customer completes a single purchase with Klarna. The call may return an immediate authorization (APPROVED) or require additional customer interaction (STEP_UP_REQUIRED).

In the request to the Payment Authorize API Klarna Icon , specify the following parameters:

Payment Authorize

POST:/v2/accounts/{partner_account_id}/payment/authorize

Show recommended

Parameter	Required	Description
`partner_account_id`	Yes	Unique account identifier assigned by Klarna to the onboarded merchant

Here you can find all required parameters for this operation authorizePayment

SHELL

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: eyJhbGciOiJIU...' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": { .. },
        "klarna_network_data": "<serialized-json>",
        "request_payment_transaction": {
          "amount": 11800,
          "payment_option_id": "***",
          "payment_transaction_reference": "acquiring-partner-transaction-reference-1234"

Step 3: Handle the Payment Authorization result

The response schema is as follows:

When performing a one-time payment or token charge through the Payment Authorize API, Klarna returns a response that reflects the result of the payment authorization. Because this flow only includes a request_payment_transaction in the request, the response will always contain a corresponding payment_transaction_response object. The result field inside this object indicates the outcome of the authorization and determines the next step to perform.

The result has the following possible values:

Result	Description	Next step
`STEP_UP_REQUIRED`	This result is returned only if `step_up_config` was provided in the request and additional customer interaction is needed to complete the payment.	Read the `payment_request_id` and `payment_request_url` from the `payment_request` object, and launch the Klarna Purchase Journey for the customer to finalize authorization.
`APPROVED`	The payment authorization succeeded. A `payment_transaction` has been created and returned in the response.	Store the `payment_transaction_id` for post-purchase operations (such as capture or refund), and return a success indicator to the client.
`DECLINED`	The authorization failed (for example, due to fraud, credit, or risk policy). No transaction is created.	Return a failure indicator to the client.

Result: `STEP_UP_REQUIRED`

When Klarna cannot immediately create a Payment Transaction and a step_up_config was provided in the request, Klarna returns STEP_UP_REQUIRED with a payment_request. The partner must redirect the customer to Klarna’s purchase journey URL to complete authentication and payment option selection.

When the payment cannot be completed instantly, Klarna returns the payment_request details including the payment_request_id and payment_request_url which should be used to launch the Klarna Purchase Journey.

Sample payload

JSON

{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
    "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",

Result: `APPROVED`

When the payment authorization is approved, Klarna returns an APPROVED result and a newly created payment_transaction. 
The Acquiring Partner must store the payment_transaction_id for post-purchase operations (capture, refund, etc.) through the Payment Transactions API.

An APPROVED result means the payment has been authorized successfully without requiring further customer interaction.

Sample payload

JSON

{
  "payment_transaction_response": {
    "result": "APPROVED",
    "payment_transaction": {
      "payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-[...]",
      "payment_transaction_reference": "transaction-reference-1234",
      "amount": 11800,
      "currency": "USD",
      "payment_funding": {
        "type": "INVOICE",
        "details": { }
      },

Result: `DECLINED`

If Klarna cannot approve the payment, the API returns a DECLINED result without a payment_transaction. Partners should treat this as a final rejection unless instructed by Klarna to retry.

Sample payload

JSON

{
  "payment_transaction_response": {
    "result": "DECLINED",
    "result_reason": "PAYMENT_DECLINED"
  }
}

Manage payment transactions with Klarna Network

API & SDK references

Authorize a payment transaction.

Integration overview

Integration details

Step 1: Gather and forward payment context data

Accept Klarna Network data points

Supplementary purchase data

Step 2: Call Klarna’s Payment Authorization API

Step 3: Handle the Payment Authorization result

Result: `STEP_UP_REQUIRED`

Result: `APPROVED`

Result: `DECLINED`

Build the payment form

Handle step-up scenario

Integration overview

Integration details

Step 1: Gather and forward payment context data

Accept Klarna Network data points

Supplementary purchase data

Step 2: Call Klarna’s Payment Authorization API

Step 3: Handle the Payment Authorization result

Result: STEP_UP_REQUIRED

Result: APPROVED

Result: DECLINED

Build the payment form

Handle step-up scenario

Result: `STEP_UP_REQUIRED`

Result: `APPROVED`

Result: `DECLINED`