With a previously created payment:customer_not_present scope token, Partners can initiate Klarna payments for subscriptions:

  1. The Partner sends a request to the Acquiring Partners to create a Klarna payment session that contains purchase details, customer_token or the token equivalent issued by the Acquiring Partner,interoperability_token and interoperability_data.
  2. The Acquiring Partner forwards the required payment context data to Klarna’s Payment Authorization API including:
    1. customer_token
    2. supplementary_purchase_data
      1. subscriptions
    3. step_up_config
    4. request_payment_transaction
  3. Klarna returns one of the following responses:
    1. APPROVED – Transaction is completed, proceed to confirmation and store payment_transaction_id.
    2. DECLINED – If the payment is denied, Acquiring Partners have to inform the Partner that the payment could not be completed.

Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include interoperability 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.

Interoperability parameters

When Partners optimize their integration with Klarna, they are likely to have interoperability parameters to share with the Acquiring Partner.

ParameterPurpose

interoperability_token

Encodes Klarna-specific session context (e.g., preselected payment option, pre-qualification results).

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

Implementation requirements

  • Accept the interoperability parameters in the Partner-facing payment request API.
  • Forward the interoperability 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 APIAPI. Make sure that all special characters permitted by the API specification are accepted.

The Partner-facing field should be named either klarna_interoperability_token/klarna_interoperability_data or interoperability_token/interoperability_data in a Klarna-specific context, 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.

Sample request

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

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

Supplementary purchase data

Supplementary purchase data improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience. It includes structured information such as line items, L2/L3 data for Card Network optimization and other transaction context.
Acquiring Partners may receive this data from the Partner in two ways:

  1. Embedded in interoperability_data
    1. No parsing needed. Just forward it as-is.
  2. As individual fields in the Acquiring Partner’s API
    1. The Acquiring Partner is responsible for mapping existing fields in their payment API with the fields defined in the supplementary_purchase_dataAPI object when calling the Payment Authorize APIAPI.

Acquiring Partner must collect and forward data that aligns with Klarna’s Supplementary Purchase Data package by utilizing their existing schema.
Acquiring Partner should not add additional fields of the supplementary purchase data in their APIs to support Klarna. Instead, they must ensure that the interoperability_dataAPI and its required structure are properly implemented.

In both cases, the Acquiring Partner is responsible for ensuring that the data provided by the Partner is accurately forwarded to Klarna. Partners should not be asked to resubmit the same information through multiple mechanisms.

Read more about Supplementary Purchase Data here.

Payment Authorize
API
POST:/v2/accounts/{partner_account_id}/payment/authorize
Show recommended
ParameterRequiredDescription
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
API

Sample Subscription request with existing token

SHELL
curl -X POST "https://api-global.klarna.com/v2/payment/authorize" \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Interoperability-Token: eyJhbGciOiJIU...' \
  -H 'Klarna-Customer-Token: krn:customer-token:123' \
  -d '{
    "currency": "USD",
    "supplementary_purchase_data": {
      "subscriptions": [{
        "subscription_reference": "MONTHLY PLAN",

For a customer not present token charge the Payment Authorize API can yield 2 different outcomes depending on the transaction and the consumer:

ResultDescription

APPROVED

The Payment Authorization is approved without additional customer interaction. A Payment Transaction is created and contained in the response.

DECLINED

The payment cannot proceed due to reasons such as fraud, final decline or risk concerns.

Approved Payment Transaction

When the request is successful, a Payment Transaction is created on Klarna Network and will be available for post-purchase operations through the Payment Transactions API. No further customer interactions are needed and the Acquiring Partner can directly inform their partners that the payment session is completed and that the customer can be redirected to the order confirmation page.

Acquiring Partners must store the Klarna payment_transaction_id for future operations on the transaction through the Payment Transactions API, such as capture and refund. The Acquiring Partner will receive the following parameters in the response.

Response body

The response will contain a payment_transaction_responseAPI object with the following parameters:

Parameter nameDescription

resultAPI

The result parameter which specifies the outcome of the authorization.
In case of a successful Authorization the result will be set to APPROVED

payment_transactionAPI

The payment_transaction object represents a single payment transaction
This object is only returned if the payment_transaction_response.result is set to APPROVED
The payment_transaction_idAPI  returned is necessary to manage the Payment Transaction through the Payment Transaction APIAPI.

Sample response - APPROVED

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

Declined authorization

If a transaction could not be approved by Klarna and step-up scenario cannot be triggered (due to missing configuration or for permanent decline), the Acquiring Partner will receive a decline. Declines should not be replayed without change of context.
The Acquiring Partner should inform the Partner that the payment could not be completed and the Partner should invite the customer to select another payment method.

Response body

The response will contain a payment_transaction_responseAPI object with the following parameters:

Parameter nameDescription

resultAPI

The result parameter which specifies the outcome of the authorization.
In case of a decline, the result will be set to DECLINED

Sample response - DECLINED

JSON
{
  "payment_transaction_response": {
    "result": "DECLINED"
  }
}