Configuring Stripe and Stripe Tax for e-commerce

Introduction

The Stripe Strong Customer Authentication (Stripe SCA) payment gateway is an authorized payment method that can be used with the e-commerce features of your platform.

Stripe SCA is compliant with all of the International credit card circuits and with the European regulatory requirement to reduce fraud and make online payments more secure. 

The Stripe integration in Docebo supports two components:

• Stripe SCA, the core payment gateway for processing payments. Learn more about Stripe SCA (opens in a new tab).
• Stripe Tax, an additional tool that automates tax calculation and compliance for businesses selling products or services across various tax jurisdictions. Learn more about Stripe Tax (opens in a new tab), 

If you only need to handle payments, Stripe alone suffices. But if you need to manage complex tax compliance, especially for international or cross-state sales, Stripe Tax can simplify that process significantly.

This article covers how to configure the Stripe integration on your platform, and also how to configure the Stripe Tax functionality if you require it.

Please note: If the accurate calculation of taxes is a determining factor in the proper operation of your e-commerce business, it is highly recommended that you use only Stripe SCA with Stripe Tax as your credit card transaction processor.

Prerequisites

The Stripe SCA integration and the Stripe Tax add-on are available on the platform with the e-commerce pack. Contact your Docebo representative for information about how to obtain it.

• To configure this integration, you will need admin access to a valid Stripe account.

Requirements & limitations

• Some currencies supported by Docebo may not be accepted by Stripe, so remember to check if your currency is supported by both systems before proceeding. Check out the complete list of the currencies supported by Docebo.
• When working with the Extended Enterprise, configure the settings of Stripe in the root domain. If some domains require a different configuration, apply the configuration locally, in the E-commerce tab of the Extended Enterprise app.
• When using Stripe Tax:
  • Please note that the tax calculation is available for the currencies and the countries listed in the Stripe documentation (opens in a new tab)
  • In the case of subscriptions, the automatic tax calculation is supported for both subscription purchases and renewals. However, please note that invoices are available only for subscription purchases, but not renewals.
  • At checkout, the platform will always show taxes separately from the price, even if on Stripe Tax you set the option to include taxes in the price.

Use case scenarios

In the United States, prices do not include taxes, while in other countries it is the opposite. Stripe Tax does not explicitly support this diversification since whether taxes should be excluded or included is determined at the account level.

Since Stripe allows you to create multiple accounts and configure them independently and Docebo allows you to configure different payment gateways, one for each Extended Enterprise domain, you can create a domain for the United States market associated with a Stripe account excluding taxes and another domain for other countries associated with a Stripe account configured to include taxes. Optionally, for the second domain, it is possible to hide the "Taxes are calculated at checkout" text shown in the user's shopping cart using either custom CSS or the Localization tool.

Configure the Stripe SCA payment gateway

To configure Stripe SCA in the platform, log in as Superadmin, then select Navigation menu > Configuration (spanner icon) > E-commerce > Stripe SCA. On the configuration page that opens, activate the Enable Stripe payment gateway option.

In the Stripe information field enter your Stripe account email. Then continue to Enter your Stripe keys, Set whether to enable Klarna, and Set charge options for tax calculation.

Set up the Stripe webhook (optional)

The Stripe SCA integration includes an optional webhook that allows the platform to receive payment confirmation directly from Stripe, even if the learner's browser session is interrupted during the checkout process. When a webhook signing secret is configured, the platform uses Stripe's server-to-server notification as the authoritative signal to finalize orders and grant learners access to their purchased content.

Best practice: Configuring the webhook is strongly recommended for any platform with active e-commerce traffic. Without it, orders might remain in "Pending" status if a learner closes their browser or loses their internet connection immediately after completing a bank authorization. This can result in a successful Stripe charge but no enrollment on the platform side.

To retrieve your webhook signing secret from Stripe, log in to the Stripe Dashboard (opens in a new tab) with your admin account. Select Developers from the top navigation, then select Webhooks. Next, select Add Destination, then select Your Account or Connected Accounts, and then select the latest API version.

Under Events to listen to, add the checkout.session.completed event.

Please note: Docebo only supports v1 events, make sure you do not select v2 events.

Next, press Continue, and then select Webhook endpoint and press Continue again. In the Configure destination section, add a name and description and then this endpoint URL:

https://[your-platform-name].docebosaas.com/ecommerce/v1/admin/stripe-sca/webhook

Once the destination is created, select it to view the signing secret, then select Reveal to copy it.

To configure the webhook in the platform, in the Stripe Webhook Signing Secret Key field, enter the signing secret you copied from the Stripe Dashboard.

Please note: The Stripe webhook signing secret field is only available on the main domain. If you use Extended Enterprise with separate Stripe configurations per domain, the webhook field cannot be independently configured on sub-domains.

When you have finished, press Save changes.

Enter your Stripe keys

In the Test environment section, select whether you want to use a sandbox (test environment) or a real (live) environment. With the sandbox option, none of the payment operations will be billed to any account.

Then enter the Secret key and Publishable key for the environment you have chosen (test or live).

To retrieve these keys from Stripe:

1. Access the Stripe Dashboard (opens in a new tab) with your admin account.
2. In the top right corner select Developers and then select the API keys tab.
3. Enable the View test data option if you want to retrieve the keys for the test environment. Otherwise leave it deselected to obtain the live keys.
4. The publishable key and the secret key are available in the Standard keys section. If you need help finding this information, refer to Stripe’s support area (opens in a new tab). 
   

Set whether to enable Klarna

In the Payment type section, under Additional payment method, set whether you want to enable the Klarna buy-now-pay-later option for users paying via Stripe. Note that:

• Purchasers will have to select “Stripe” as a payment gateway in the shopping cart. They will then be redirected to the Stripe checkout page where they will see the Klarna option

  Tip: The Klarna option may not be available if there is a mismatch between the payment currency and the Stripe merchant country.

• If selected, Klarna will pay the whole amount to the merchant, and Klarna will then deduct the installments from the purchaser’s credit card.
• The Ecommerce transaction page and the ecommerce-transaction report will only show “Stripe” as a payment method used, there will be no mentions of the usage of Klarna.

To enable Klarna:

Select the Enable Klarna check box.

Please note: Remember that the Klarna setting you choose here will automatically apply to all extended enterprise clients that have Stripe SCA enabled. You cannot selectively enable or disable it on specific domains.

Then you need to also enable Klarna in your Stripe dashboard. For more information see the Stripe documentation for Klarna payments (opens in a new tab).

Please note: When you enable Klarna the platform’s integration forces the default settings for it, overriding any custom settings that might have been set in Stripe.

Set charge options for tax calculation

In the Payment type section,if you do not require Stripe Tax (automatic tax calculation) you can leave the Charge option set to the default, Simple charge.

If you do need to configure Stripe Tax, complete the steps described in the chapter Configure automatic tax calculation.

When you have finished, press Save changes.

Configure automatic tax calculation with Stripe Tax

Stripe Tax is an additional tool of the Stripe payment gateway that supports automatic tax calculation:

• Stripe Tax automatically calculates and collects the taxes on all purchases performed via e-commerce (including subscription purchases and renewals). Learn more on StripeDOCS (opens in a new tab).
• When users select Stripe SCA for their payment, in the checkout Billing information there is an option where they must set whether they are a business or an individual: Business purchasers are required to enter a company name and VAT number, while individuals are required to enter their full name and can optionally provide a Tax identifier.
• In addition, all kinds of users must enter their email address and Address, City and Zip/postal code, and select their country from the Stripe supported countries drop-down list (see countries supported by Stripe (opens in a new tab). This information is used for tax calculation purposes.

To set up this functionality you need to enable automatic tax calculation on the platform as well as configure Stripe Tax on the Stripe dashboard itself, as described in the following chapters.

Enable automatic tax calculation in the platform

Please note: This procedure assumes that the Stripe SCA core payment gateway is already configured.

Select Navigation menu > Configuration (spanner icon) > E-commerce > Stripe SCA and on the Stripe configuration page scroll down to the Payment type section and select the option Enable automatic tax calculation.

• In the Tax code field, enter the product tax code you want to apply. This will determine the tax rate applied to your transactions.

  Example: txcd_10000000 (General - Electronically Supplied Services)

  Refer to the Stripe documentation on tax codes (opens in a new tab).

• Enable the option Authorize Stripe to send an invoice per transaction detailing the purchased items, to allow Stripe to automatically send an invoice via email to users who finalize a purchase on the platform.

Please note: sending of these invoice emails also needs to be configured on the Stripe end.

When this option is activated, users must fill in their email address in the Billing information panel of the Payment and billing step of the purchase process to finalize the purchase. The invoice will be sent only after a successful payment and will contain details of every item bought in the transaction. If users buy multiple quantities of the same item, each item will be listed separately on the invoice.

For business users the invoice will include the VAT number, while for individuals the invoice will include the Tax identifier, if the user provided this information.

For subscriptions: Note that the invoice is only available for the initial subscription purchase, but not for subsequent renewals.

When you are finished press Save changes. 

Remember: You also need to complete the configuration on the Stripe end as described in the following chapter, Set up Stripe Tax on the Stripe dashboard.

Set up Stripe Tax on the Stripe dashboard

Log in to the stripe dashboard with your admin credentials (opens in a new tab), click the gear icon in the header to open the Product settings page, then under the Tax section select Settings.

Configure the available options as follows:

In the Business Information section, set the Origin address to where your business is located.

In the Product and Prices section select a Default product tax category. The most commonly used option is General - Electronically supplied services. 

The Include tax in prices dropdown sets how taxes are presented to the buyer. The available options are:

• Yes - Tax is included in the price: the amount paid by buyers never changes, even if the tax rate varies.
• No - Tax is excluded from the price: taxes are specified on the price and added to the subtotal. This solution is common in US markets and for B2B sales.
• Automatic - Use the currency to determine if tax is included or excluded: use this option only if suggested by your tax consultant or by your Stripe CSM.

In the Automatic Tax Calculation section, enable the Use automatic tax calculation toggle.

More details on setting up Stripe Tax are available in StripeDOCS (opens in a new tab).

As a business, you have an obligation to identify the states or provinces and Countries where you have tax obligations and need to register to collect tax in the Registrations tab of the Application Dashboard that you can reach from the Application bar by clicking on More and then on Tax.

From this tab, click on Export transactions to export transaction data into either an itemized or summarized report, which can be used to integrate with other services for more organic management of taxes. Learn how to register for sales tax, VAT, and GST and how to export transactions on StripeDOCS (opens in a new tab).

Best practices

Please pay attention to the following notes when integrating Stripe into your platform:

• When a user buys content using Stripe as a payment method, that user will be registered as a customer in Stripe and you will find their details in your Stripe Admin Dashboard.
• The process for setting up the Stripe  SCA configuration in your platform is identical when using either a single domain or Docebo’s Extended Enterprise functionality.