API and SDKs
Tokenized Hosted Checkout Integration

This guide is intended for Acquiring Partners who provide APIs and/or SDKs to their Partners, enabling them to integrate a Hosted Checkout or a drop-in embedded checkout component that supports tokenized payments. In this setup, the Acquiring Partner hosts and controls the payment form, while Klarna issues tokens that Partners can use for secure, repeatable transactions. The integration typically involves both client-side and server-side components to render the checkout and manage token lifecycle events.

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

  • Ensure their Hosted Checkout or embedded component incorporates Klarna's presentation guidelines while also supporting token creation flows.
  • Provide APIs and/or SDKs that allow Partners to securely obtain and manage Klarna tokens.
  • Support Klarna's interoperability data points related to token creation and usage.
  • Implement logic to handle Express Checkout–style flows that may leverage previously issued tokens.
  • Dynamically retrieve Klarna's presentation instructions to properly display Klarna within the selector, even when tokens are used.
  • Initiate the Klarna Purchase Journey via a pop-up purchase window (through Klarna's SDK) where the initial tokenization and customer consent occur.
  • Authorize token-based payments through Klarna's APIs, including support for Step-Up verification where required.
  • A payment server to interact with Klarna's Payment Authorize API.
  • A client-side component (Hosted Checkout page or drop-in widget) integrated with Klarna's SDK to launch the Klarna Purchase Journey pop-up and handle token creation securely.
  • 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 initiates a checkout session with the Acquiring Partner with the intention to tokenize the payment details, and sends the interoperability data points.
  3. The Partner either redirects the customer to the Acquiring Partner's Hosted Checkout Page URL or embeds the checkout element directly on the page.
  4. The Acquiring Partner's client-side component initializes Klarna's SDK and integrates it into the payment selector interface.
  5. The customer selects Klarna as their payment method and clicks the Klarna Payment button.
  6. The Acquiring Partner uses a combination of the Authorize Payment API and Klarna's SDK to initiate the Klarna purchase flow and request a customer tokenAPI. The interoperability data points shared by the Partner is also forwarded at this stage.
    1. Happy path: The payment transaction is created immediately, and the customer is redirected to the order confirmation page.
    2. Step-up required: Klarna's purchase journey is launched in a pop-up window for additional verification.
  7. (If Step-up is required) The Acquiring Partner monitors the payment status asynchronously via Klarna Webhooks. The Klarna customer tokenAPIcan already be retrieved at this stage.
  8. (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 P->>AP: Create checkout session Note over P,AP: Share interoperability data points<br>Request tokenization AP->>P: Return checkout session P->>AP: Load embedded element or redirect to hosted checkout AP->>K: Initialize Klarna SDK Note over AP,K: Share interoperability data points AP->>K: Request presentation instructions (SDK) K->>AP: Return assets and instructions AP->>AP: Render payment selector C->>AP: Select Klarna payment method AP->>AP: Update Klarna presentation<br>Show Klarna payment button C->>AP: Click Klarna payment button AP->>+K: Trigger authorize handler (SDK) Note over AP,K: First Authorize Payment API call with:<br>- interoperability data points<br>- request customer token alt Step-up required K->>-K: Start Klarna purchase journey C->>K: Complete purchase on Klarna K->>AP: Webhook + client notification Note over K,AP: Payment request completed<br>Klarna customer_token returned AP->>K: Authorize Payment API (final) Note over AP,K: Request customer token K->>AP: Payment approved Note over AP,K: Klarna customer_token returned AP->>P: Webhook + client 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: Webhook + client 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 declined K->>AP: Payment DECLINED AP->>P: Webhook + client notification Note over P,AP: Payment declined AP->>C: Return to checkout Note over C,AP: Display error message end
  1. The customer navigates to the Partner's checkout page.
  2. The Partner initiates a checkout session with the Acquiring Partner with the intention to charge the tokenized Klarna payment method and sends the interoperability data points.
  3. The Partner either redirects the customer to the Acquiring Partner's Hosted Checkout Page URL or embeds the checkout element directly on the page.
  4. The Acquiring Partner's client-side component initializes Klarna's SDK and integrates it into the payment selector interface.
  5. The customer selects Klarna as their payment method and clicks the Klarna Payment button.
  6. The Acquiring Partner uses a combination of the Authorize Payment API and Klarna's SDK to initiate the Klarna purchase flow using the Klarna customer tokenAPI. The interoperability data points shared by the Partner is also forwarded at this stage.
    1. Happy path: The payment transaction is created immediately, and the customer is redirected to the order confirmation page.
    2. Step-up required: Klarna's purchase journey is launched in a pop-up window for additional verification.
  7. (If Step-up is required) The Acquiring Partner monitors the payment status asynchronously via Klarna Webhooks.
  8. (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 P->>AP: Create checkout session Note over P,AP: Share interoperability data points<br>Use customer token issued by Acquiring Partner AP->>P: Return checkout session P->>AP: Load embedded element or redirect to hosted checkout AP->>K: Initialize Klarna SDK Note over AP,K: Share interoperability data points<br>Use customer token issued by Klarna AP->>K: Request presentation instructions (SDK) K->>AP: Return assets and instructions AP->>AP: Render payment selector C->>AP: Select Klarna payment method AP->>AP: Update Klarna presentation<br>Show Klarna payment button C->>AP: Click Klarna payment button AP->>+K: Trigger authorize handler (SDK) Note over AP,K: First Authorize Payment API call with:<br>- interoperability data points<br>- Klarna customer token alt Transaction approved K->>AP: Payment APPROVED AP->>P: Webhook + client notification Note over P,AP: Order completed AP->>C: Redirect to confirmation page else Step-up required K->>-K: Start Klarna purchase journey C->>K: Complete purchase on Klarna K->>AP: Webhook + client notification Note over K,AP: Payment request completed AP->>K: Authorize Payment API (final) K->>AP: Payment approved AP->>P: Webhook + client notification Note over P,AP: Order completed AP->>C: Redirect to confirmation page else Transaction declined K->>AP: Payment DECLINED AP->>P: Webhook + client notification Note over P,AP: Payment declined AP->>C: Return to checkout Note over C,AP: Display error message 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