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 API returns exact DOMAIN.REASON values in reasonCode. The following source-backed examples are not a retry-policy matrix; determine any retry action from your SmartRetry configuration and the transaction context.

​
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 PAYER_ACCOUNT.INVALID_SECURITY_CODE reason points to a security-code issue.
  • A PAYER_ACCOUNT.SUSPECTED_FRAUD reason identifies a payer-account fraud outcome.
  • An AUTH.3DS_CHALLENGE_FAILED reason identifies an unsuccessful 3DS challenge.
Using domain alongside reasonCode gives you a clearer picture of where recovery efforts should focus. See Transaction Statuses for the full list of domains.