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

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

1. The customer clicks the Klarna Payment button.
2. The initiate JavaScript function attached to the Klarna Payment button is triggered.
3. Acquiring Partner’s backend calls Klarna’s Payment Authorize API.
4. Klarna returns STEP_UP_REQUIRED and a payment_request_id
5. The initiate function returns a promise resolving to the the paymentRequestId object.
6. The customer enters the Klarna Purchase Journey and completes authentication/payment selection.
7. Klarna redirects the customer back to the Partner.

To support the step-up scenario, Acquiring Partners must define return URLs when calling the Payment Authorize API.

• return_url: if the Klarna purchase flow is launched in a web environment, Klarna will redirect the customer to this URL after the customer finishes their interaction with Klarna, either by approving or aborting the purchase flow. This could either be a URL from the Acquiring Partner who will handle the redirection logic or a URL collected from the Partner.

• app_return_url: The customer may be redirected to a third party app (bank app) or the Klarna app during the Klarna purchase journey on mobile environments. This URL enables Klarna to return the customer back to the Partner’s mobile app.

Implementation notes for Partners

• Ensure the app_return_url is set up to register a URL scheme (e.g., yourapp://klarna) or universal link that resumes the payment flow.
• Klarna uses this URI after the customer completes a native app-based flow (e.g., biometric auth in a bank app or Klarna app login).
• Partners are expected to open the integrating mobile application in its last state (no state changes or deeplink navigations).

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

Sample request

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 '{
        ...
        "step_up_config": {
          "payment_request_reference": "acquiring-partner-request-reference-1234",
          "customer_interaction_config": {
            "method": "HANDOVER",

When step-up is required, the Payment Authorize API response includes a payment_request_id that must be passed to the frontend SDK:

{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "payment_request": {
    ...
    "state_context": {
      "customer_interaction": {
        "method": "HANDOVER",
        "payment_request_id": "krn:payment:eu1:request:..."

The initiate function from the Klarna Payment button instance will return a promise that resolve to an object with the paymentRequestId:

Sample code

const buttonConfig = {
  initiate: () => {
    // call to Klarna Payment Authorize API returns STEP_UP_REQUIRED
    return { paymentRequestId: "krn:payment:eu1:request:5eb1.." }
  },
  initiationMode: "DEVICE_BEST",  // Device-optimized payment initiation
}

// Render and mount the button with the assigned configuration
paymentPresentation.paymentButton.component(buttonConfig).mount("#klarna-button-container");

The initiationModeis a parameter which controls how the Klarna Purchase Journey is launched (redirect / modal window) on different devices (mobile/desktop/native):

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.

After the customer finishes or aborts the Klarna purchase flow—whether on web or in the app—Klarna does the following:

1. Redirect the customer to return_url: Klarna redirects the customer to the return_url specified in the customer_interaction_config object, except for when the popup experience was applied and the customer aborts the purchase flow.
2. Issuance of payment_token upon completion: Klarna issues 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.

OPTIONAL: Listens to Klarna Web SDK events

The KlarnaPayment SDK interface enables Acquiring Partners to register event handlers to follow the different stages of the purchase and provide the best user experience to consumers.

​​​These event handlers allow you to access various properties of the ongoing paymentRequest as defined in the below table. This access allows developers to handle payment requests with greater precision and awareness of the payment’s current state.

​Sample code: