Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.smartretry.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.
Reason codeDescriptionTypeSmartRetry retries?
INSUFFICIENT_FUNDSThe payer’s account does not have enough funds to cover the transaction.SoftYes - retried after a delay aligned with typical deposit timing.
DO_NOT_HONORA generic issuer refusal, often triggered by fraud filters or internal bank rules.Soft (context-dependent)Yes - retried with routing and parameter changes to reduce issuer friction.
EXPIRED_CARDThe card’s expiry date has passed.HardNo - the payment method must be updated.
FRAUD_SUSPECTEDThe issuer has flagged the transaction as potentially fraudulent.HardNo - retrying a fraud-flagged transaction worsens the merchant’s risk profile.
STOLEN_CARDThe card has been reported stolen by the cardholder.HardNo - the account is permanently blocked for this payment method.
LOST_CARDThe card has been reported lost by the cardholder.HardNo - the account is permanently blocked for this payment method.
CVV_FAILUREThe CVV provided does not match the issuer’s records.SoftYes - retried using CVV optimization strategies from the Arsenal.
3DS_CHALLENGE_FAILEDThe payer did not complete the 3DS authentication challenge.SoftYes - retried with adjusted 3DS parameters and exemption logic where applicable.
DUPLICATE_TRANSACTIONThe issuer identified this as a duplicate of a recent transaction.SoftYes - retried after a sufficient interval to clear the duplicate window.
INVALID_CARDThe card number or account details are not valid.HardNo - the payment method must be replaced.
VELOCITY_LIMITThe transaction exceeds the number of attempts allowed in a given time period.SoftYes - retried via a different acquirer or after the velocity window resets.
AMOUNT_LIMIT_EXCEEDEDThe transaction amount exceeds a limit set by the issuer or acquirer.SoftYes - retried through an alternative acquirer with a higher limit threshold.
CARD_RESTRICTEDThe card has a restriction that prevents this transaction type, merchant category, or region.Context-dependentDepends on the restriction type. SmartRetry evaluates available routing and parameter options before deciding.

​
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.