Skip to main content

Configure Payment Retry Rules

Zuora

Configure Payment Retry Rules

  1. Last updated
  2. Save as PDF

Zuora allows you to retry payments on a scheduled basis by using scheduled payment runs which will process any invoices that have not been fully paid for customers who have auto-pay enabled. You can also specify the maximum number of consecutive times a failed payment method (for example, credit card) is retried for payment, as well as the ability to define a time period to not retry a payment. For instance, if you define the interval as 8 hours, an automated payment retry will not attempt a payment if the last failed payment was less than 8 hours ago.

This article describes how to enable and configure the payment retry rules in settings for payment processing. For the following customers, we strongly recommend using the Configurable Payment Retry feature instead of configuring the basic payment retry rules described in this article. With Configurable Payment Retry, you can set up custom retry logic or leverage AI capabilities to recover failed payments in a more flexible manner.

Enable and configure tenant-level payment retry rules

To enable payment retry in your tenant and configure the payment retry rules for all payments processed in your tenant:

  1. Navigate to Settings > Payments, and then click Configure Payment Retry Rules.
  2. Select Enable Payment Run retry rules to enable payment retry in your tenant and to configure your payment run retry rules.
  3. Specify the Maximum number of payment failures per Payment Method allowed by entering an integer between 1 to 100. Alternatively, you can leave this field empty but specify a value in the next step to indicate a time interval for your payment retry.

    The number of consecutive failures on a payment method indicates how many consecutive failed payments have been accumulated by using this payment method. It does not indicate how many failed payment retries have been attempted because the payment might be retried with different payment methods.

    Note that the counter for the Maximum number of payment failures per Payment Method allowed begins on April 13, 2010. This is the date the payment retry configuration became available.

  4. When collecting payment for a particular Payment Schedule Item (PSI) through the system-generated Payment Run, and if you have enabled Configure Payment Retry Rules, the payment retry rule applies to the payments collected through the Payment Schedule Item.
    For example:
    1. Schedule a PSI-1 on 1 January 2024 at 10:00 hours.
      • Payment P-1 is generated with ‘Error’ status, and the Payment Method failure count changes from 0 to 1. By default, the PSI-1 will reflect a ‘Pending’ status.
      • The system will create another Payment Run at 11:00 hours. No payment is generated, and the PSI-1 status will reflect ‘Error.’ This is because the Payment Method does not meet the Payment Retry rules.
    2. Without modifying the previous Account’s Payment Method max consecutive failure count, schedule a PSI-2 on 2 January 2024 at 10:00 hours.
      • No payment is generated, and PSI-2 Status will reflect ‘Error’ status as the Payment Method still does not meet the Payment Retry Rules.
  5. To specify the time interval in which you want to retry your payment, enter an integer from 1 to 1000 to indicate the number of hours that must pass after the last payment attempt before the next payment retry takes place. The number of hours must be entered in the field Do not retry payment if last payment attempt was less than __ hours(s) ago. Alternatively, you can leave this field empty but specify a value in the previous step to indicate the maximum number of payment failures allowed per payment method.

    Specifying a time interval in which to retry your payment run prevents a payment attempt if the last failed payment was within the last 'number' of hours. For example, if the last failed payment was at 1PM and the retry interval is 4 hours, then a Payment Run at 2PM will not attempt a payment, but a Payment Run at 6PM will retry payment.

If you want to retry "once a day," Zuora recommends that you enter 22 or 23 hours as it is possible for a payment to be attempted at the end of the payment run on one day and the beginning of the payment run the next day.

Note: After the tenant-level payment retry rules are set up, they become the default retry rules for any payment methods in your tenant, including payment methods that were created through Payment Pages 2.0 and the REST APIs. The retry rules for specific payment methods can be overridden by using the methods described in the following Configure payment retry rules for a specific payment method section.

Configure payment retry rules for a specific payment method

If payment retry is enabled in your tenant, the tenant-level retry rules are applied to the failed payment processing by default. You can configure the retry rules specific to a payment method when creating or updating the payment method.

Configure payment retry rules when creating a payment method

When creating a payment method, use any of the following methods to configure the retry rules specific to a payment method and override the default tenant-level retry rules:

Configure payment retry rules when updating a payment method

When updating a payment method, use any of the following methods to configure the retry rules specific to a payment method and override the default tenant-level retry rules:

  • In the UI, navigate to the Electronic Payment Methods section of the customer account, click Edit below the payment method, and then clear Use Default Retry Rule. In the prompted retry rule fields, enter your customized values by following the same requirements described in the preceding Enable and configure tenant-level payment retry rules section.
  • Use the Update a payment method API operation. Specify false for the useDefaultRetryRule field and optionally specify the maxConsecutivePaymentFailures and paymentRetryWindow fields.

Reset the number of the consecutive failed payments

The number of consecutive failures on a payment method indicates how many consecutive failed payments have been accumulated by using this payment method. If you set the Payment Retry Rules to allow a maximum number failed payments attempts, once that number is reached, Zuora will stop using this payment method to perform payment attempts. If you want to use this payment method to process payments, reset the Consecutive Failed Payments field to 0 by using any of the following methods:

If a customer has entered a new and valid payment method, you can change the Default Payment Method of this account to the new payment method. The next payment run will use the new payment method to collect payment.

If a new default payment method is set, the Consecutive Failed Payments is reset automatically. The number of consecutive failed payments is per payment method. In addition, Consecutive Failed Payments will reset to 0 once a successful payment has been made with the payment method.

Prevent a retry attempt

To prevent a payment retry attempt after the initial attempt failed, configure the Payment Run retry rules by using the following values:

  1. Specify 1 for the Maximum number of payment failures per Payment Method allowed.
  2. Do not enter a value for the Do not retry payment if last payment attempt was less than field.

Once the Payment Method that is set as default on the Account Level has failed to process a successful payment, the next payment run will not try to process a payment for this account.

Handling failed payments

In instances where the payment fails based on the retry rules you set, you must determine the appropriate action to take with those accounts. If your process is to "downgrade" the customer or cancel them, you must also take the corresponding action within Zuora to execute the business logic you deem appropriate.

Because every company uses different policies to handle failed payments, Zuora does not perform any actions automatically when a payment fails. To handle payment failures, you should determine whether you want to cancel the subscription (and cancel in Zuora), or call the customer and ask for a new payment method, suspend service, or perform another action.