Decline code reporting
Unified reporting and analytics across all MIDs and acquirers, giving you one source of truth for performance and reconciliation.
- Category
- Reporting
- Capabilities
- 10
- Available on
- All plans
Every refused card payment arrives back with a response code attached, and that code is the only reliable statement of what the issuer actually objected to. Decline code reporting surfaces those raw values, translates the scheme-specific variants into one readable vocabulary, and keeps the original payload alongside the translation so an engineer can always audit the interpretation.
The point of the report is not to count refusals but to make each one legible enough to act on. Codes are grouped into families, ranked by lost value rather than raw volume, and tied to the response your team is permitted to take: reattempt, refresh the credential, request a different authentication path, or stop submitting altogether.
One dashboard reconciles volume, fees, refunds and chargebacks across every acquirer, currency and MID, with exports built for your finance team. You stop stitching spreadsheets together and start acting on the numbers.
Decline code reporting overview
Decline code reporting exists to answer one narrow question: what did the issuer say when it refused this payment, and what does that entitle us to do next.
The report opens on the raw response value returned by the acquirer, preserved exactly as received, with the scheme, the acquirer and the advice text stored beside it.
Nothing is rounded into a category before you have seen the original, because the original is what an acquirer or scheme will refer to if the treatment of a code is ever questioned.
On top of the raw layer sits a normalised vocabulary. Networks describe the same objection with different values, and some acquirers add proprietary ones, so the report maps every variant into a single family such as stale credential, insufficient balance, authentication failure, risk refusal or invalid request.
The mapping is visible and reversible: expanding a family lists the constituent scheme values, so nothing is hidden inside a friendly label. Families are ordered by the value withheld rather than the number of occurrences, which stops a large tail of low-value refusals from crowding out a small family that is quietly taking substantial revenue.
Each family then carries a treatment label and a written playbook note. The label states what scheme rules permit: reattempt within the allowance, refresh the stored credential, take a different authentication path, or cease submitting for this billing event.
The note records your own policy in plain language for the operator reading it. This is deliberately where the report stops.
Deciding how many approvals you achieved belongs to approval rate reporting, watching how one bank behaves over months belongs to card issuer performance reporting, and executing the retry schedule belongs to decline recovery. This page owns the vocabulary and the permitted response, and links out for the rest.
How decline code reporting works
Capture the verbatim response
As each authorisation response returns, the response code, the advice text, the scheme and the acquirer that answered are written together as a single immutable row. The original value is never overwritten by an interpretation, so the raw payload remains available for audit and for engineers debugging an unexpected value.
Map variants into one vocabulary
A maintained mapping table resolves scheme-specific and proprietary values into shared families, so a comparison across networks or acquirers describes the same objection. Any value with no mapping is surfaced as unmapped rather than silently absorbed, which is how new or undocumented codes get noticed instead of disappearing into a bucket.
Rank families by withheld value
Each family is totalled by the currency amount of the payments it refused as well as by count, and the report leads on value. A family of a few hundred refusals on high-ticket orders therefore sits above a long tail of small ones, which keeps attention on the families that actually change the revenue line.
Attach treatment and publish alerts
Every family is tagged with its permitted treatment under scheme rules and carries your written playbook note. Thresholds are set per family against its own baseline, so a family moving out of pattern raises an alert on its own terms rather than waiting for a headline figure to move enough to be noticed.
Why decline code reporting matters
A code is evidence, a total is not
When revenue slips, the useful artefact is the issuer's own statement of what it objected to. Reading families rather than totals turns a vague acceptance dip into something specific: stored credentials ageing out, one authentication route misbehaving, a risk filter reacting to a particular ticket band. That specificity is what lets a payments team fix a cause instead of experimenting on symptoms.
Attempt discipline protects your standing
Schemes restrict how often a refused payment may be submitted again, and the restriction depends on the value the issuer returned. Publishing the permitted treatment beside each family gives operators and automated jobs one shared answer, which keeps submissions inside the allowance, avoids fees spent on requests that cannot succeed, and keeps your attempt behaviour explainable if it is ever reviewed.
Regulatory notes for decline code reporting
Attempt limits under scheme rules
Visa and Mastercard both restrict how a refused authorisation may be handled, and the restriction follows the value the issuer returned. Some values may not be submitted again at all, while others carry a capped allowance for the same billing event.
Exceeding those limits attracts fees and, at volume, scheme scrutiny.
Holding the permitted treatment against each code family is a practical control.
It gives automated jobs and human operators the same instruction, and it leaves a written record of why a given payment was or was not submitted again, which is the record an acquirer will ask for if attempt behaviour is queried.
Handling stored credentials correctly
Where a code family indicates that a stored card is no longer usable, the correct response is to refresh or replace the credential rather than to keep presenting it.
Scheme credential-on-file rules expect a merchant to act on that signal, and repeatedly submitting a credential the issuer has already rejected is treated as poor practice.
The report distinguishes these families explicitly so the workflow routes them to a credential update path. Where an updater service is not available for a card, the family flags for cardholder contact instead, which keeps the response inside the rules without abandoning the payment.
Decline code reporting use cases
Membership collection batch
A gym group collecting monthly dues sees a batch refused and needs the families split before contacting anybody. Cardflo separates stale-credential values, which route to a credential refresh, from balance-related values sitting inside their reattempt allowance, so two different messages go to two different groups of members rather than one blanket email.
Timed ticket release
A promoter releasing seats at a fixed hour watches response families live as the window opens. Cardflo shows risk refusals concentrating on one card product above a set basket value, which identifies the caution as bank-side rather than a checkout defect and avoids a needless configuration change part-way through the release.
Second market launch
A retailer opening a new European market finds invalid-request values dominating week one. Cardflo expands the family to the constituent scheme values and the request payload behind them, exposing a formatting fault in the address fields sent for that country, which is a merchant-side defect no acceptance percentage would have named.
Month-end write-off review
A finance team closing the ledger exports code-level rows to divide refusals that may still convert from those permanently blocked. Cardflo labels each family with its permitted treatment, so orders behind blocked families are written off at once while the remainder stay open as genuinely recoverable.
Decline code reporting by the numbers
In most card portfolios the large majority of refused payments resolve into a handful of families, which is why a ranked family view is more actionable than a long list of individual scheme values.
The catch-all 'not honoured' value commonly makes up a substantial slice of refusals, so cross-tabulating it against value, market and card product is usually the only route to a diagnosis.
Codes are written as responses arrive, so a family emerging inside a billing run or sale window can be read during the event rather than in the following day's summary.
Methodology: these figures are illustrative ranges drawn from published industry data and observed merchant cohorts, not guarantees. Actual results depend on your risk profile, card mix, geography and acquiring setup, and are confirmed only in your own pricing and approval terms.
Related terms
Talk to our team about a live rollout across our acquirer partners' rails.
What you get with Decline code reporting
- Read the verbatim response code and issuer advice text captured for every refused authorisation.
- Translate Visa, Mastercard, Amex and local scheme variants into one normalised code family.
- Rank code families by the value they withheld, so effort follows money rather than counts.
- See which families are safe to reattempt and which the scheme rules forbid resubmitting.
- Track code drift week on week, so a newly appearing family is caught while it is still small.
- Separate genuine credential problems from generic refusals that carry no diagnostic detail.
- Filter any code family down to a single MID, market, card product or billing run.
- Attach a written playbook entry to each family so operators respond consistently.
- Export code-level rows over the API for your own risk models and finance write-offs.
- Alert on a single family crossing its own baseline, not just on headline acceptance.
A short scoping call, then a written plan for your MIDs.
Questions about Decline code reporting
What does decline code reporting tell me that an acceptance figure cannot?
An acceptance figure states the size of a problem. A response code states its nature.
Two merchants can sit at the same acceptance level with entirely different causes: one is losing payments to stale stored credentials, the other to an authentication path that keeps failing.
Only the code breakdown separates those, because the code is the issuer's own description of the objection. That is why the code view is a diagnostic surface and the acceptance view is a measurement surface, and why they belong on separate reports.
Why do the same codes mean different things across schemes?
Each network maintains its own response-code list and its own advice text, so the value returned for a refused payment depends on which scheme carried it. Some acquirers add proprietary values on top, and a few pass through gateway-level errors in the same field.
The report keeps the original value and the acquirer that returned it, then maps it into a normalised family, so a comparison across scheme boundaries is meaningful without hiding what the network actually said.
How do I know which codes I am allowed to submit again?
Scheme rules restrict reattempts on values that indicate a permanent obstacle, and they cap the number of attempts permitted on values that indicate a temporary one.
The report labels each family with its permitted treatment, so an operator reading it does not have to hold the rulebook in their head.
Where a family is capped rather than blocked, the label states the remaining allowance for that billing event, and the recovery workflow itself lives on the decline recovery page.
What is a generic refusal, and can anything be done about one?
A generic refusal is a value the issuer returns without disclosing a reason, most often the catch-all code that simply says the payment was not honoured. It is usually a risk decision at the bank rather than a fault in your request.
It cannot be diagnosed from the code alone, so the report cross-tabulates it against ticket value, market, card product and the authentication path used, which is normally enough to show which slice of traffic is triggering the caution.
How quickly do new codes appear in the report?
Codes are written as the authorisation response is received, so a family that starts appearing during a billing run is visible within minutes rather than at the end of a reporting cycle.
That matters most for scheduled runs and short sale windows, where a rule change at one bank can affect a whole batch before anyone reviews a daily summary.
Can I keep a written policy against each code family?
Yes. Each family carries an editable playbook note, which is what operators and support staff read when they open a refused payment.
Keeping the policy attached to the code rather than in a separate document means the instruction, the evidence and the permitted treatment stay in one place, which also makes the reasoning auditable when a scheme or acquirer asks how attempts are governed.
Related guides.
See how Cardflo compares.
Ready to improve your payments setup?
Tell us about your business. We'll match you with the right acquiring partners and the right route, typically inside a week.