Payment Troubleshooting

Payment issues can occasionally occur due to incorrect gateway settings, failed renewals, webhook configuration problems, or testing environment errors. This guide explains the most common payment-related issues in WooCommerce and the steps you can take to resolve them when using Flexi Subscription.

Overview #

If subscription payments are not behaving as expected, begin by checking:

1. WooCommerce payment gateway configuration
2. Payment gateway account status
3. API credentials
4. Webhook configuration
5. Subscription status
6. Renewal order status
7. Test or live mode settings

Most payment issues can be resolved by reviewing these settings before investigating further.

Before You Begin #

Before troubleshooting, confirm that:

1. WooCommerce is installed and activated.
2. Flexi Subscription is installed and activated.
3. Your payment gateway plugin is enabled.
4. API credentials are correct.
5. Your merchant account is active.
6. The payment gateway supports recurring billing.

Payment Failures #

A payment failure usually occurs when the initial subscription payment cannot be completed.

Possible causes include:

1. Incorrect API credentials
2. Invalid customer payment details
3. Merchant account restrictions
4. Payment declined by the issuing bank
5. Unsupported payment method

To resolve the issue:

1. Verify your payment gateway configuration.
2. Confirm your API credentials are correct.
3. Check that the payment gateway is enabled.
4. Review the WooCommerce order status.
5. Check the payment gateway logs for error messages.
6. Ask the customer to try another supported payment method if necessary.

Renewal Payment Issues #

Sometimes the initial subscription purchase succeeds, but future renewal payments fail.

Common reasons include:

1. Expired payment authorization
2. Customer’s payment method has expired
3. Automatic recurring billing is not supported
4. Subscription has been placed On Hold
5. Payment gateway rejected the renewal

To troubleshoot:

1. Confirm the subscription is Active.
2. Verify automatic renewals are enabled.
3. Check the renewal order status.
4. Review payment gateway logs.
5. Confirm the customer’s payment method is still valid.

Webhook Errors #

Many payment gateways use webhooks to notify WooCommerce when payment events occur.

If webhooks are not working correctly, you may notice:

1. Payments succeed but subscription status does not update.
2. Renewal orders remain pending.
3. Subscription renewals are not recorded.
4. Payment confirmations are delayed.

To resolve webhook issues:

1. Verify the webhook endpoint configured by your payment gateway.
2. Confirm webhook delivery is successful.
3. Check for failed webhook requests.
4. Ensure your website is publicly accessible.
5. Verify your SSL certificate is valid.

Important: Incorrect webhook configuration is one of the most common causes of subscription synchronization problems.

Sandbox and Test Mode Problems #

Test Mode allows you to simulate subscription purchases before accepting live payments.

Common issues include:

1. Using live credentials in Test Mode
2. Using test credentials in Live Mode
3. Unsupported test payment methods
4. Incorrect sandbox account configuration

To resolve these issues:

1. Verify whether WooCommerce is currently using Test Mode or Live Mode.
2. Use the correct API credentials for the selected mode.
3. Use supported test payment methods provided by the payment gateway.
4. Complete a full test purchase before switching to production.

Common Gateway Configuration Mistakes #

Incorrect gateway configuration is a frequent cause of payment issues.

Review the following settings carefully:

Checking Subscription Status #

If payments appear to fail unexpectedly, review the subscription itself.

Confirm that:

1. The subscription is Active.
2. The next payment date is scheduled.
3. Renewal orders have been created.
4. The linked WooCommerce order exists.
5. Automatic renewals are enabled where applicable.

If the subscription is Cancelled, Expired, or On Hold, renewal payments will not be processed as expected.

Reviewing WooCommerce Logs #

WooCommerce records payment gateway activity, making it easier to diagnose issues.

When troubleshooting, review available logs for:

1. Payment authorization failures
2. API authentication errors
3. Renewal payment failures
4. Webhook delivery errors
5. Communication timeouts

Gateway logs often provide the most detailed explanation of why a payment failed.

Best Practices #

1. Always test payment gateways before accepting live subscriptions.
2. Verify webhook delivery after any gateway configuration changes.
3. Use Test Mode for configuration and development.
4. Switch to live credentials only when testing is complete.
5. Keep WooCommerce, Flexi Subscription, and payment gateway plugins updated.
6. Monitor failed renewal payments regularly.
7. Review payment gateway logs whenever unexpected payment behavior occurs.