Skip to main content
When passing originalDeclineCode, the recovery engine automatically determines the optimal recovery path for each decline type. The more context you provide, the higher the recovery rate.

​
Supported Categories

CategoryExample CodesWhat Happens
Recoverableinsufficient_funds, do_not_honor, call_issuer, try_again_later, card_declined, generic_decline, expired_cardThe engine applies the optimal recovery strategy for this decline type. Recovery is attempted automatically.
Authentication requiredauthentication_requiredThe card is valid but the issuer requires the customer to authenticate (3-D Secure). A merchant-initiated retry cannot complete a customer-present challenge, so no retry is attempted. Webhook notification sent.
Blockedfraudulent, lost_card, pickup_card, restricted_card, fraud_suspectedTransaction is blocked to protect the merchant. No recovery attempted. Webhook notification sent.
UnknownAny unrecognised codeConservative recovery attempted.
Not providednull / omittedRecovery attempted using available transaction signals.
Always pass the originalDeclineCode from your payment processor. The engine’s recovery rate improves significantly when it can read the specific decline reason. Passing no code results in a generic recovery attempt.

​
Why Decline Codes Matter

Different declines need different strategies:
  • insufficient_funds → Retry on payday, end of month, or after a known billing cycle
  • do_not_honor → Retry with optimised timing and issuer-trust signals
  • expired_card → Skip the retry, refresh the token via the account updater, and prompt the customer to update their card
  • authentication_required → Skip the retry — the customer must re-authenticate the card through your checkout
  • fraudulent → Block immediately — retrying causes chargebacks and damages merchant health
The Revtain engine encodes these patterns based on industry-wide observation. By passing the decline code, you let the engine pick the right path automatically.

​
What Happens with Blocked Codes

For blocked decline codes (e.g., fraudulent, lost_card), Revtain:
  1. Returns 403 Forbidden immediately
  2. Fires a recovery.blocked webhook
  3. Records the transaction as blocked
  4. Does not attempt any retry on any gateway
Do not retry blocked transactions on your own. Repeatedly attempting fraudulent or lost-card payments will trigger chargebacks and damage your merchant account standing.

​
What Happens with authentication_required

Some issuers — increasingly common in Europe under Strong Customer Authentication — decline a charge because the cardholder must complete 3-D Secure. The card itself is valid. A retry from Revtain runs without the customer present, so it cannot satisfy a 3-D Secure challenge. Retrying the same charge wastes attempts and erodes issuer trust. Instead, Revtain:
  1. Returns 403 Forbidden immediately
  2. Fires a recovery.blocked webhook with declineCode: "authentication_required" and recommendedAction: "request_card_update"
  3. Does not attempt any retry
Route the customer back through your own checkout to re-enter or re-confirm their card. Your payment gateway runs the 3-D Secure challenge there — once authenticated, submit the resulting token to /api/recovery/execute as normal.