Once the customer wants to pay with Klarna in-store:

1. The Partner sends a request to the Acquiring Partner to create a Klarna payment session.
2. The Acquiring Partner forwards the required payment context data to Klarna’s Payment Authorization API.
3. Klarna returns one of the following responses:
   1. APPROVED – transaction is completed.
   2. STEP_UP_REQUIRED – customer needs to go through Klarna's Purchase Journey
   3. DECLINED – payment was denied.

Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include store specific datapoints to determine the most granular data about purchase location as well as supplementary purchase data which improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience.

To confirm that purchase is made via a physical store Klarna needs to receive the most granular information about purchase location.

Implementation requirements

• Accept the store parameters in the Partner-facing payment request API.
• Forward the store parameters unmodified to Klarna’s Payment Authorization API.

Sample request

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

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

Store parameter validation guidelines

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:

Point of checkout with existing store_id / store_reference of physical store

Physical store

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

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.

Sample request

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

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

Parameter validation guidelines

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 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_data object when calling the Payment Authorize API.

​

Read more about Supplementary Purchase Data here.

In the request to the Payment Authorize API, Acquiring Partners must specify the following parameters:

Path

Header

Body

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

curl https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/authorize \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": { .. },
        "interoperability_data":  "<serialized-json>",
        "request_payment_transaction": {
          "amount": 11800,
          "payment_transaction_reference": "acquiring-partner-transaction-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 request is completed and that the receipt can be printed.

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_response object with the following parameters:

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

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

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

• Accept and forward granular data about purchase location
• Accept and forward interoperability_token and interoperability_data from the Partner, unmodified.
• Map relevant fields from your API to Klarna’s Payment Authorize API, including:
  • supplementary_purchase_data
  • step_up_config
  • request_payment_transaction
• Call Klarna’s Payment Authorization API with all parameters provided by Partners.
• Handle API responses:
  • APPROVED: proceed to confirmation and store payment_transaction_id
  • STEP_UP_REQUIRED: either return the klarna payment_request_id or payment_request_url to the Partner
  • DECLINED: inform the Partner that the payment could not be completed, the Partner should invite the customer to select another payment method.