At a glance
A horizontal bar chart of the top decline reason codes behind your declined Viva transactions. The first card to open whenviv_decline_ratejumps. Different reasons need different fixes:INSUFFICIENT_FUNDSis genuine,DO_NOT_HONORis issuer-side fraud-flag,3DS_REQUIREDis exemption misconfiguration.
| What it counts | COUNT(transactions) GROUP BY DeclineReasonCode where StatusId IN (E, M), ordered descending, top 10. Codes mapped from Viva’s reason taxonomy. |
| API endpoint | /api/transactions with status filter E + M; EventId and ResponseCode fields drive the grouping. |
| Currency | Currency-neutral (count, not amount). |
| 3DS-rejection codes | Counted (e.g. 3DS_REQUIRED, 3DS_FAILED). 3DS abandons (X) are NOT in this card; see viv_threedsecure_abandon_rate. |
| Refunds / disputes | Not relevant. |
| Recurring rebill failures | Counted. Reason codes for rebills are usually EXPIRED_CARD, INSUFFICIENT_FUNDS, DO_NOT_HONOR. |
| Channels | Online + POS + recurring blended. POS declines are usually PIN_INCORRECT or INSUFFICIENT_FUNDS (genuine). |
| Time window | 7D vsP. |
| Alert trigger | top reason >40% of all declines (skewed-distribution sentinel). |
| Roles | owner, finance, operations |
Calculation
Calculated automatically from your Viva Payments data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
A Greek subscription cosmetics retailer (“Athina Beauty”) on Smart Checkout, monthly rebills, no POS. Window 26 Apr 26 to 02 May 26. Total declines: 412.| Decline reason code | Count | % of declines | Likely cause |
|---|---|---|---|
INSUFFICIENT_FUNDS | 142 | 34.5% | End-of-month rebills; many customers between paydays |
DO_NOT_HONOR | 96 | 23.3% | Issuer-side fraud-flag, suspicious cluster from one BIN |
EXPIRED_CARD | 64 | 15.5% | Recurring rebills against on-file cards that expired |
3DS_REQUIRED | 42 | 10.2% | Exemption claimed but issuer pushed back |
CARD_VELOCITY_EXCEEDED | 28 | 6.8% | Customer hitting issuer daily-spend cap |
INVALID_CVC | 18 | 4.4% | Customer mistyped CVV; benign |
STOLEN_CARD | 12 | 2.9% | Customer reported card stolen, transaction blocked |
PICKUP_CARD | 6 | 1.5% | Issuer asking for card to be retained (rare on CNP) |
RESTRICTED_CARD | 4 | 1.0% | Card flagged for limited use |
INSUFFICIENT_FUNDSat 34.5% is consistent with subscription billing. End-of-month rebill failures are dominated by between-paydays cash-flow cycles. Smart Retry over 3 to 7 days typically recovers 30 to 50% of these (customer’s salary lands, retry succeeds). Track recovery in the upstream subscription tool.DO_NOT_HONORat 23.3% is the actionable concentration. This code is issuer-side “we won’t tell you why we declined”. Sudden clusters from a specific BIN range = issuer fraud-filter triggered (often by velocity, geography, or a Mastercard/Visa security-incident broadcast). Flag to Viva merchant support for a routing review; in some cases retrying via a different network token unlocks acceptance.EXPIRED_CARDat 15.5% is a network-token gap. If you’re using Viva network-token integration with VTS / MDES, expired-card declines should be near zero (the token auto-updates on issuer reissuance). 15.5% suggests you’re storing raw PANs rather than tokens. Migrate to network tokens for an immediate 10 to 15pp uplift in rebill success rate.3DS_REQUIREDat 10.2% means exemption claims are being rejected. You’ve claimed an SCA exemption (probably MIT or low-value) but the issuer disagrees. Common cause: claiming MIT on a customer-initiated rebill, or claiming low-value above the EUR 30 threshold. Audit your exemption logic.STOLEN_CARD+RESTRICTED_CARD+PICKUP_CARD= 22 transactions. Small absolute count but each represents a confirmed-fraud signal. If volume here grows, your acquisition funnel is attracting fraud-prone traffic (review affiliate / programmatic ad sources).
Sibling cards merchants should reference together
| Card | Why pair it with Top Decline Reasons |
|---|---|
viv_decline_rate | The aggregate rate; this card is its decomposition. |
viv_success_rate | The complement; reason-fix work directly lifts this. |
viv_threedsecure_abandon_rate | If 3DS_REQUIRED dominates, abandon rate often spikes too. |
viva_payment_methods | Method mix often correlates with reason-code mix (AmEx + cross-border = more DO_NOT_HONOR). |
viv_chargeback_rate | Approved-then-disputed reasons worth comparing against decline reasons. |
Stripe stripe_top_decline_reasons / PayPal pp_top_decline_reasons | Cross-PSP reason-mix comparison. |
viva_revenue_by_country | Country-level breakdown often surfaces issuer-region patterns. |
Reconciling against the vendor’s own dashboard
Where to look in the Viva Payments Dashboard: viva.com/business/account/login. Closest comparable views:Viva Business → Risk → Decline analysis (where enabled, reason-code grouping)
Viva Business → Sales → Reports → Transactions (filter Status: Failed; the per-row reason column)Why our breakdown may legitimately differ:
| Reason | Direction | Why |
|---|---|---|
| Code grouping | Marginal | Viva groups some sibling codes (e.g. INSUFFICIENT_FUNDS and EXCEEDS_WITHDRAWAL_LIMIT) under one bucket; we preserve granular codes. |
| Time zone | Boundary days off | Athens / Cyprus / customer-issuer timezones vs UTC. |
| Code translation | Marginal | Viva normalizes some scheme-specific codes; the merchant-facing reason text may differ between the Viva Dashboard and ISO-standard 8583 codes. |
| Comparison | Expected relationship | When divergence is legitimate |
|---|---|---|
viv_top_decline_reasons ↔ Stripe / PayPal top reasons | Top reasons usually overlap | Customer-side reasons (insufficient funds, expired card) appear consistently. PSP-specific routing rules cause differences in DO_NOT_HONOR distribution. |
Known limitations / merchant FAQs
“What doesDO_NOT_HONOR actually mean?”
The issuer has refused the transaction without specifying why, usually because their internal fraud or risk system flagged it. Common drivers: velocity (too many transactions on the same card in a short window), geography mismatch, BIN-level promotional or security broadcasts, or a Mastercard / Visa security incident. The fix is rarely on your side; retrying via a network-token-backed flow occasionally unlocks acceptance, and routing to a different acquirer (where multi-acquirer is available) sometimes helps. If a single BIN is producing a sudden spike, escalate to Viva merchant support.
“Should I retry on INSUFFICIENT_FUNDS?”
Yes, with intelligent timing. Customers between paydays often have the funds within 1 to 5 days. Smart Retry handles this automatically over a 3 to 7 day window. Don’t retry within an hour, that just exhausts attempts.
“3DS_REQUIRED is dominating, what’s wrong?”
You’ve claimed an SCA exemption that the issuer isn’t accepting. Common mistakes: (1) claiming MIT (merchant-initiated transaction) on a flow the customer is actively in (it should be a CIT, customer-initiated), (2) claiming low-value above EUR 30, (3) claiming trusted-merchant when the customer hasn’t actually whitelisted you. Audit your exemption logic by reason code, expect zero 3DS_REQUIRED if exemptions are configured correctly.
“How do I lower EXPIRED_CARD declines on rebills?”
Network tokens (VTS for Visa, MDES for Mastercard). When the customer’s physical card is reissued, the issuer auto-updates the network token; rebills against the token continue working without merchant action. Migrate from raw-PAN storage to network-token storage for an immediate 10 to 15pp uplift in rebill success.
“STOLEN_CARD and PICKUP_CARD, do I need to act?”
Volume matters. A small steady stream is normal background. A sudden cluster suggests fraud-prone traffic in your acquisition funnel; review affiliate / programmatic ad sources from the same window. Don’t try to suppress these declines, the issuer is correctly preventing card-not-present fraud on your behalf.
“Why is my reason mix different from another merchant’s?”
Two factors. (1) Vertical: subscription stores see more INSUFFICIENT_FUNDS and EXPIRED_CARD; one-time DTC sees more DO_NOT_HONOR. (2) Geography: cross-border traffic sees more DO_NOT_HONOR; domestic traffic sees more genuine customer-side codes.
“JP Morgan acquisition, did reason codes change?”
No. Reason codes are determined by the issuer and the scheme, not by Viva or its parent.
“Can I see reason codes per BIN range?”
Not on this card. The Viva Dashboard’s Risk view (where enabled) does support BIN-level grouping. A per-BIN-range card is on the roadmap.
“How fast does Viva publish new reason codes?”
Codes flow through within 1 to 5 minutes of the decline; small lag for the freshest minutes during high-volume sync windows.