API and SDKs
Tokenized Server Side Integration

This guide is designed for Acquiring Partners who implement server-side-only integrations for tokenized payments, enabling their Partners to securely create and manage tokens while maintaining full control over their own payment flows and checkout experience.

​In this model, the Partner typically uses the Acquiring Partner's APIs to:

  • Retrieve a list of available payment methods.
  • Obtain a Klarna payment URL for redirecting the customer.

To support Klarna in this setup, Acquiring Partners are expected to:

  • Provide clear and accurate technical documentation that ensures Partners implement the token creation and usage flow according to Klarna's specifications.
  • Review and validate the Partner's integration to confirm that tokenized transactions are handled securely and comply with Klarna's requirements.
  • Ensure that all interoperability data points related to tokenized transactions are submitted and processed in line with Klarna's interoperability standards.
  • Support Klarna's Step-Up flow, which may be triggered during token-based authorization when additional customer verification is required.
  • A server-side API that Partners can use to request a Payment with Klarna.
  • A payment server to initiate requests to Klarna's Payment Authorize API.
  • A webhook listener to receive and process asynchronous status updates from Klarna regarding token lifecycle events and payment outcomes.
  1. The customer navigates to the Partner's checkout page.
  2. The Partner displays a payment selector to the customer, with Klarna listed as a payment method. This can be implemented using one of the following approaches:
    1. Retrieve the Payment Presentation instructions directly from Klarna.
    2. Obtain a list of supported payment methods and descriptors from the Acquiring Partner (if available).
  3. The customer selects Klarna as the preferred payment method and clicks the Klarna Payment button.
  4. The Partner initiates a payment session with the Acquiring Partner with the intention to tokenize the payment details. The Acquiring Partner must support one of the following modes to launch the Klarna Purchase Journey:
    1. Redirect mode: Returns a Klarna payment URL for the Partner to redirect the customer.
    2. SDK mode: Returns a Klarna Payment Request ID for the Partner to initiate the purchase flow using Klarna's SDK.
  5. The Acquiring Partner calls Klarna's Payment Authorize API and request a customer tokenAPIfrom Klarna, forwarding the interoperability data points provided by the Partner.
    1. Happy path: The payment transaction is successfully created, and the Partner redirects the customer to the order confirmation page.
    2. Step-up required: The Acquiring Partner returns either a Klarna payment URL or a Payment Request ID for the Partner to launch the Klarna Purchase Journey.
  6. (If Step-up is required) The Acquiring Partner monitors the status of the Klarna payment asynchronously using Webhooks. The Klarna customer tokenAPIcan already be retrieved at this stage.
  7. (If Step-up is required) Upon successful completion of the Klarna purchase journey, the Acquiring Partner calls the Payment Authorize API a second time to finalize the transaction and obtain the Klarna customer tokenAPI.
sequenceDiagram autonumber participant C as Customer participant P as Partner participant AP as Acquiring Partner participant K as Klarna C->>P: Visit checkout page alt Partner integrates Klarna SDK directly P->>K: Request Klarna payment presentation Note over P,K: Share interoperability data points else Partner uses Acquiring Partner APIs P->>AP: Request available payment methods Note over P,AP: Share interoperability data points AP->>K: Request Klarna payment presentation Note over AP,K: Share interoperability data points end P->>P: Display payment selector C->>P: Select Klarna and click Pay button P->>AP: Create payment session Note over P,AP: Request customer token<br>Share interoperability data points AP->>K: Authorize payment (initial) Note over AP,K: Request customer token<br>Share interoperability data points alt Step-up required K->>AP: Return payment request for step-up Note over K,AP: Klarna payment URL and request ID AP->>P: Return payment session Note over P,AP: Forward Klarna payment URL and request ID P->>P: Launch Klarna purchase journey C->>K: Complete purchase on Klarna K->>AP: Webhook notification Note over K,AP: Payment request completed<br>klarna customer_token returned AP->>K: Authorize payment (final) Note over AP,K: Request customer token K->>AP: Payment APPROVED Note over AP,K: Klarna customer_token returned AP->>P: Webhook notification Note over P,AP: Order completed<br>Return Klarna issued customer token<br>Return Acquiring Partner issued customer token AP->>C: Redirect to confirmation page else Transaction approved K->>AP: Payment APPROVED Note over AP,K: Klarna customer_token returned if request<br>customer token sent in KEC session by the partner AP->>P: Respond with approval Note over P,AP: Order completed<br>Return Klarna issued customer token<br>Return Acquiring Partner issued customer token P->>C: Redirect to confirmation page else Transaction declined K->>AP: Payment DECLINED AP->>P: Respond with decline Note over P,AP: Payment declined P->>C: Redirect to checkout page Note over C,P: Display error message to customer end
  1. The customer navigates to the Partner's checkout page.
  2. The Partner displays a payment selector to the customer, with Klarna listed as a payment method. This can be implemented using one of the following approaches:
    1. Retrieve the Payment Presentation instructions directly from Klarna and use the Klarna customer token to personalize them.
    2. Obtain a list of supported payment methods and descriptors from the Acquiring Partner (if available).
  3. The customer selects Klarna as the preferred payment method and clicks the Klarna Payment button.
  4. The Partner initiates a payment session with the Acquiring Partner with the intention to charge the tokenized Klarna payment method. The Acquiring Partner must support one of the following modes to launch the Klarna Purchase Journey:
    1. Redirect mode: Returns a Klarna payment URL for the Partner to redirect the customer.
    2. SDK mode: Returns a Klarna Payment Request ID for the Partner to initiate the purchase flow using Klarna's SDK.
  5. The Acquiring Partner calls Klarna's Payment Authorize API using the Klarna customer tokenAPIand forwarding the interoperability data points provided by the Partner.
    1. Happy path: The payment transaction is successfully created, and the Partner redirects the customer to the order confirmation page.
    2. Step-up required: The Acquiring Partner returns either a Klarna payment URL or a Payment Request ID for the Partner to launch the Klarna Purchase Journey.
  6. (If Step-up is required) The Acquiring Partner monitors the status of the Klarna payment asynchronously using Webhooks.
  7. (If Step-up is required) Upon successful completion of the Klarna purchase journey, the Acquiring Partner calls the Payment Authorize API a second time to finalize the transaction.
sequenceDiagram autonumber participant C as Customer participant P as Partner participant AP as Acquiring Partner participant K as Klarna C->>P: Visit checkout page alt Partner integrates Klarna SDK directly P->>K: Request Klarna payment presentation Note over P,K: Share interoperability data points<br>Use customer token issued by Klarna else Partner uses Acquiring Partner APIs P->>AP: Request available payment methods Note over P,AP: Share interoperability data points<br>Use customer token issued by Acquiring Partner AP->>K: Request Klarna payment presentation Note over AP,K: Share interoperability data points<br>Use customer token issued by Klarna end P->>P: Display payment selector C->>P: Select Klarna and click Pay button P->>AP: Charge customer token Note over P,AP: Use customer token issued by Acquiring Partner<br>Share interoperability data points AP->>K: Authorize payment (initial) Note over AP,K: Use customer token issued by Klarna<br>Share interoperability data points alt Transaction approved K->>AP: Payment APPROVED AP->>P: Respond with approval Note over P,AP: Order completed P->>C: Redirect to confirmation page else Step-up required K->>AP: Return payment request for step-up Note over K,AP: Klarna payment URL and request ID AP->>P: Return payment session Note over P,AP: Forward Klarna payment URL and request ID P->>P: Launch Klarna purchase journey C->>K: Complete purchase on Klarna K->>AP: Webhook notification Note over K,AP: Payment request completed AP->>K: Authorize payment (final) K->>AP: Payment APPROVED AP->>P: Webhook notification Note over P,AP: Order completed AP->>C: Redirect to confirmation page else Transaction declined K->>AP: Payment DECLINED AP->>P: Respond with decline Note over P,AP: Payment declined P->>C: Redirect to checkout page Note over C,P: Display error message to customer end
  1. The Partner initiates a payment session with the Acquiring Partner with the intention charge the tokenized Klarna payment method.
  2. The Acquiring Partner calls Klarna's Payment Authorize API using the Klarna customer tokenAPI#*Happy path: The payment transaction is successfully created.
    1. Unhappy path: The Klarna customer token could not be charged. Unlike on-demand purchase scenarios. No step up can be triggered since the customer is not present when the subscription charge is triggered
sequenceDiagram autonumber participant C as Customer participant P as Partner participant AP as Acquiring Partner participant K as Klarna C->>P: Subscription charge due P->>AP: Charge customer token Note over P,AP: Use customer token issued by Acquiring<br>Partner<br>Share interoperability data points AP->>K: Authorize payment (initial) Note over AP,K: Use customer token issued by Klarna<br>Share interoperability data points alt Transaction approved K->>AP: Payment APPROVED AP->>P: Respond with approval Note over P,AP: Order completed P->>C: Notify customer of successful subscription charge else Transaction declined K->>AP: Payment DECLINED AP->>P: Respond with decline Note over P,AP: Payment declined P->>C: Notify customer of failed subscription charge end