Skip to main content
When a transaction fails, the issuing bank returns a decline code - a specific reason code that explains exactly why the authorization was refused. SmartRetry reads these codes in real time and uses them to decide whether and how to attempt recovery.

​
What are decline codes?

Decline codes are standardized response codes generated by the issuing bank at the end of the authorization flow. After the card network routes your transaction to the issuer, the issuer evaluates it against account status, fraud rules, balance, and velocity limits - then returns an approval or a specific decline reason. Without decline codes, merchants would have no way to distinguish a stolen card from a temporary funds issue. SmartRetry uses these codes as the primary input to its recovery decision logic. The reasonCode field on the transaction status object contains the specific decline reason. The domain field tells you which part of the payment chain produced it.

​
Hard vs. soft declines

Not all declines are equal. The most important distinction in payment recovery is between hard declines and soft declines.
A soft decline indicates a temporary issue. The underlying payment method is structurally valid, but something situational prevented the authorization from succeeding right now.Common causes include:
  • Insufficient funds at the time of the attempt
  • Temporary fraud filters that may clear on a second attempt
  • Velocity or spending limits that reset over time
  • Network timeouts or transient processor errors
Soft declines are the primary target for SmartRetry’s recovery logic. By analyzing the specific reason code, timing, and issuer behavior, SmartRetry can retry the transaction with a realistic chance of success.

​
Common decline reason codes

The table below lists frequently encountered decline reasonCode values, their type, and how SmartRetry responds to each.
SmartRetry only retries transactions with a realistic probability of success. The retry behavior shown below reflects SmartRetry’s default logic; actual behavior may vary based on issuer signals, transaction context, and your configuration.

​
Using the domain field

The domain field on the status object helps you understand the systemic source of a decline - not just the specific reason code. For example:
  • A CVV_FAILURE with domain: PAYMENT_METHOD points to a data quality issue on the card itself.
  • A FRAUD_SUSPECTED with domain: RISK points to a risk rule at the acquirer or issuer level.
  • A VELOCITY_LIMIT with domain: PROCESSOR points to an acquirer-side limit, not an issuer limit - meaning routing to a different acquirer may resolve it.
Using domain alongside reasonCode gives you a clearer picture of where recovery efforts should focus. See Transaction Statuses for the full list of domains.