# Stripe Subscription

The Stripe Subscription provider allows the purchasing of Stripe Subscription plans. As such, it works in quite a specific way compared to other payment providers.

Where other providers simply pass payment details through to the payment gateway to be paid for, the Stripe Subscription provider passes through payment details along with Plan ID's that MUST match up with subscription plans setup in Stripe.

Because of this, when using the Stripe Subscription payment provider, it is assumed the Order contains only subscription plan order line items, and that each order line item's SKU (or an OrderLine property of "planId") matches a Plan ID within Stripe. Also, whilst a price will exist on the product page for displaying on the site, the actual price charged will come from the Stripe plan, so it's important that these are kept in sync.

Finally, because Tea Commerce's role is purely to facilitate the checkout process, the Stripe Subscription provider will simply setup the subscription and charge the initial fee. From then on, subsequent renewal payments will be handled soley via Stripe. If you want to trigger custom actions within Tea Commerce / Umbraco, for example to email a customer if a subscription payment fails, you should create a Stripe webhook to listen for relevant updates and trigger these actions manually.

# Configure Stripe

Login to the Stripe dashboard.

# Subscription Plans

To create a Subscription Plan, click Billing and Product from the left hand side menu. On the right hand side, click Create Product.

On the next screen, enter a name for the subscription plan and click Create product.

On the next screen, fill in the details of the plan such as the recuring interval + pricing. Prices entered in Stripe should be exlcuding VAT as it is will be decided by Tea Commerce the relevant VAT Group and thus tax rate which applies. Once complete click Add pricing plan.

NB If you chose not to set a plan ID manually, one will be created for you by Stripe. You should keep track of this as you'll need to store this against the product node within Umbraco.

Repeat the steps above for each subscription plan you wish to create.

# Live API Keys

Click Developers and then API Keys in the left hand side menu. On the right hand side you will find your Publishable key. To view your Secret key, click the Reveal live key token.

# Test API Keys

To retreieve your test API keys, click the View test data toggle switch in the left hand side menu and then repeat the steps outlined in the Live API Keys section above.

# Webhook Notifications

When using the Stripe Subscription provider, the status of an order is updated based on responses from Stripe sent over webhooks. Tea Commerce automatically creates a webhook communication URL for you which should be registered with Stripe as follows.

Click Developers and then Webhooks in the left hand side menu. On the right hand side, click Add Endpoint and enter the Tea Commerce cummunication URL as follows (replacing the parameters in square brackets with the corisponding values taken from your store):

https://[domain]/base/TC/PaymentCommunicationWithoutOrderId/[storeId]/StripeSubscription%20-%20inline/[paymentMethodId]

From the Version dropdown select Latest API version (2019-05-16) and then in the Events to send dropdown select the following event types:

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• customer.subscription.trial_will_end
• invoice.payment_succeeded
• invoice.payment_failed
• invoice.upcoming

Click Add endpoint to create the webhook endpoint registration and be send to the webhook details screen.

Finally, from this screen, locate the Signing secret section and click the Click to reveal button to display of the webhook signing secret. Be sure to take note of this as we will need this later so that we can validate webhook requests.

NB You'll need to configure a webhook endpoint for both test and live configurations. To configure the test webhook, toggle the View test data toggle in the left hand side menu and then repeat the steps from above.

TIP To test payments locally we recommend you use a tool such as ngrok which can create a temporary public URL that safely proxies to your localhost server, allowing you to receive the Stripe webhook requests without the need to alter your firewall settings.

# Radar

The Stripe payment provider is automatically configured to send through billing contact information, this is in order for you to be able to perform validation rules using Stripe Radar. It is optional, but strongly recommended that you configure Radar Rules to validate the submitted Credit Card against these billing details. See the Radar documentation for more details.

# Configure Tea Commerce

For the most part, the Stripe Subscription provider settings are similar to the regular Stripe provider however there is one important feature worth highlighting.

With the Stripe Subscription provider it is possible to configure it such that it can either capture payments right now, in which case a credit card checkout form will be presented at the payment stage, or you can actually configure it to send out invoices instead. This could be an attractive option for B2B where invoicing is the norm.

To conifgure this feature, you can use the billing_mode setting as documented in the table below.

NB If you would like to offer both options, credit card / invoice, you would need to setup two instances of the Stripe Subscription provider configured accordingly and then allow them to choose the relevant option at checkout.

# Provider Settings

Create a payment method and select StripeSubscription - inline as the payment provider. Now configure the settings as follows.

# Configure Umbraco

As mentioned in the section intro, with the Stripe Subscription provider we have to setup products in a specific way. When configuring your product we need to store and pass through the Stripe Subscription Plan ID to the checkout process. The simplest way to do this is to set the products SKU to be the Plan ID.

If you need to set the SKU to something other than the Plan ID however, you can store the Plan ID in an alternative property and then pass this through on the OrderLine via property with the alias "planId".

The simplest way to do this would be to use an umbraco property with the alias "planId" and then configure OrderLine Automatic Properies to copy the "planId" field to the OrderLine properties collection.

# Stripe Subscription Events

Working with subscriptions is somewhat different to working with standard products as the state of the subscription can change over time and so it is often desirable to know when these changes occur. To assist with this the Stripe Subscription payment provider will trigger events when certain state changes occur (so long as a valid Webhook has been configured).

To listen for events you should register an event handler like so:

public StripeSubscriptionEventHandler: ApplicationEventHandler
{
    protected override void ApplicationStarted(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
    {
        StripeSubscription.StripeSubscriptionEvent += (sender, args) {
            // Handling logic goes here
        }
    }
}

The subscribed event handler will receive a sender argument, which is the instance of the StripeSubscription payment provider sending the event and an args argument which is an instance of the StripeSubscriptionEventArgs class.

The StripeSubscriptionEventArgs class contains the following properties:

# Useful Links

• Stripe Website
• Stripe API Documentation
• Stripe WebHooks Documentation
• Stripe Radar Documentation
• Stripe Dashboard