Recurring Payments - Stripe Gateway Configuration

This document explains how  Recurring Payments works with the Stripe payment gateway.  General setup of the Stripe payment gateway is found here.

Webhook configuration

A webhook is a URL on your site that Stripe can access to accomplish certain tasks. Stripe uses it for:

  • Recording renewal payments
  • Processing merchant-side refunds
  • Processing merchant-side cancellations
  • Handling failed payment notifications

EDD creates a webhook for you, and you simply need to tell Stripe where it is. If webhooks are not configured properly or are blocked by a plugin or configuration of your site, the processes above will not function.

Note: This step is the number one cause of failure in the recurring billing process. The following steps are very important.

To add the appropriate webhook endpoints, in your Stripe dashboard go to Developer → Webhooks (direct link). We recommend creating two webhook endpoints: one for test mode and one for live mode. If you create both, you'll need to repeat the below process after toggling modes.

Click  Add Endpoint, then add the following URL:

https://example.com/?edd-listener=stripe

Note: Replace "example.com" with your actual site URL. The exact URL you need to enter can be found in your WP admin under Downloads → Settings → Payment Gateways → Stripe.

We recommend selecting "receive all events" as Easy Digital Downloads will probably need to use the same webhook endpoint to communicate with your site using features not yet released.

After you add the endpoint you should see the new URL listed in the webhooks settings.

Note: Your webhooks won't work out of the box in a local development environment like Vagrant, WAMP, MAMP, Desktop Server, or Local by Flywheel. These are typically non-publicly accessible IP addresses and Stripe can't reach them.

Cancelling Subscriptions

When using Stripe, a cancellation may be initiated either from within EDD or from the Stripe Dashboard.

From The EDD Admin

To cancel a subscription from the EDD admin go to Downloads → Subscriptions and click View on the item you want to cancel.

Then in the bottom of the next screen click on  Cancel Subscription.

When you set a subscription to cancelled it's cancelled immediately, but the customer will still have access to their purchased material for as much time as they've paid for.

Example: they've paid $10/mo, and you cancel halfway through the month.  They still have access to their material for the rest of the month, but they won't be rebilled, and access will stop at the end of the month.

From The Stripe Dashboard

To cancel a subscription from the Stripe Dashboard, log into Stripe and find the search bar in the top right.

You may find customers by searching for:

  • the charge ID
  • the subscription profile ID
  • the EDD customer ID number
  • the customer email

Once you've found and selected your Customer in Stripe you'll see a list of subscriptions.

If you click Cancel you'll be given two options, to cancel Immediately or At Period End.  For the purposes of EDD it doesn't matter which you choose, your customer won't experience any difference between the two.

Cancelling Summary

It doesn't matter if you cancel a subscription in EDD or in Stripe, the effect is exactly the same and the customer won't notice a difference.

Multiple Domains and one Stripe Account

You can use a single Stripe account with multiple domains by setting up multiple endpoint URLs in your Stripe account under API > Webhooks and add multiple endpoints.

Refunds

When using the Stripe payment gateway refunds are processed the same way as any other transaction.  Read our full documentation on refunds here.

Common issues relating to webhooks

Customers get charged too many times

If you don't set up your Stripe webhooks correctly prior to a customer making a purchase and you are using the "Times" option in EDD Recurring to charge the customer a set amount of times (for example, 5 times), they will get charged too many times. 

This is because, without the webhook, Stripe is not able to tell EDD that the payments went through successfully so EDD doesn't know. Because of this, EDD thinks the customer has not yet been charged - even though they may have already been charged 5 times (or more). 

EDD sends a "cancel subscription" to Stripe automatically when the number of times has been reached. But since there is no webhook, EDD doesn't know that the customer has been charged at all and never cancels the subscription. This results in the customer continuing to be charged even after the set amount of times has been reached. This is why it is important to set up webhook immediately after installing the Stripe extension.