Skip to main content

Use the Configurable Payment Retry feature


Use the Configurable Payment Retry feature


Activation of the retry logic

Upon the completion of a payment run, Configurable Payment Retry’s logic is activated. Initial payments from the payment run that are not successful will be sent into the retry system and will trigger the configured retry logic.

If you configured your retry logic manually based on the payment gateway response codes, the retry logic that you defined for the customer group is executed. If you enabled Smart Retry, the AI-driven retry logic is executed to retry failed payments at optimal times. For details about how to configure these two approaches, see Edit retry logic for a customer group.

When a retry attempt is executed in Configurable Payment Retry, a payment run with the record of the payments being attempted is also created and visible in Payment Runs of Zuora Payments. Retry attempts are executed in batch on the hour rather than continually being executed. A maximum of 24 payment runs can be made in a day. Hence, the retry logic cannot be set to retrying sooner than every hour.

Please ensure that out-of-box payment retry is not running in Zuora environment, and the Callout Notification setting for Configurable Payment Retry is configured. Failure to disable the out-of-box payment retry while running Configurable Payment Retry might result in disruption to the service. See Configure the Configurable Payment Retry feature for details.

See Payment Runs for more information about payment runs.

Auto-pay settings

See the table below for the invoice-level and account-level auto-pay settings for different retry levels in different retry stages. 

Retry level Invoice-level auto-pay setting Account-level auto-pay setting
Invoice Turned off when the retry cycle starts. No change during invoice retry cycles.
  • Once the retry cycle starts, auto-pay is turned off.
  • If no payments have been collected, auto-pay stays off.
  • If payments have been collected, auto-pay is turned on. 

Once the account-level and/or invoice-level auto-pay is turned off, invoices or debit memos for the account will not be picked up in the next payment run. If you want the invoices and debit memos to be picked up during a payment run, you need to manually turn on the auto-pay both on the account level and the invoice level. You must also make sure a valid electronic payment method is configured for the accounts.

View account-level and invoice-level retry status

Once Configurable Payment Retry is installed, a custom field "Retry Status" will be added to the Account and Invoice (or Debit Memo, if Invoice Settlement is enabled on your tenant) objects. You can use the values of these two fields to determine the retry and payment status.

The values of these two fields are managed by Configurable Payment Retry based on the settings and the retry logic. Zuora recommends that you do not change the values of these two fields. 

To view the retry status of an account, navigate to the details page of the account.


To view the retry status of an invoice or debit memo, navigate to the Additional Fields section on the details page of the invoice or debit memo.


Account retry status

  • In retry: The account is active in a retry process. It indicates that either an invoice of the account or the account enters a retry cycle. 
  • Failure: The retry process for the account has completed with errors and payments have not been collected.
  • Blank: All accounts start with this status (no value for the field). Once the account or an invoice of the account enters a retry process, this field begins to be updated. If a retry cycle completes and payments are collected, this field becomes blank again.

Invoice or debit-memo retry status

  • In retry: The invoice or debit memo is active in a retry process.
  • Complete: The retry process has completed and the payment has been collected.
  • Complete - External: The retry process has completed due to a payment made outside of the retry process. It means that an ad hoc payment has been made during the retry process. The next time Configurable Payment Retry attempts to retry a payment, it recognizes the payment and updates the status to Complete - External.
  • Failure: The retry process has completed and no payments have been received.
  • Blank (no value): All invoices or debit memos will start with this status (no value for the field). Once the account or the invoice (debit memo) enters the retry process, this field will begin to be updated. The field will never be blank again unless it is manually modified to be blank (which is not recommended).

View retry attempts

To monitor the progress of your retry logic, complete the following steps.

  1. In your Zuora tenant, click the desired account and select Transactions > Payments.

  2. View the Status of each payment.

    • Error - Payment was unsuccessful and is in retry attempt
    • Processed - Payment was successfully processed


  3. Click the Payment Number to view payment details.


    The Payment window opens:


    • Error Message: Displays the error message from the selected payment gateway.
    • Comment: Displays information about the status of the account in the retry process. You may have noticed that attempt numbers in the comment start with 2. This is because Attempt 1 is triggered via a payment run in Zuora and subsequent retries are triggered in Configurable Payment Retry.