As seen previously, upon calling Klarna's Payment Authorization API it is possible to trigger a step-flow. In such scenario, the Payment Authorization API returns a Payment Request in the response. The expectation is that the consumer will go through Klarna’s Purchase Journey to complete the payment, usually triggering authentication and payment option selection.

The Payment Request is the resource used to let the consumer go through Klarna's Purchase Journey. For this to happen, Acquiring Partners have to:

1. Properly configure the step up configuration upon calling Payment Authorization API
2. Expose data points for the Partner to be able to redirect the customer to Klarna's Purchase Flow

To create a Payment Request, Acquiring Partners must configure multiple properties based on their integration. These properties depend on the Partner's own implementation and require specific values to be provided to Klarna through the Acquiring Partner's APIs:

• A return_url where the customer is redirected after approving the payment.
• An app_return_url used when redirecting the customer to a mobile banking application.

The Acquiring Partner's APIs must then return the following parameters to the Partner:

• The URL that can be used to redirect the customer to the Purchase Journey.
• The identifier that can be used to complete the Payment Request via Klarna's SDKs
• The Payment Request Data that can be used to receive additional data for enterprise use cases.

For Partners to be able to ensure a seamless experience across different ecosystems, Klarna supports multiple integration patterns that require data points sent by Partners:

Klarna needs to be able to return the consumer to the Partner through an HTTP redirection. This can be achieved either through the Acquiring Partner’s usual integration mechanism, or by allowing the Partner to explicitly submit a Klarna redirect URL and forward it on the configuration.

When the Acquiring Partner is already asking a suitable return_url from the Partner, it is advised to not ask for a second one as this would increase the minimal integration requirements for Klarna to work.

Klarna needs to be able to handover to a Mobile Application and return back. In many flows happening on a mobile application, Klarna will try to handover to its own application or any other Mobile Bank Application for approvals.

For the experience to work, Partners have to be able to define an Mobile Application return URL. This parameter can either be generic to the Acquiring Partner’s API or specific to Klarna.

When the Acquiring Partner is already asking a suitable app_return_url from the Partner, it is advised to not ask for a second one as this would increase the minimal integration requirements for Klarna to work.

To build the step-up configuration, Acquiring Partners have to build the different values required using the values received from the Partners and their own infrastructure.

As previously mentioned, return_url should be either the Acquiring Partner's own mechanism, or directly the value coming from the Partner.

It is possible to add Placeholders in the return_url. Read more about it in the section to track the Payment Request state.

In most cases, the app_return_url is directly owned by the Partner. But similarly, if the Acquiring Partner is already requesting such a parameter, then it can be directly re-used.

Parameters

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

Sample response

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

​While the Partner integration is responsible for guiding the customer to complete the Payment Request, Acquiring Partners must provide the required parameters to enable this process.

Acquiring Partner has to extract customer_interaction.payment_request_id and customer_interaction.payment_request_url from payment_request.state_context as well as payment_request.payment_request_data from the response and forward it back on their response to the Partner.

The Partners will then use the provided data points to redirect their customers to the Klarna Purchase Journey.

In the Create Payment API response returned to their Partners the Acquiring Partner should return the following parameters:

{
  "status": "pending",
  "redirect_url": "https://acquiring-partner.com/payment/xxxxxxxx" // Acquiring Partner's standard integration working with any Payment Method requiring redirect

  // Klarna specific block
  "klarna": { 
    "payment_request_id": "krn:payment:eu1:request:dfb444b7-8b58-6731-9db8-e6bfe93f5629",
    "payment_request_url": "https://pay.klarna.com/krn:payment:eu1:request:dfb444b7-8b58-6731-9db8-e6bfe93f5629/start"
    "payment_request_data": "{\"content_type\":\"application/vnd.klarna.payment-request-data.v2+json\",\"content\":{\"payment_request\":{\"payment_request_id\":\"krn:payment:eu1:request:dfb444b7-8b58-6731-9db8-e6bfe93f5629\"}}}"
  }

Once the Partner has the required data points to redirect the customer through Klarna's Purchase Journey (usually using web redirection or Klarna's SDKs), the customer enters the Klarna purchase journey. This flow allows the customer to choose their payment method and input any necessary information. The process also requires the customer to log in to their Klarna account, if needed, to proceed with the payment.

After completing these steps, the customer is automatically redirected to the URL specified in the customer_interaction_config.return_url.

When the consumer has been approved by Klarna, the Acquiring Partner will receive a webhook with the payment_token that can be used to finalize the authorization of the payment.