Skip to main content

Managed Recurring Retries

Managed Recurring Retries helps improve the handling of failed recurring payments by determining whether a declined rebill should be retried, or whether the subscription should be paused or cancelled.

note

Managed Recurring Retries must be enabled and configured by your NetValve account representative or support team. Contact them to get started.

Overview​

Previously, a declined rebill for a Gateway Managed Recurring subscription would immediately pause the subscription.

With Managed Recurring Retries, NetValve evaluates the reason for the decline and determines the appropriate action:

  • Retry the payment after an appropriate interval
  • Pause the subscription for further review or corrective action
  • Cancel the subscription when the decline indicates that further attempts are unlikely to succeed

This provides more flexible handling of temporary payment failures while avoiding unnecessary retry attempts for permanent or non-recoverable declines.

How Failed Payments Are Handled​

NetValve evaluates each declined rebill based on the decline reason and applicable card-network guidance.

Temporary declines​

Temporary issues may include insufficient funds, issuer unavailability, or other recoverable conditions. These transactions can be retried automatically when Managed Recurring Retries is enabled and retry timing is available through either:

  • Card-network guidance
  • The configured merchant retry schedule

If retries are not enabled or no applicable retry schedule is available, the subscription is paused.

Payment-data issues​

Declines caused by payment-data issues, such as an expired card or invalid card information, generally result in the subscription being paused.

This allows the payment method to be reviewed or updated before another payment attempt is made.

Permanent declines​

Declines indicating that the payment method is no longer usable, such as a closed account or a reported lost or stolen card, may result in the subscription being cancelled.

Retry decisions are based on the decline response, applicable Visa or Mastercard guidance, and the configured retry policy.

Retry Timing​

When a failed rebill is eligible for retry, NetValve determines the next attempt date using one of the following methods.

Network-guided timing​

For certain decline responses, the card network specifies when another payment attempt should be made. When this guidance is available, NetValve follows the network-recommended retry timing.

Merchant retry schedule​

When the card network does not provide specific retry timing, NetValve uses the retry schedule configured for the client.

For example, a retry schedule could be configured as:

  • First retry after 1 day
  • Second retry after 3 days
  • Third retry after 7 days

If all configured retry attempts are unsuccessful, the subscription is paused.

Whenever a retry is scheduled, the subscription's nextAttemptDate is updated to reflect the retry timing determined above — from network guidance or the merchant retry schedule. This field is available when retrieving the subscription through the existing subscription APIs.

When a retry succeeds:

  • recurringTransactionStatus is updated to COMPLETED
  • nextAttemptDate is recalculated from the subscription's original scheduled date, not the date the retry succeeded — the subscription resumes its original cadence rather than rebasing off the retry

Retry limits are also applied to prevent excessive payment attempts within a defined period. When the applicable retry limit is reached, the subscription is paused.

Retry Schedule Example​

A retry schedule consists of one or more retry stages. Each stage defines how many days NetValve should wait before making the next payment attempt.

For example:

Example retry schedule — 3 stages
{
  "intervals": [
    { "stage": "R1", "days": 1 },
    { "stage": "R2", "days": 3 },
    { "stage": "R3", "days": 7 }
  ]
}

In this example:

  • R1 schedules the first retry after 1 day
  • R2 schedules the next retry after 3 days
  • R3 schedules the final retry after 7 days

If the payment attempt at R3 is also unsuccessful and no further retry stage is configured, the subscription is paused.

Retry Schedule Scope​

Retry schedules are typically configured at the client level and apply to subscriptions belonging to that client.

Where supported, a subscription-specific retry schedule can also be configured to override the client-level schedule when different retry timing is required.

Card-network guidance takes precedence over the configured merchant retry schedule when the network provides specific retry timing for a decline.

The merchant retry schedule is used when no network-specific retry timing applies.

Prerequisites for Merchant-Scheduled Retries​

Managed Recurring Retries can be enabled or disabled at the client or MID level.

For temporary declines to use merchant-configured retry timing:

  1. Managed Recurring Retries must be enabled for the applicable client or MID.
  2. A retry schedule must be configured at the client or subscription level (see Retry Schedule Scope above).

Configuring or Updating a Retry Schedule​

Retry-policy configuration is managed through NetValve.

To enable Managed Recurring Retries, create a new retry schedule, or update an existing schedule, contact your NetValve account representative or support team.