Test the WooCommerce Subscriptions Payment Retry System

This guide is for shop managers who want to test the WooCommerce Subscriptions Failed Recurring Payments Retry System. The WooCommerce Subscriptions Retry System attempts to re-bill a declined card. It works for card errors that you can retry, like insufficient funds, as opposed to ones that you cannot, like cards that cardholders (or card issuers) have canceled.

In this guide we recreate a scenario that triggers the retry system by using test credit cards with a payment gateway in Test Mode. This document aims to empower merchants, but if you cannot meet the considerations below, you should contact a developer for help to set up a more robust testing environment.

• To test the retry system, you need to create a subscription with a credit card that works for the initial signup but fails upon renewal. We use 2 seperate, specific test credit cards. But for them to work as intended, the payment gateway must be in Test Mode.
• Test Mode comes with the caveat that if real, active subscriptions payment tries to use the gateway while in this mode, it will fail. So, it’s important to prevent real subscriptions from starting or renewing while the payment gateway is in Test Mode.
• It’s possible to check Action Scheduler to see if any automatic renewals are due. That doesn’t account for new signups or customers who might manually renew though, so you should also put the checkout page into coming soon mode.
• Keep in mind when using a staging site that Subscriptions will disable auto-renewals (and emails) by default. You can force a staging site to process automatic payments, which is a viable solution provided you set all the payment gateways to Test Mode. However, that approach is outside the scope of this document.

You will perform the following steps as a test customer, but it’s important that the store manager first sets the respective payment gateway to Test Mode. Then follow the rest of the steps as a customer would:

1. Purchase a WooCommerce Subscription using a standard test credit card; 4242424242424242.
2. Once the purchase is complete, go to My Account > Payment Methods. 
3. Click Add Payment Method.
4. Add this second test credit card; 4000008260003178. This is Stripe’s test card that has insufficient funds, but allows it to be “attached” to a customer. Use any future expiry date, and CVC number. The country for this particular card must be the United States. Any valid ZIP code can be used.
5. Click Add payment method. 

5. A modal opens to simulate a 3DS check. Click Complete.

6. Go to My Account > Subscriptions. 
7. Click View next to the subscription created in the steps above.
8. Click Change payment. 
9. Select the card ending in 3178 added during the steps above.
10. Click Change payment method. 

The steps above simulates a customer paying with a working credit card, and switching their subscription payment method to a card that returns an “insufficient funds” error upon renewal. “Insufficient funds” is usually a temporary issue, which is why the retry system will step in. 

Now that the customer changed their subscription to a payment method that will fail, we need to trigger the renewal. Instead of waiting for the subscription to renew “naturally”, we can move the testing process along by triggering a renewal immediately. The steps below simulate exactly what would happen during a “real” renewal:

1. Log into the site’s WP Admin panel.
2. Go to WooCommerce > Subscriptions. 
3. Note the subscription number belonging to your test customer (250 in our example)
4. Go to WooCommerce > Status > Scheduled Actions> Pending (sub-tab).
5. Type the subscription number into the search field top-right and click Search hook, args and claim ID.
6. The result displays in the Hook column, it should read: woocommerce_scheduled_subscription_payment_payment
7. Hover over the entry in the Hook column to reveal Run and Cancel links. 

8. Click Run to trigger an immediate renewal. 
9. Return to WooCommerce > Subscriptions and see the subscription status is On Hold. 
10. Click the subscription number to enter the Edit Subscription screen. 
11. View the Order Notes on the right. The most recent entry says Payment Failed. 

12. Click on the order number in the notes (or in the Related Orders section at the bottom) to enter its Edit order screen.
13. Notice the order’s Pending Payment status. The Order notes records the failed payment, status changes, and the retry system activation.

14. To trigger subsequent retries, follow steps 4-5 again with two important adjustments:
    • we want to retry the order billing, so search for the Order number instead (253 in this example), and
    • look for the hook woocommerce_scheduled_subscription_payment_retry hook
15. Click Run, let the page reload, and repeat that process until the payment retry system ends (default is after 5 tries).

After 5 tries the Order status changes to Failed. The subscription remains On-Hold, and requires manual intervention. In a real-world scenario you would generate a pending renewal order, email the customer the payment link, and ask them to try again with a working credit card.