Implement payment retry logic with network decline-code handling for soft vs. hard declines

In-depth guide

Steps

1. Classify decline codes returned in the authorization response: hard declines (e.g., do_not_honor_permanent, invalid_account, card_not_supported, stolen_card) indicate the card cannot be used and should not be retried; soft declines (e.g., insufficient_funds, do_not_honor, try_again_later) may succeed on a later retry.
2. For soft declines, implement an exponential backoff retry schedule aligned with network retry rules: Visa and Mastercard allow a maximum of 15 retries over 30 days after an initial decline; exceeding this triggers excessive retry monitoring fees.
3. Do not retry hard decline codes (card blocked, fraud, stolen) under any circumstances — retrying these increases fraud risk and may violate card network excessive retry rules.
4. For insufficient_funds declines on recurring subscriptions, schedule retries toward end-of-month or payroll dates when funds are more likely to be available.
5. Implement idempotency keys on each retry attempt using a new unique key per attempt — do not reuse the same idempotency key across retries as it will return the cached original decline response.
6. After exhausting retries, trigger account updater (VAU/ABU) to check for new card credentials before presenting the cardholder with a payment update prompt.