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.
The following instructions are specific to WooPayments and Stripe for WooCommerce. Please check your payment gateway’s documentation for instructions, and test credit card numbers, that can be used for testing in a similar scenario.
Considerations when testing the retry system
↑ Back to topIn 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.
Steps to take from customer view
↑ Back to topYou 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:
- Purchase a WooCommerce Subscription using a standard test credit card;
4242424242424242
. - Once the purchase is complete, go to My Account > Payment Methods.
- Click Add Payment Method.
- 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. - Click Add payment method.
![Adding a new payment method to the My Account area using a test credit card that will decline to process due to insufficient funds.](https://woocommerce.com/wp-content/uploads/2024/07/test-renewals-add-payment-method.webp?strip=all&w=704)
- A modal opens to simulate a 3DS check. Click Complete.
![A 3DS modal simulates a customer authentication request.](https://woocommerce.com/wp-content/uploads/2024/07/action-scheduler-payment-modal.png?strip=all&w=704)
- Go to My Account > Subscriptions.
- Click View next to the subscription created in the steps above.
- Click Change payment.
- Select the card ending in
3178
added during the steps above. - Click Change payment method.
![Finalize the payment method change by selecting it from the list](https://woocommerce.com/wp-content/uploads/2024/07/edit-subscription-change-payment-method.webp?strip=all&w=704)
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.
Steps to take as the shop manager
↑ Back to topNow 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:
- Log into the site’s WP Admin panel.
- Go to WooCommerce > Subscriptions.
- Note the subscription number belonging to your test customer (250 in our example)
- Go to WooCommerce > Status > Scheduled Actions> Pending (sub-tab).
- Type the subscription number into the search field top-right and click Search hook, args and claim ID.
- The result displays in the Hook column, it should read:
woocommerce_scheduled_subscription_payment_payment
- Hover over the entry in the Hook column to reveal Run and Cancel links.
![The Scheduled Actions and Pending sub-tabs showing a subscription search result](https://woocommerce.com/wp-content/uploads/2024/07/retry-system-pending-scheduled-action.webp?strip=all&w=704)
- Click Run to trigger an immediate renewal.
- Return to WooCommerce > Subscriptions and see the subscription status is On Hold.
- Click the subscription number to enter the Edit Subscription screen.
- View the Order Notes on the right. The most recent entry says Payment Failed.
![The Subscription's Order notes records the renewal, order creation, and order failure.](https://woocommerce.com/wp-content/uploads/2024/07/retry-system-subscription-on-hold.webp?strip=all&w=704)
- Click on the order number in the notes (or in the Related Orders section at the bottom) to enter its Edit order screen.
- Notice the order’s Pending Payment status. The Order notes records the failed payment, status changes, and the retry system activation.
![The subscription's renewal order has a status of Pending Payment. The order notes recorded the various events relating to the retry system.](https://woocommerce.com/wp-content/uploads/2024/07/retry-system-order-pending-payment.webp?strip=all&w=704)
- 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
- Click Run, let the page reload, and repeat that process until the payment retry system ends (default is after 5 tries).
![The Scheduled Actions hook now refers to the order instead of the subscription](https://woocommerce.com/wp-content/uploads/2024/07/retry-system-action-scheduler-order-retry.webp?strip=all&w=704)
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.
Questions and Support
↑ Back to topSomething missing from this documentation? Do you still have questions and need assistance?
- Have a question about a specific extension or theme you’d like to purchase? Click here.
- Already purchased and need some assistance? Get in touch with a Happiness Engineer via the WooCommerce.com Support page and choose this extension name from the “I need help with” dropdown.