Soft decline
DEFINITION
A soft decline is a payment failure caused by a temporary condition, such as insufficient funds or an issuer hold, rather than a permanent problem with the card itself. Because the cause is usually short-lived, it's a strong candidate for an automatic retry rather than a request for a new payment method.
TABLE OF CONTENTS
RELATED TERMS
A soft decline is a payment failure caused by a temporary condition, such as insufficient funds or an issuer hold, rather than a permanent problem with the card or account. Because the underlying cause is often short lived, a soft decline is a strong candidate for a retry rather than an immediate request for a new payment method.
Soft declines sit opposite hard declines, which are generally considered final and aren't retried automatically because the payment method itself is unlikely to work again without a change, such as an expired or canceled card. A hard decline can still lead to a later successful charge in a few specific situations:
An immediate retry is triggered if Account Updater or the customer updates their billing information.
A hard decline can convert to a soft decline during the dunning cycle after a billing information update.
Forced collection can be initiated outside the typical recurring schedule.
That distinction, temporary versus final, is what decides whether a payment failure should be retried automatically or should prompt the customer to take action.
Why it matters
Getting the soft decline versus hard decline distinction right protects revenue without wasting attempts. Retrying a soft decline at the right moment can recover a payment that would otherwise be lost to a temporary issue like a low balance during payday week. Retrying a hard decline just repeats a failure the issuer has already ruled out, which wastes a retry and can even flag the merchant's account with the payment processor for excessive retry activity. Classifying declines correctly also decides whether an invoice needs a dunning email asking the customer to update their card, or simply needs time for the retry to succeed on its own.
Because soft declines are temporary by nature, they are the case where retry timing matters most. Recurly's Intelligent Retries builds a customized retry schedule for each declined charge instead of retrying on a single fixed cadence, so a soft decline gets a more favorable retry window than a blanket schedule would give it.
How to handle a soft decline
When a payment fails, the response is generally handled in a few steps:
Identify where the failure occurred by checking whether a transaction record exists and reviewing the gateway's response message or code.
Classify the decline: a hard decline usually means a card update is required, a soft decline usually means a retry or brief customer action will resolve it, and a validation error points to a configuration fix rather than a payment problem.
Confirm the retry and dunning settings, including whether retries run on a gateway-level or invoice-level schedule and whether customer notifications are enabled.
If the issue persists, test with a different, known-good payment method to rule out a merchant-side configuration problem.
When a payment fails, the invoice can move into dunning depending on how the site is configured. The invoice stays past due while retries run on the dunning schedule, and a successful retry immediately exits dunning and restores the subscription.
Benefits and examples
Different gateway error types follow different retry schedules. For example, a "Try Again" or generic gateway error retries every two days, while an "issuer or processor unavailable" error retries every three days. In both cases the goal is the same: give the temporary condition behind the soft decline time to clear before the next attempt, rather than retrying immediately and hitting the same wall.
Recurly's Intelligent Retries feature draws on historical transaction data to find a more favorable retry window for each declined charge. The system factors in transaction attributes, decline reasons, and past patterns, and the model improves as more transaction data flows through it. Soft declines, being temporary, are where this adaptive timing makes the biggest difference to recovery.
Frequently asked questions
What's the difference between a soft decline and a hard decline? A soft decline comes from a temporary condition, like insufficient funds or an issuer hold, and is a good candidate for a retry. A hard decline is generally considered final and isn't retried automatically, since the payment method itself is unlikely to work again without a change.
Can a hard decline ever turn into something retryable? Yes, in specific cases. A hard decline may convert to a soft decline during the dunning cycle after the customer updates their billing information, or an immediate retry can be triggered by Account Updater or a customer-initiated update.
Does a soft decline automatically retry, or does the customer need to do something? It depends on the cause and the site's dunning configuration. Many soft declines are retried automatically on a schedule, but if the issue persists, the customer may still need to update their payment method or contact their bank.
How does a soft decline affect a subscriber's account? If the payment isn't recovered on the first attempt, the invoice can move into dunning and the subscription may show as past due while retries continue. A successful retry immediately restores the subscription and exits dunning.
Why does Recurly retry some declines on different schedules? Different decline reasons behave differently over time, so a fixed retry cadence isn't equally effective for all of them. Recurly's Intelligent Retries system adapts the timing per transaction based on historical patterns, aiming to retry each soft decline when it's most likely to succeed.
