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

1. 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)
2. 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
3. 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.

Before calling Klarna’s Payment Authorization API, the Acquiring Partner must ensure their backend accept and forward Klarna specific parameters. These include interoperability parameters that preserve session context as well as supplementary purchase data which improves Klarna’s ability to assess risk, optimize approval rates, and deliver a more personalized checkout experience.

Interoperability parameters

When Partners optimize their integration with Klarna, they are likely to have interoperability parameters to share with the Acquiring Partner.

These ensure consistent customer and transaction context throughout the payment flow and must be forwarded unaltered to Klarna.

Implementation requirements

• Accept the interoperability parameters in the Partner-facing payment request API.
• Forward the interoperability parameters unmodified to Klarna’s Payment Authorization API.
• Validation can and should be implemented, but it must not be more restrictive than what is specified in Klarna’s Payment Authorize API. Make sure that all special characters permitted by the API specification are accepted.

Sample request

Below an example of how Acquiring Partners can accept the interoperability parameters in their Payment request API endpoint.

{
  "currency": "USD",
  "amount": 17800,
  "payment_method_options": {
    "klarna": {
      "interoperability_token": "eyJhbGciOiJ...",
      "interoperability_data": "{\"content_type\":\"application/vnd.klarna.interoperability-data.v2+json\",\"content\":{\"payment_request\":{...}}}"
    }
  }
}

Tokenization Specific Supplementary Purchase Data

Customer token scopes

To support tokenized payments, Acquiring Partners must include additional parameters when calling the Authorization API. 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.

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:

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

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

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

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

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

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

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

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

Sample response - DECLINED

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

Mixed responses

In case of a token creation with a purchase there could be rare scenarios where the results of the payment_transaction_response and the customer_token_response do not match. The table below summarizes the possible combinations and the required actions:

• When the payment transaction result is APPROVED and the customer token result is STEP-UP, retrieve the payment_transaction_id from the response, then direct the customer to the step-up flow to complete authentication for token creation.

• When the payment transaction result is STEP-UP and the customer token result is APPROVED, retrieve the successfully created customer_token from the response, then direct the customer to the step-up flow to authenticate and complete the purchase.

• When the payment transaction result is APPROVED and the customer token result is DECLINED, retrieve the payment_transaction_id from the response; the token cannot be created - inform the Partner so they can notify the shopper that the token creation was unsuccessful.

• When the payment transaction result is DECLINED and the customer token result is APPROVED, retrieve and persist the customer_token from the response for future use; the payment failed—inform the Partner so they can notify the shopper that the purchase was unsuccessful.