Once the customer has selected Klarna and decided to proceed to the payment with Klarna, Acquiring Partners are expected to authorize the payment with Klarna and allow the customer to go through Klarna's Purchase Journey.

The following sequence applies:

1. Customer clicks on the Klarna Payment button
2. The javascript function attached to the button click handler initiate is triggered
3. Acquiring Partner’s backend call Klarna’s Payment Authorize API
4. Klarna returns one of the following responses:
   
   • APPROVED – transaction is completed.
   
   • STEP_UP_REQUIRED – customer needs to go through Klarna's Purchase Journey
   
   • DECLINED – payment was denied.
   
5. The javascript function attached to the initiate button click handler returns a promise resolving to the authorization result

As described in the previous section, once the customer has selected the Klarna payment option in the payment selector, the Acquiring Partner will need to render the Klarna Payment Button.

The Acquiring Partner will need to configure paymentButton component from the paymentPresentation instance with the following attributes:

• initiate button click handler: attach a function which triggers your backend to call Klarna’s Payment Authorize API and return a promise resolving to the authorization result.
• initiationMode: This parameter controls how the Klarna Purchase Journey is launched (redirect / pop up window) on different devices (mobile/desktop/native)

Sample code

const buttonConfig = {
  initiate: () => {
      return fetch('/your-api/authorize-payment')
        .then(response => response.json());
  },
  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 initiate button click handler attribute from the SDK requires the Acquiring Partner to call Klarna's Payment Authorize API and return the results as a promise to the client-side.

• When Partners optimize their integration with Klarna, they are likely to have interoperability data points to share with the Acquiring Partner.
• The Acquiring Partner’s Checkout session API should accept interoperability_token and interoperability_data  parameters and if provided they must be forwarded when calling Klarna's Payment Authorize API.

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)

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

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

Back to the SDK the function attached to the initiate handler returns a promise which should resolve to an object with an optional returnUrl to redirect the customer to a success page.

const buttonConfig = {
  initiate: () => {
    //call to Klarna Payment Authorize API returns an APPROVED transaction
    return { returnUrl: "https://acquiringpartner.com/success" }
  },
  initiationMode: "DEVICE_BEST",  // Device-optimized payment initiation
}

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

In this scenario as the consumer clicks on the Klarna Payment button, the transaction will be immediately approved and the consumer will be redirected to the order confirmation page.

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

Back to the SDK the function attached to the initiate handler returns a promise which should resolve to an object with an optional returnUrl to redirect the customer in case of a declined transaction.

const buttonConfig = {
  initiate: () => {
    //call to Klarna Payment Authorize API returns an DECLINED transaction
    return { returnUrl: "https://acquiringpartner.com/failure" }
  },
  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 Acquiring Partner should inform the Partner that the transaction could not be completed and the Partner should invite the customer to select another payment method.

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

Back to the SDK the function attached to the initiate handler returns a promise which should resolve to an object containing the paymentRequestId generated as part of the step up response.Back to the SDK the function attached to the initiate handler returns a promise which should resolve to an object containing the paymentRequestId generated as part of the step up response.

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");

In this scenario as the consumer clicks on the button, the Klarna Purchase journey will be triggered. This will be covered in details in the next section - Handle Step-up scenario.

• Render the Klarna Payment Button using Klarna SDK and configure the initiate handler.
• On button click, trigger a call to your backend to initiate Klarna's Payment Authorization API.
• Forward interoperability_token and interoperability_data if provided by the Partner, unmodified.
• Map relevant fields from your checkout session API to Klarna’s Payment Authorize API, including:
  
  • supplementary_purchase_data
  
  • step_up_config
  
  • request_payment_transaction
  
• Handle Klarna's response:
  
  • APPROVED: redirect customer to success page and and store payment_transaction_id
  
  • DECLINED: redirect to failure page or offer alternative payment methods
  
  • STEP_UP_REQUIRED: launch Klarna Purchase Journey via SDK