Klarna Docs - POS checkout integration - Handle step-up scenario for in-store

Help customers complete in-store payments securely by handling Klarna’s step-up authentication using the Purchase Journey. This guide breaks down how to integrate and respond when a step-up flow is triggered by Klarna’s Payment Authorize API.

Overview

When Klarna requires additional verification from the customer (e.g., login, authentication, or payment method selection), it returns a Payment Request in the response to the Payment Authorize API call.

The Acquiring Partner backend must detect this and return the necessary data points to Partners so they can start the Klarna’s Purchase Journey with the customers.

As shown in the below diagram, the high level flow is the following:

Partner submits a Klarna payment request to the Acquiring Partner.
Acquiring Partner calls the Klarna Payment Authorize API.
Klarna returns a step-up required response containing:
1. payment_request_id
2. qr_code
  1. image_url
  2. target_url
Customer scan QR and enters Klarna’s Purchase Journey.
Customer completes authentication/payment method selection.
Partner listens to the Klarna's Webhooks.
When Webhook is received confirming that customer authorized the purchase then Partner sends final Authorize request to place an order.

Step 1: Configure Parameters (Step Up, Point of Checkout and Point of Transaction)

Acquiring Partners must include a step_up_config object when calling Klarna’s Payment Authorize API, and specify the following parameters:

Parameter name	Description
`payment_request_reference`	Reference to the payment session or equivalent resource on the Acquiring Partner's side. Helps match Klarna payment requests with internal records.
`customer_interaction_config`	Configuration properties for supporting step-up scenario. It contains: `method` (set to "QR_CODE")
`point_of_checkout`	Information about where the purchase was made. One of store_id (onboarded) store_reference (onboarded) store (non-onboarded) A store can be classified as one of three types: physical store, website, or mobile app. To ensure that a purchase is recognized as an in-store transaction, please provide the `store_id` or `store_reference` corresponding to a store with the type set to `PHYSICAL_STORE`. Alternatively, if such a store does not yet onboarded, please create a new store entry with the type designated as `PHYSICAL_STORE`. Example:
`point_of_transaction`	Information about the most granular location data about the purchase. Can be of three possible types: website, mobile app and terminal. To ensure that a purchase is recognized as an in-store transaction, please provide the type `TERMINAL` with `terminal_reference` Example:

Sample request

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-Interoperability-Token: eyJhbGciOiJIU...' \
  -d '{
        "currency": "USD",
        "supplementary_purchase_data": { .. },
        "interoperability_data":  "<serialized-json>",
        "request_payment_transaction": {
          "amount": 11800,

Step 3: Extract & Return Mandatory Klarna Parameters

Whenever the step-up scenario is triggered, the Payment Authorize API response will contain

payment_request_id : The unique Klarna identifier for the payment request
qr_code: Object containing image_url with QR code image and target_url if partner wants to customize QR code size

Sample response

JSON

{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    ...
    "state_context": {
      "customer_interaction": {
        "method": "QR_CODE",
        "qr_code": {

Forwarding Klarna Parameters to the Partner

Acquiring Partners should extract and expose these parameters in their API response to the Partner system. This enables the Partner to:

Redirect the customer to Klarna’s Purchase Journey directly
Use Klarna’s Web SDK to start the purchase flow

JSON

{
  "status": "pending",
  "klarna": {
    "payment_request_id": "krn:payment:eu1:request:552603c0-fe8b-4ab1-aacb-41d55fafbdb4",
    "payment_request_url": "https://pay.test.klarna.com/eu/requests/6bbf6775-[...]/start"
  }
}

Use of an intermediate redirect

In some implementations, the Acquiring Partner may return a general-purpose redirect_url under their domain for all payment methods. Partners then use this URL to trigger a client-side redirect to Klarna’s payment_request_url.

JSON

{
  "status": "pending",
  "redirect_url": "https://acquiringpartner.com/payment/xxxxx"
}

Step 4: Customer Starts the Klarna’s Purchase Journey

When QR code is presented to customer on a a digital consumer-facing screen, customer scans a QR and starts purchase Journey.

The Klarna Purchase Journey enables the customer to:

Authenticate with Klarna (via login, OTP, etc.)
Choose the payment method (Pay in N, Pay Later, etc)
Accept the payment.

Phone collection in the Klarna Purchase Journey

Implementation notes for Partners:

Ensure the store has a digital consumer-facing screen, such as a self-checkout, an iPad, or a mobile checkout device, on which the QR codes can be displayed.

Step 5: Redirection After Acceptance

After the customer completes Klarna’s Purchase Journey, whether via web browser or mobile app, Klarna displays a message to customer saying "Your payment was authorized by Klarna. You will get a confirmation from the store." Klarna will send a webhook to partner confirming customer authorized the purchase and issue a payment_token to the Acquiring Partner, which is required to finalize the payment. This part will be covered in the following section - Monitor the payment request state.

Summary checklist for Acquiring Partners

Configure step_up_config with QR_code method when calling the Payment Authorize API
Make sure that point_of_checkout contains one of:
- store_id of previously onboarded physical store
- store_reference of previously onboarded physical store
- store details of physical store. Note: in this case store will be onboarded to Klarna.
Handle Klarna’s STEP_UP_REQUIRED response by extracting the payment_request_id and qr_code.
Forward these values to the Partner system for frontend use.
Once customer scan a QR display a waiting visualisation in a kiosk or on a customer-facing display until customer finishes purchase journey on customer's phone.
Wait for a webhook confirming customer finishes the journey.
Make a final request to place an order with Klarna.