With a previously created payment:customer_present scope token, customers can use Klarna for an on-demand payment:

  1. The javascript function attached to the button click handler initiate is triggered
  2. The Partner sends a request to the Acquiring Partners to create a Klarna payment session that contains purchase details, customer_token or the token equivalent issued by the Acquiring Partner, interoperability_token and interoperability_data.
  3. The Acquiring Partner forwards the required payment context data to Klarna’s Payment Authorization API including:
    1. customer_token
    2. step_up_config
    3. request_payment_transaction
  4. Klarna returns one of the following responses:
    1. APPROVED – Depending on risk assessment and the initially selected payment method, charges might go through immediately as a one-click experience. Transaction is completed, proceed to confirmation and store payment_transaction_id.
    2. STEP_UP_REQUIRED – In certain cases, customers are required to go through a step-up flow. Acquiring Partners have to either return the klarna payment_request_id or payment_request_url to the Partner.
    3. DECLINED – If the payment is denied, Acquiring Partners have to inform the Partner that the payment could not be completed, the Partner should invite the customer to select another payment method.
  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 APIAPI 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

JAVASCRIPT
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 Acquiring Partner can also create a custom button to launch the Klarna Purchase Journey. This is detailed in the Launch the Klarna Purchase Journey with a custom button section.

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.

Request Parameters

In the request to the Payment Authorize APIAPI, Acquiring Partners must specify the following parameters:

Path
Parameter nameDescription

partner_account_idAPI

The unique identifier of the Partner account. This is used to scope the request.
Header
Parameter nameDescription

AuthorizationAPI

Acquiring Partners use their Klarna API key to authenticate:
Basic <API key>

Klarna-Interoperability-TokenAPI

Must contain the interoperability token if provided by the Partner.

Body

Parameter nameDescription

currencyAPI

Currency in ISO 4217 format.

request_payment_transactionAPI

Represents a request to authorize a payment transaction, this object contains the following parameters:

step_up_configAPI

  • This object is required to support a step-up scenario, where the customer must approve the payment. Acquiring Partners must configure customer_interaction_configAPI to determine how the purchase journey is launched. Applicable customer interaction config methodAPI for this integration pattern is HANDOVER.
  • Acquiring Partners must also indicate a return_urlAPI and/or an app_return_urlAPI, to ensure proper redirection after authorization. This will be covered in detail in the section Handle step-up scenario.<br />
  • This object also allows Acquiring Partners to provide a payment_request_referenceAPI for the purpose of correlating the payment session or equivalent resource with the Klarna Payment Request. This will also be exposed in payment request webhooks.

This will be covered in detail in section Handle step-up scenario.

supplementary_purchase_dataAPI

Additional information that provides more detailed information about the transaction, which helps reduce the risk of fraud and enhances transparency.
Shopping basket, customer billing / shipping details or specific transaction data can be provided through this object.
The Acquiring Partner is responsible for mapping relevant fields from their Checkout session API into Klarna’s supplementary_purchase_data object format when calling the Klarna Payment Authorization API as explained in the previous section.

interoperability_dataAPI

This field should be used for forward interoperability_data provided by the Partner as explained in the previous section.
acquiring_configAPIThis object is mandatory if the Acquiring Partners have multiple payment accounts configured as detailed here. Use this field to specify which payment account will be used for the transaction. You have flexible options, choosing from either of the two described below:
  • payment_account_idAPI: Provide this data point when relying on Klarna's payment account identifier.
  • payment_acquiring_account_idAPI + payment_account_referenceAPI: Provide these data points when you need to specify an account identifier assigned by Klarna to the acquiring account, along with a reference for the payment account that allows the partner to identify it independently of Klarna-generated IDs.

Below an example request body for the Payment Authorize APIAPI. (interoperability token sent as an HTTP header parameter)

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,

The Payment Authorize API can yield 3 different outcomes depending on the transaction and the consumer:

ResultDescription

APPROVED

The Payment Authorization is approved without additional customer interaction. A Payment Transaction is created and contained in the response.

STEP_UP_REQUIRED

Additional customer interaction is required to authorize the payment. Those interactions need to happen in Klarna’s Purchase Journey and the customer has to be redirected to it. Read more about how to handle the Step-up Scenario.

DECLINED

The payment cannot proceed due to reasons such as fraud, final decline or risk concerns.

Approved Payment Transaction

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_responseAPI object with the following parameters:

Parameter nameDescription

resultAPI

The result parameter which specifies the outcome of the authorization.
In case of a successful Authorization the result will be set to APPROVED

payment_transactionAPI

The payment_transaction object represents a single payment transaction
This object is only returned if the payment_transaction_response.result is set to APPROVED
The payment_transaction_idAPI  returned is necessary to manage the Payment Transaction through the Payment Transaction APIAPI.

Sample response - APPROVED

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

JAVASCRIPT
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.

Declined authorization

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_responseAPI object with the following parameters:

Parameter nameDescription

resultAPI

The result parameter which specifies the outcome of the authorization.
In case of a decline, the result will be set to DECLINED

Sample response - DECLINED

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

JAVASCRIPT
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.

Step-up scenario

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 case your systems cannot support a pattern where there is no consumer interaction at the initialization of the session, it is possible to force the Step-up flow. This can be achieved by adding the mode = REQUIRED to the step_up_config object.

The mode = REQUIRED will be available in a future release.

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

Parameter nameDescription

payment_transaction_responseAPI

The payment_transaction_response object will contain the resultAPI parameter which specifies the outcome of the the authorization.
In case of the Step up flow the result will be set to STEP_UP_REQUIRED

payment_requestAPI

The base properties of a Payment Request.
This field is only returned if the payment_transaction_response.resultAPI is set to STEP_UP_REQUIRED.
The state_context.customer_interactionAPI object contains the payment_request_idAPI necessary for the Partner to launch the Klarna Purchase Journey using the Klarna SDK.

Sample response - STEP_UP_REQUIRED

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

JAVASCRIPT
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.