Learn how to process subscription payments when using the Stripe payment provider in Umbraco Commerce.
The Stripe Checkout payment provider is built to support both one-time and subscription-based payments including a mixture of the two. Before processing subscription payments you need to know the specific configuration steps required as well as some important limitations.
To process Subscription payments you first need to identify recurring products and define their recurring nature. This is done by adding the following properties to your product nodes:
In addition to the product properties defined above, you also need to configure your Umbraco Commerce Stores Product Property Aliases
field to copy these product properties to the generated order line.
With the properties defined the transactions will be converted to a subscription if the order has any order lines containing recurring items. If your order contains both recurring and non-recurring items then the order will be processed as a subscription transaction. In this case, the value of the non-recurring items will be added as an invoice line item to be paid on the initial transaction only.
There are a number of limitations when using the Stripe Checkout payment provider for subscription payments.
The Capture
configuration setting is not supported by Subscription payments. All Subscription transactions will have their initial payment processed immediately. This includes any one-time fees defined on the initial invoice.
No matter the number of recurring items in an order, each transaction will result in only one subscription being created including all recurring items. You can't create a Subscription per order line. If you need to purchase multiple Subscriptions, these must be processed as individual transactions.
You can't have non-order line discounts or gift cards that result in the order total being less than the sum total of any recurring order lines. You can discount a recurring item as an order line discount rule (only if using ad-hoc prices, and the value remains above 0). You couldn't give a 10% order discount unless you have other non-recurring items that would cover the cost of this discount.
The Stripe payment provider is only responsible for processing the initial Stripe transaction. All other "Subscription" integrations such as enabling member access etc. will need to be custom developed using the Stripe Software Development Kit (SDK) and your own webhook handler.
If you need a ready-to-use management portal to allow the management of your Subscriptions use the Stripe Customer Portal. The Stripe payment provider already captures the required fields as order properties for you to access.
Find guides to help you work with the Stripe payment provider for Umbraco Commerce.
In this section, we will provide you with a number of step-by-step how-to guides that may come in useful when working with the Stripe payment provider.
Learn how you can block different types of payments when using the Stripe payment provider with Umbraco Commerce.
Out of the box, Stripe implements a lot of security features for you, making payments safe and secure by default. You may still have a need to provide additional security steps of your own.
If you are based in the EU selling digital goods it would be a requirement to capture two forms of proof of a customer's location for VAT purposes. One recommended way is to capture the customer's billing country, and bank country, and ensure these are the same. The Stripe payment provider allows you to set this up in a few steps.
The first step is to ensure you are capturing the customer's billing address or more specifically, the billing address country. Learn how to do this in the core Umbraco Commerce documentation.
As long as you have populated your orders billing country, it will automatically be sent to Stripe using custom metadata on the transactions customer entity. This will be passed via a metadata entry on the Stripe customer with the key billingCountry
, with the value of the two-letter ISO code of the given country.
In order to configure custom Radar rules you need to sign up for the Radar for Fraud Teams added feature. This does incur an additional fee per transaction, however, the added security will outweigh the minimal expense.
To enable Radar for Fraud Teams follow these steps:
Log in to your Stripe dashboard.
Navigate to the Settings > Product Settings > Radar Settings section.
Enable the Radar for Fraud Teams feature, allowing us to define custom Radar rules.
To set up a new Stripe Radar rule, follow these steps:
Navigate to the Radar > Rules section.
Locate the Then, when should a payment be blocked? panel.
Click the Add rule button to add a new rule.
Enter the following rule in the dialog:
Click the Test rule button to test the rule.
Click the Add and enable button to add the rule to the list of block rules.
The rule test may fail when you click the Test rule button due to there being no transaction with the given metadata being attached to them. You will, however, be able to continue regardless.
Name | Description |
---|---|
Name | Value |
---|---|
isRecurring
True/false flag to indicate whether the given product is recurring or not
stripePriceId
Identifies a Stripe Price to use for this item. If a Price ID is found, the Stripe product/price will be used and the order line price will effectively be ignored in favor of the price held in Stripe. Because of this, it's important to ensure these values stay in sync. Otherwise, the customer will see one price on checkout and another at the payment gateway. If no price ID is found, an "ad-hoc" price will be created using the order lines' total price
stripeProductId
Relevant only if you don't provide a Stripe Price ID, this will allow all ad-hoc prices to be associated with a single Stripe Product definition within Stripe. If a product ID is not found, then an ad-hoc product will be created per order
stripeRecurringInterval
Relevant only if you don't provide a Stripe Price ID, this allows you to define the interval for the ad-hoc price created. Can be either day
, week
, month
or year
stripeRecurringIntervalCount
Relevant only if you don't provide a Stripe Price ID, this allows you to define the interval count. For example, if the interval is month
and the interval count is 2
then the item will be billed every two months
Product Property Aliases
isRecurring, stripeRecurringInterval, stripeRecurringIntervalCount, stripePriceId, stripeProductId
Learn how to run local tests of the webhooks setup with the Stripe payment provider.
The Stripe payment provider uses webhooks to finalize payments. Due to this, it can be tricky to test payments locally as Mollie must have a public-facing URL to be able to notify you.
You could expose your website through your network's firewall or use tools to create temporary tunnels through your network. Below you can find two options to create temporary tunnels through your network:
Go to the stripe documentation and install the stripe CLI.
Go to the stripe documentation and log in to the CLI.
While running the site locally, make a note of your local store domain. For example: https://localhost:44321
. Using the Stripe CLI, you can configure Stripe to forward any events to that URL.
To do so, run the following from the command line.
The {payment_method_id}
is configured as part of the Stripe webhook configuration step.
e.g.
When you start listening to Stripe events, the command line will give you a webhook signing secret. This should be used to set the Test Webhook Signing Secret
setting, shown in the Umbraco configure payment provider settings step.
With the Stripe CLI running, you can now test the site using your local dev domain. You will see any configured stripe events configured for the webhook displayed in the console window and can debug them using Visual Studio.
Go to the ngrok website.
Download and install the tool on your system.
You can either launch ngrok from the command line or use the steps below to create a batch file to be run at any time.
Open NotePad.
Type the following:
Swap the local domain/port number at the end according to the configuration of your site.
Save the file as ngrok.bat
at the root of your web project.
You can run the batch file at any time to launch ngrok and create a publicly accessible tunnel to your website.
When you launch ngrok for the first time, it will ask you to sign in. Enter the credentials you used to sign up. It will remember them from now on.
With ngrok running you can now test the site using the URLs displayed in the console window. Use these URLs (preferably the secure https
one) for your Stripe webhook configuration and you should now be able to test your Stripe webhooks locally.
You will see webhook requests displayed in the console window, and you can debug them using Visual Studio.