Dunning Payment Retries

Payment Retry Schedule provides a way to customize the retry process by specifying details about the retry process such as the number of retry attempts, the retry interval, the minimum payment amount, account category which associated accounts will be evaluated for retry, and error codes applicable for the retry process.

Failure reason code mapping

There are two terms that need to be taken into account in scope of failure reasons: Generic Reason Codes and Payment Processor Reason Codes. Let’s take a quick look at both of them.

Each Payment Processor contains Payment Processor Reason Codes, a list of errors that appear in case the payment fails. To evaluate a payment for the retry process, these errors should be mapped to one of the Generic Reason Codes specified in the Payment Retry Schedule.

You can associate Payment Processor Reason Codes with corresponding Generic Reason Codes by mapping them manually or by uploading a preconfigured CSV file.

Maximum amount of retries and retry interval

When creating a new Retry Schedule, specify the number of retry attempts and the interval for how often each retry should occur.

For example, if the maximum amount of attempts is “5” and the retry interval is “1”, the payment will be retried five days in a row until it is successfully processed. If the retry fails after the maximum number of attempts, it will not be retried.


The Retry Schedule can be either in ACTIVE, DRAFT, or INACTIVE status.

DRAFT You can create a Retry Schedule in either DRAFT or ACTIVE status. When the Retry Schedule is in the DRAFT status, it’s not yet in use. Once moved to ACTIVE from DRAFT, the schedule cannot be returned to DRAFT state.
ACTIVE Once the status moves to ACTIVE, it means that billing accounts associated with this Retry Schedule start to be evaluated for the retry process.
INACTIVE When you no longer need a Retry Schedule, move it to the INACTIVE status. It can later be changed back to ACTIVE status.

What is a Retry Series?

A Retry Series is automatically created for each failed payment that is eligible for the retry process and hasn’t been previously retried. The failed payment that is a base for creating a Retry Series is marked as the original_id, and after every retry attempt, a new payment is created (payment_id). If after the first retry attempt, the payment fails once more within the same Retry Series, a new payment is created and the primary payment is noted as previous_id.

The Retry Series life cycle includes four statuses.

ACTIVE A new Retry Series is created in the ACTIVE status.
COMPLETED If the payment is successfully completed within the number of attempts specified in the max_retries property, a Retry Series moves to the COMPLETED status.
If the status of the retried payment is EXTERNAL REVIEW, the Retry Series moves to the COMPLETED status.
INACTIVE If the retried payment fails with a reason code that isn’t mapped on to any of the Generic Reason Codes from the Retry Schedule, the Retry Series moves to the INACTIVE status.
FAILED If the payment retry count reaches the number specified in the max_retries property, but the payment still fails, the Retry Series moves to the FAILED status.

What payments are evaluated for the Retry Process?

To be evaluated for the retry process, the failed payment should meet all conditions from the Retry Schedule: the specified account category, the payment amount exceeds the minimum amount specified, and the Generic Reason Code is mapped to the Payment Processor error which appears on the payment failure.

Also, the payment should be created within the date range of today minus the number of days specified in the retry_interval_days parameter of the Retry Schedule.

Let’s take a look at a few examples.

Payments that have never been retried

For the new payments (never been retried) that occurred on October 2-6, new Retry Series are created. However, only payments with the occurred_on value which equals “today” (October 6) minus the retry_interval_days value from the Retry Schedule are retried during the current payment retry process. In our example, these are the payments created on October 2.

Payments that have already been retried

The existing payments (have been previously retried) are retried only if they occurred “today” (October 6) minus the retry_interval_days value from the Retry Schedule. To be retried, the payment should be the latest one in the associated ACTIVE Retry Series.

Payments with the modified retry interval value

In case theretry_interval_days value was modified and there are payments for which the Retry Series is already created but the date when they should have been retried was missed (due to the change), the processor will retry them as well once the Retry Payment job is run.

Only payments that failed after the ProcessAutoRecurringPaymentsQuartzJob is completed are evaluated for the retry process. You can find a list of them in Gotransverse UI (1.0) Receivables > Payment Collection > Global Errant Payments.

What jobs do you need?

To set up the Payment Retry process, you are going to need two jobs: Payment Retry Processor and Payment Retry Updater.

The Payment Retry Processor job provides a way to evaluate payments applicable for the retry process, create a Retry Series, and actually retry the appropriate payments. The Payment Retry Updater job is a component for updating the information about payments that have already been retried.

Cron Job Scheduler

With Cron intervals, you can configure the automatic job runs specifying the desired time. To set up the automatic job runs, when creating a job, in the cron_expression parameter, specify time when the job should be run by using a Cron expression. Here is a sample of how this value may look like:

0 0 6 * * ? The job will be run every day at 6 am.

To run the job manually, set the can_run_manual parameter to true, and follow steps in the Running the job section.

Next steps

Payment Retries functionality is available at Gotransverse user interface 2.0 and API. For more information, refer to the following: