Recurring Payments – Stripe Gateway Configuration

This document explains how the Recurring Payments extension works with Stripe.

Configuring Stripe

It’s important to follow all steps laid out in the Stripe Setup Documentation.

Important Setup Note: If Webhooks are not properly configured, subscriptions will not work properly!

Canceling Subscriptions

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

Canceling as a Customer

Customers can cancel their own subscriptions from your store’s account page. 

Canceling as a Site Administrator

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’s status 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.

For example, if 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 re-billed, and access will stop at the end of the month.

From The Stripe Dashboard

To cancel a subscription from the Stripe Dashboard, log in to Stripe and find the search bar at the top of the page.

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 (X icon to the of the subscription name) you’ll be given three options; to cancel Immediately, at the end of the current period, or on a custom date. For the purposes of EDD it doesn’t matter which you choose immediately or at the end of the current period, your customer won’t experience any difference between the two. If you choose a custom date, that’s after the end of the current period, they will continue to get billed until the custom date passes.

Canceling 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.

Updating Credit/Debit Card Information

Customers can update their card information for their specific subscription(s) from your store’s account page.

Statement Descriptors

When a product is configured as a subscription, the descriptor behavior is slightly different than non-subscription purchases. When a subscription is purchased for the first time on your site, a “Product” is created in Stripe that will be used for all subsequent purchases of that particular subscription. You can see your current list of Products by logging into your Stripe account and navigating to Products.

When this Product is created, a statement descriptor is created based on the name of your product, regardless of the aforementioned setting in your WordPress dashboard. The descriptor will also be made lowercase and will separate words using hyphens. Understandably, this doesn’t look friendly on a bank statement. There are two ways to change this behavior that are best used together if you do not like the default behavior:

1. Edit the Plan details

By going to Products in your Stripe account, you can click on any Product to see its details. Once you’re on the details page, click the Edit details button. You will be presented with a modal that allows you to set the statement descriptor for that particular Product.

What you set here will be used for all payments of that subscription plan on your site.

2. Filter the Statement Descriptor default for Stripe plans

The above method allows you to control the statement descriptor for a specific subscription that already exists. But if a new subscription is created from the first-time purchase of a different subscription on your site, the default behavior will apply. That means the new subscription will still have a statement descriptor based on the product name by default.

To create a new default statement descriptor for all subscriptions created in the future (this will not affect existing subscription), use the following filter:

function custom_edd_recurring_stripe_plan_statement_descriptor( $args, $subscription ) {
   $args['statement_descriptor'] = 'New Statement Desc';
   return $args;
}
add_filter( 'edd_recurring_create_stripe_plan_args', 'custom_edd_recurring_stripe_plan_statement_descriptor', 10, 2 );

Replace New Statement Desc with your preferred default statement descriptor (remember the 22 character limit).

In summary, use the first method to edit the statement descriptor for an existing subscription. Use the second method to set a new default statement descriptor for all future subscriptions.

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 a webhook immediately after installing the Stripe extension.