Klarna Docs - Enable Klarna Payment in Vtex
API and SDKsSupport
Enable Klarna Payment in Vtex

This section covers the installation, configuration, and management of the Klarna Payments App in VTEX. It includes step-by-step instructions for setting up Klarna as a payment provider, handling orders, and moving to production.

The Klarna Payments App integrates with VTEX, enabling Klarna as a payment option at checkout. This allows merchants to accept payments through Klarna and manage orders using basic Order Management functionalities, such as capturing payments, processing refunds, and canceling transactions.

The following diagram provide a detailed overview of how Klarna Payments functions within the VTEX platform.

sequenceDiagram title Klarna Payments App for VTEX participant Customer participant VTEX_Storefront participant KP_App participant Klarna participant VTEX_Back_Office Customer->>VTEX_Storefront: 1. Goes to checkout and clicks "Buy" VTEX_Storefront->>KP_App: 2. Sends basket and customer information KP_App->>Klarna: 3. Calls `create session` API Klarna-->>KP_App: 4. Returns `session_id` KP_App->>Klarna: 5. Creates `HPP session` using `session_id` Note right of KP_App: `place_order_mode = PLACE_ORDER` Klarna-->>KP_App: 6. Returns `HPP URL` KP_App->>Customer: 7. Redirects to Klarna Hosted Payment Page (HPP) Customer->>Klarna: 8. Authenticates & authorizes payment Klarna-->>KP_App: 9. Sends notification to `merchant_urls` alt **Successful authorization** Note over Klarna, KP_App: Contains `session_id`, `status`, and `order_id` KP_App->>VTEX_Back_Office: 10. Sends order data for order creation VTEX_Back_Office->>VTEX_Storefront: 11. Creates VTEX order KP_App->>VTEX_Storefront: 12. Redirects customer to VTEX VTEX_Storefront->>Customer: 13. Displays order confirmation message else **Failed authorization** Note over Klarna, KP_App: Contains `session_id` and `status` KP_App->>VTEX_Storefront: 10. Redirects customer to VTEX VTEX_Storefront->>Customer: 11. Displays error message end

To enable Klarna as a payment provider in your VTEX store, you must install the Klarna Payments App.

  1. Open a terminal and log in to your VTEX account using the VTEX IO CLI.
  2. Run the following command to install the Klarna Payments App: vtex install klarnapartnerglobal.klarna-payments@2.0.4
  3. Once installed, go to VTEX Admin > Apps and verify that Klarna Payments appears under Installed Apps.

In VTEX Admin, navigate to Apps > Klarna Payments and click on 'Edit'

Navigate to KP app on VTEX

Select the region where your store operates (for example, North America, Europe).

VTEX KP app configuration - region selection

​For the allow all countries toggle:

  • Switch the Allow all countries toggle ON if you operate in all the Klarna markets of the selected region.
VTEX KP app configuration - Allow all countries toggle ON

Allow all countries toggle ON

  • If you  only operate in some of the region  markets, switch the toggle OFF and select the markets where you operate in the dropdown.
VTEX KP app configuration - specific markets selection

specific markets selection

​Test Mode: Set depending on the Klarna environment you want to use:

  • On – Uses Klarna’s Playground (test) environment.
  • Off – Uses Klarna’s Production environment.
VTEX KP app configuration - Environment toggle

Environment toggle

​​Click Save to apply the changes.

After installing Klarna Payments, you must add it as a payment provider in VTEX.

Go to VTEX Admin > Store Settings > Payments > Providers and click New Provider

Adding Klarna as payment provider on VTEX

Search and select KlarnaPayments.

Select Klarna Payments as provider

​Enter the required credentials:

  • Application Key (API User)
  • Application Token (API Password)

Entering Klarna API credentials on VTEX

​Enter a name for you to easily identify the Klarna provider configuration.

Enter an easy to identify name to the Klarna provider configuration

The Enable test mode setting determines whether the provider configuration applies to the VTEX test environment or the VTEX production environment.

Enable test mode - Provider configuration -VTEX

Click Save to complete the setup.

Important!
Ensure that the Klarna credentials entered in the provider configuration match the Klarna environment selected in the Klarna Payments App. Using Playground credentials with the Production environment, or vice versa, will result in authentication errors.

Go to VTEX Admin > Store Settings > Settings > Payment Conditions and click the "+" button to add a new condition.

Adding a new payment condition - VTEX KP app

Adding a new payment condition

​Look for Klarna and select it.

Select Klarna

​Enter a name for the Klarna payment condition

Enter name for payment condition

​Change the status to Active, this will enable Klarna in the checkout page.

Set to active

In Process with provider, select the provider configuration you created in the previous step.

Select Karna's provider configuration created in previous step

​Click Save. Now Klarna should be displayed at checkout as payment option

Save

​

Testing is a crucial step in ensuring that the Klarna Payments App functions correctly on the VTEX platform. It's recommended to conduct thorough testing in the Playground environment, in test mode, before going live.

FeatureTest Environment (Playground)Production Environment
Order processing timeUp to 60 minutes for test transactions to process in VTEX.Around 30 seconds for live transactions.
Auto-capture behaviorOrders are auto-captured in 24 hours unless manually captured.Klarna follows standard capture rules.
Credentials requiredPlayground API credentials must be used.Production API credentials must be used.
Payment processingNo actual money is exchanged.Live payments with real funds.

Before switching to production, confirm the following:

  • Klarna Payments is configured correctly with production API credentials.
  • Test orders have been successfully processed in the playground environment.
  • Klarna appears as a payment option in checkout.
  • Klarna’s order management functions (capture, refund, cancel) have been tested.
  • Your store’s payment conditions correctly allow Klarna for supported markets.

Once all steps are verified, Klarna Payments is ready to process live transactions.