In a usual server-side payment integration with an Acquiring Partner, the Partner will start the payment flow when the customer decides to pay with a given payment method. In the case where the customer selects Klarna, the Partner will then send a request to the Acquiring Partner to create a payment session with Klarna as the selected payment method, forwarding to the Acquiring Partner the mandatory data points such as returning address, etc.

In this occasion, Acquiring Partners will have to integrate with Klarna's Payment Authorization API, which will either directly proceed to authorize a Payment Transaction or require the customer to go through Klarna's Purchase Journey.

Before calling the Payment Authorization API, it is required to receive certain data points from the Partner to ensure a full end-to-end integration between the Partner's checkout flow and Klarna's Purchase Journey.

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

The interoperability data points (interoperability_token and interoperability_data) ensure all information and context associated with a Payment Transaction is preserved throughout the journey of a customer.

Klarna's interoperability_token and interoperability_data must be accepted through the Acquiring Partner's server-side API endpoints used by their Partners to initiate the payment.<br />

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

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "interoperability_token": "eyJhbGciOiJ...",
      "interoperability_data": "..."
    }
  }
}

As those parameters can change over time and are versioned so that the third party integration continues to work, Acquiring Partners need to respect these guidelines if they wish to validate parameters:

Supplementary Purchase Data consists of  datapoints associated with the payment that helps Klarna optimize the Purchase Journey and improve acceptance rate. These datapoints can be forwarded to Klarna through:

• The interoperability_data field mentioned previously
• The Acquiring Partner's own API

When Acquiring Partners allow Partners to provide additional data points directly through their APIs, such as line items or L2/L3 data for Card Network optimization, they must forward the same data to Klarna using supplementary_purchase_data object of the Payment Authorization API.

​Read more about Supplementary Purchase Data here.

• When Partners optimize their integration with Klarna, they are likely to have an interoperability_token to share with the Acquiring Partner. The Acquiring Partner’s payment session API should expose a parameter for this as seen previously.
• The Acquiring Partner will use this to trigger a server side call to the Klarna's Payment Authorize API, using the payment details provided by the Partner.

In the request to the Payment Authorize API, the Acquiring Partner will specify the following parameters:

Path parameter

Header parameter

Request body

Below an example request body for the Payment Authorize API. (interoperability token sent as an HTTP header parameter)

{
  "currency": "USD",
  "supplementary_purchase_data": { .. },
  "interoperability_data":  "<serialized-json>",
  "request_payment_transaction": {
    "amount": 11800,
    "payment_transaction_reference": "acquiring-partner-transaction-reference-1234"
  },
  "step_up_config": {
    "payment_request_reference": "acquiring-partner-request-reference-1234",

The Payment Authorize API can yield 3 different outcomes depending on the transaction and the consumer:

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

Sample response - APPROVED

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

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

Sample response - DECLINED

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

When a Payment Transaction could not be immediately created by Klarna and a step-up configuration was provided in the call to the Payment Authorization API, the Step-up scenario will be triggered and the Acquiring Partner will receive a STEP_UP_REQUIRED result.

In such scenario, the Payment Authorization API returns a Payment Request in the response. The expectation is that the customer will go through Klarna’s Purchase Journey to complete the payment, usually triggering authentication and payment option selection. The required work to properly make the step-up scenario work is outlined in the next section.

The following parameters are present in the response to the request.

Response body

Sample response - STEP_UP_REQUIRED

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