Steps for token creation only or for token creation with purchase:

  1. Customer clicks on the Klarna Payment button
  2. The javascript function attached to the button click handler initiate is triggered
  3. The Partner sends a request to the Acquiring Partner containing interoperability_token and interoperability_data for:
    1. Token creation only (Use cases: On-demand without a purchase, Subscription with free trial)
    2. Token creation with purchase (Use cases: On-demand with initial purchase, Subscription without free trial, Mixed payments)
  4. The Acquiring Partner forwards the required payment context data to Klarna’s Payment Authorization API including:
    1. supplementary_purchase_data
      1. ondemand_service or
      2. subscription
    2. step_up_config
    3. request_customer_token
    4. if purchase is applicable: request_payment_transaction
  5. Klarna returns one of the following responses:
    1. STEP_UP_REQUIRED – The customer has to authenticate for the token creation and, if applicable, for the payment. Either return the Klarna payment_request_id or payment_request_url to the Partner.
    2. APPROVED – Successful creation of the customer token and, if applicable, the payment transaction.
    3. DECLINED – Token creation and payment authorization is declined.
  6. 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.

Customer token scopes

To support tokenized payments, Acquiring Partners must include additional parameters when calling the Authorization APIAPI. Klarna then generates a customer token, which authorizes future payments on behalf of the customer. Each customer token is issued with specific scopes that define the permitted actions and level of access for subsequent transactions.

ScopeDefinitionUse cases

payment:customer_present

Enables tokenization of the customer for subsequent on-demand charges. Depending on risk assessment and the initially selected payment method, charges might go through immediately as a one-click experience or, in certain cases, require a step-up.
  • On-demand with initial purchase
  • On-demand without purchase

payment:customer_not_present

Enables tokenization of the customer for subsequent subscription charges. It allows the Partners to initiate tokens charges without requiring a step-up flow since the customer is not present during the transaction.
  • Subscription with free trial
  • Subscription without free trial

Creating a token with multiple token scopes will be supported in the future.

Choosing the correct token scope is crucial for ensuring successful payments and maximizing conversion:

  • payment:customer_present: choose this token scope for payments where the customer is actively present in the payment flow and can authenticate if required, so it's not suitable for subscription charges.
  • payment:customer_not_present: choose this token scope for payments where the customer is not present in the payment flow. While this scope could also work for a customer present payment, there may be limitations in the payment options Klarna can offer under this scope.
Payment Authorize
API
POST:/v2/accounts/{partner_account_id}/payment/authorize
Show recommended
ParameterRequiredDescription
Klarna-Interoperability-Token
No

The interoperability token enables continuity of customer journey across domains and services. If you are an Acquiring Partner, you receive this token from your merchant.

Here you can find all required parameters for this operation authorizePayment
API

Note that the request_payment_transaction is only required in case of token creation with purchase.

Token creation only

Token creation with purchase

The Payment Authorize API response for the payment_transaction_response and for the customer_transaction response can yield 3 different results:

ResultDescription

STEP_UP_REQUIRED

The customer has to authenticate for the token creation and, if applicable, for the payment. Read more about how to handle the Step-up Scenario.

APPROVED

Successful creation of the customer token and, if applicable, the payment transaction.

DECLINED

Token creation and if applicable, the payment authorization are declined.
Payment Authorize
API
POST:/v2/accounts/{partner_account_id}/payment/authorize
Show recommended
ParameterRequiredDescription
payment_transaction_response
No

The request for a payment transaction can result in one of the following outcomes:

  • Successful Authorization (result APPROVED) : The authorization was approved, and the response body includes the Payment Transaction object.

  • *...

-result
Yes

The result of the authorization attempt

-payment_transaction
Yes

The Payment Transaction object represents a single payment transaction.

--payment_transaction_id
No

Unique identifier for a created Payment Transaction. This identifier can be used to manage the Payment Transaction through the Payment Transaction API.

You should not make any assumption about the format of this identifier, you should trea...

--payment_transaction_reference
No

Reference to the payment or equivalent resource created on your side. This will be exposed in the Payment Transaction webhooks for the purpose of correlating your resource with the Klarna Payment Transaction.

--state
No

The current state of the Payment Transaction.

  • AUTHORIZED - The payment transaction has been authorized and waiting for further actions such as capture, refund, void, or expiration.
  • COMPLETED - The payment transaction has been compl...
--currency
No

Currency in ISO 4217 format.

--amount
No

Total amount of a one-off purchase, including tax and any available discounts. The value should be in non-negative minor units. Eg: 25 Dollars should be 2500. This is the amount that Klarna will charge the customer for a one-off purchase. S...

--payment_pricing
No

Payment pricing details

---applicable_rate
Yes

Applicable rate for the payment

----fixed_fee
Yes

Applicable fixed fee for the payment. The value is negative when representing an incentive. It is present as per the currency applicable for the fixed fee for that transaction.

-----amount
Yes

Numeric without decimals. Minor currency units (e.g. cent, öre) following ISO 4217, must use with Currency.

-----currency
Yes

Currency in ISO 4217 format.

----variable_fee
Yes

Variable fee is the percentage of the payment amount. The value is negative when representing an incentive.

-----percentage
Yes

Percentage points representing the percent value multiplied by 100. For example, 1.5% is represented as 150.

Showing 15 of 41
Back to Top
Here you can find all required parameters for this operation authorizePayment
API

Step-up scenario

When the customer has to authenticate for the token creation, and optionally also for the purchase completion, 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 authenticate for the token creation and, if required, to complete the purchase. The required steps 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.

Token creation with purchase -Sample response - STEP_UP_REQUIRED

JSON
{
  "payment_transaction_response": {
    "result": "STEP_UP_REQUIRED"
  },
  "customer_token_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",

Token creation without purchase -Sample response - STEP_UP_REQUIRED

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

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.

Approved Payment Transaction

When the token creation is successful, a customer_token is created on the Klarna Network. Optionally, if a purchase is completed, a payment_transaction_id is created too. 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 confirmation page.

Acquiring Partners must share the Klarna customer_token or issue their own token equivalent and share it with their Partners to enable them to perform future token charges. Acquiring Partners must also 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.

Sample response - APPROVED

JSON
{
  "customer_token_response": {
    "result": "APPROVED",
    "customer_token": "krn:customer-token:123"
  }
}

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

Declined authorization

If a token creation request, optionally with a purchase, could not be approved by Klarna and the step-up scenario cannot be triggered (due to missing configuration or a permanent decline), the Acquiring Partner will receive a DECLINED result. Declines should not be replayed without a change of context. The Acquiring Partner should inform the Partner that the token creation, and the transaction if applicable, could not be completed.

Sample response - DECLINED

JSON
{
  "customer_token_response": {
    "result": "DECLINED"
  }
}

Sample response - DECLINED

JSON
{
  "payment_transaction_response": {
    "result": "DECLINED"
  },
  "customer_token_response": {
    "result": "DECLINED"
  }
}

Mixed responses

When creating a token with a purchase, it’s possible—though rare—for the payment transaction and customer token results to differ. The list below summarizes each scenario and the appropriate next steps:

  • APPROVED (transaction), STEP_UP_REQUIRED (token): Register payment_transaction_id, then direct the customer to the step-up flow to complete token authentication.
  • STEP_UP_REQUIRED (transaction), APPROVED (token): Register customer_token, then direct the customer to the step-up flow to complete the purchase.
  • APPROVED (transaction), DECLINED (token): Retrieve payment_transaction_id; token creation failed—notify the partner to inform the transaction.
  • DECLINED (transaction), APPROVED (token): Retrieve and save customer_token for future use; purchase failed—notify the partner to inform the customer. May use the customer_token to reattempt the charge on the background if customer_not_present scope was requested.

SDK - Initiate Handler Promise Resolution

Back to the SDK, the function attached to the initiate handler returns a promise which should resolve to an object that varies depending on the transaction outcome:

  • Step-up scenario
    • The object contains a paymentRequestId generated as part of the step-up response.
    • When the customer clicks the Klarna payment button, the Klarna Purchase journey is triggered.
    • This flow is described in more detail in the Handle Step-up section.
  • Immediately approved transaction
    • The object may include an optional returnUrl that redirects the customer to the order confirmation page.
    • In this case, the transaction is approved right after the customer clicks the Klarna payment button.
  • Declined transaction
    • The object may include an optional returnUrl that redirects the customer after the decline.
    • The Acquiring Partner should inform the Partner that the transaction could not be completed.
    • The Partner should then prompt the customer to select another payment method.