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: Klarna will always redirect the customer to this URL on a successful authorization. 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.

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

Sample request

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

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.

If the Klarna Purchase Journey requires a handover to another app (e.g., Klarna app, bank app), Klarna will use the provided app_return_url to return the customer to the Partner’s mobile app.

Implementation notes for Partners:

• Ensure the app 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).

After the customer completes Klarna’s Purchase Journey, whether via web browser or mobile app, Klarna performs two critical actions:

1. Redirection to return_url : Klarna redirects the customer to the return_url provided in the customer_interaction_config object. This URL should guide the customer back into your or the Partner’s frontend experience.
2. Issuance of payment_token: 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.

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:

• Configure step_up_config with valid return_url and app_return_url when calling the Payment Authorize API
• Handle Klarna’s STEP_UP_REQUIRED response by extracting the payment_request_id and passing it to the frontend.
• Prefer internal return_url to finalize transaction before redirecting to Partner UI.
• Register SDK event handlers (complete, abort, error).