KEY TAKEAWAYS
- Soft declines are retryable; hard declines are permanent.
- Expired/pickup/closed accounts map to the dead state.
- Authentication-required responses are challenges, not declines.
- Processors compress codes differently — corroborate on a second gateway when it matters.
- History retains decline codes results for the retention window, then purges them.
- Deduplicate and validate before any paid decline codes request.
When an issuer declines a transaction it sends a reason code. The code is terse, but it tells you what to do next. Here are the groups that matter in practice.
Soft declines (retry makes sense)
- Insufficient funds: the account works but cannot cover this amount. Retry later or with a smaller amount.
- Do not honour (generic): the issuer declined without detail. Often risk-related and sometimes temporary.
- Limit exceeded: a velocity or credit limit was hit. Retrying immediately will not help; wait for the window to reset.
Hard declines (stop retrying)
- Expired card: the date is in the past — the card is definitively unusable.
- Pickup card / lost or stolen: the account is blocked. Never retry; handle the customer carefully.
- Closed account: the issuer has terminated the account.
- Invalid card number: the number does not correspond to a valid account.
Hard declines map cleanly onto the dead state in a card check. Retrying them wastes time and balance.
Authentication-required responses
Some responses mean "finish the authentication first". These are not declines at all — the card may be perfectly live. 3-D Secure step-ups and issuer challenges fall here, and they are the main source of the unknown state in verification. Handle them with an authentication flow, not with retries.
Mapping codes to action
| Code group | Card status | Recommended action |
|---|---|---|
| Insufficient funds / limit | Live | Retry later or lower amount |
| Do not honour | Unclear | One delayed retry |
| Authentication required | Unclear | Step-up authentication |
| Expired / closed / pickup | Dead | Remove from list |
Why processors disagree
Processors compress dozens of issuer codes into a handful of buckets, and their mappings differ. A card one gateway calls dead may be unknown at another. For cards that matter, corroborate with a second gateway before acting. The gateway guide explains how to combine them safely.
Decline codes are the issuer's shorthand for why a specific transaction was refused. They cluster into a few families: insufficient funds, risk and velocity rules, card-status issues, and data mismatches. Reading a code correctly is the difference between retrying something that will never work and fixing something that will.
In verification workflows, declines most often surface as unknown rather than dead: the issuer refused the request without declaring the account closed. That distinction matters — unknown cards deserve a fallback pass, while genuinely dead cards do not.
Key points about decline codes
- Group declines by cause before reacting
- Insufficient funds and velocity limits are common and temporary
- A decline is not proof the card is invalid
- Unknown results after declines get one fallback pass
The mechanics behind decline codes
Nothing in the check moves money: the request asks a question, the issuer answers, and the platform records one of four outcomes against your account. The four outcomes are categorical rather than numeric because decisions are categorical too: proceed, recover, retry or log. Live means the issuer answered and the account is active and chargeable at that moment; it is strong evidence, not a promise about a future charge. Dead means the account is closed, blocked or invalid. It is a final answer for the current state of the card and should never be retried blindly. Keep it in mind whenever decline codes results are reviewed.
Unknown means no definitive answer was received — often an issuer challenge or soft decline — so the card remains unclassified and deserves at most one fallback pass. Behind the scenes, every check follows the same chain: your input, the gateway format, the provider connection, the issuer response and the classification you see. Checks are routed through providers rather than card networks directly, so the same card can behave differently on different routes. It is a small rule that changes how decline codes behaves at scale.
A working routine for decline codes
When results look wrong, diagnose in order: input format, route, provider health, and only then the cards themselves. Keep a small balance buffer so an interrupted run never leaves a half-classified list and the temptation to re-check everything. Decide how each outcome is handled before the run starts; a triage plan written after the results arrive is usually just a spreadsheet. Watch two numbers over time: the classified rate and the error rate. Together they explain almost every surprise in monthly spend. It is a small rule that changes how decline codes behaves at scale.
Reading decline codes results honestly
Errors are free by design: no classification means no charge, so retrying after fixing the cause costs nothing but effort. A result is only as fresh as its timestamp. High-value decisions should use checks that ran close to the moment of the decision. Conflating outcomes is the most expensive habit in this area — an error treated as a dead card discards real inventory, and an unknown treated as live inflates confidence. When a result contradicts other evidence, re-check once after a reasonable interval rather than assuming the checker is wrong. That single habit separates routine decline codes from expensive decline codes.
Scaling decline codes without surprises
Keep one primary gateway and one fallback, and switch on evidence — error spikes and classified-rate drops — rather than on price alone. Document the route, the batch policy and the retry rules next to each production run; six months later that note is the diagnosis. Keep the API key server-side and regenerable; a leaked key is a billing incident as much as a security one. Budget verification against the cost of failure, not against zero; the comparison is what makes spend defensible. Remember it the next time decline codes produces an ambiguous answer.
Boundaries of decline codes
Operators remain responsible for the legal basis on which they hold and process card data. A check does not move money, does not create a charge and does not touch the cardholder's credit file. The platform does not trade card data, and nothing in the system is designed to bypass a cardholder's consent. It sounds obvious until a real run tests it.
Paying for decline codes: the honest math
Top up before long runs; an interrupted run is the most avoidable kind of waste. Funding is prepaid in BTC and LTC; deposits credit automatically once confirmed, and checks draw from the balance per classified result. Billing follows the classification: live and dead results are billed at the gateway price, while errors are free. The API returns the balance on every response, so integrations can meter themselves. That distinction is what keeps decline codes decisions clean.
Security rules for decline codes
Aggregate statistics are computed without exposing individual records, which is why published numbers can be useful without being risky. Check inputs are account-scoped and retained under the platform retention window, then purged by the scheduled cleanup. Regenerate the key the moment compromise is suspected; every check remains attributed in history, so the audit trail survives. Verification data is operational data — treat it with the same care as any other sensitive business record. In decline codes work, that is the difference between a signal and a guess.
What aggregate data says about decline codes
The platform publishes outcome distributions and latency percentiles from real traffic, refreshed monthly, precisely so expectations can be calibrated against reality. Sample sizes matter. Small windows produce noisy percentages, which is why published aggregates carry minimum thresholds. Cost per classified card is the honest metric. A cheap-per-request route with a high failure rate is the most expensive option in practice. Trends beat snapshots: a classified rate that drifts over weeks says more than any single run's result. It is a small rule that changes how decline codes behaves at scale.