> ## Documentation Index > Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Top Decline Reasons, Viva Payments > Top Decline Reasons for Viva Payments stores. Tracked live in Vortex IQ Nerve Centre. How to read it, why it matters, and how to act on it. **Metrics type:** [Supporting Metrics](/nerve-centre/overview#metrics-types-explained) • **Category:** [Payment Gateway](/nerve-centre/connectors#connectors-by-type) ## At a glance > A horizontal **bar chart of the top decline reason codes** behind your declined Viva transactions. The first card to open when [`viv_decline_rate`](/nerve-centre/kpi-cards/viva-payments/decline-rate) jumps. Different reasons need different fixes: `INSUFFICIENT_FUNDS` is genuine, `DO_NOT_HONOR` is issuer-side fraud-flag, `3DS_REQUIRED` is 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`](https://developer.vivawallet.com/apis-for-payments/payment-api/) 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`](/nerve-centre/kpi-cards/viva-payments/3ds-abandonment-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 | ```text theme={null} Top reason concentration = 142 / 412 = 34.5% (below 40% threshold, not skewed) 3DS-related reasons = 42 / 412 = 10.2% (exemption claim review needed) Issuer-flag reasons = (96 + 28 + 12 + 6 + 4) / 412 = 35.4% Customer-side genuine = (142 + 64 + 18) / 412 = 54.6% ``` What the merchant should notice: 1. **`INSUFFICIENT_FUNDS` at 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. 2. **`DO_NOT_HONOR` at 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. 3. **`EXPIRED_CARD` at 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. 4. **`3DS_REQUIRED` at 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. 5. **`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`](/nerve-centre/kpi-cards/viva-payments/decline-rate) | The aggregate rate; this card is its decomposition. | | [`viv_success_rate`](/nerve-centre/kpi-cards/viva-payments/success-rate) | The complement; reason-fix work directly lifts this. | | [`viv_threedsecure_abandon_rate`](/nerve-centre/kpi-cards/viva-payments/3ds-abandonment-rate) | If `3DS_REQUIRED` dominates, abandon rate often spikes too. | | [`viva_payment_methods`](/nerve-centre/kpi-cards/viva-payments/payment-methods) | Method mix often correlates with reason-code mix (AmEx + cross-border = more `DO_NOT_HONOR`). | | [`viv_chargeback_rate`](/nerve-centre/kpi-cards/viva-payments/chargeback-rate) | Approved-then-disputed reasons worth comparing against decline reasons. | | Stripe [`stripe_top_decline_reasons`](/nerve-centre/stripe/stripe_top_decline_reasons) / PayPal [`pp_top_decline_reasons`](/nerve-centre/paypal/pp_top_decline_reasons) | Cross-PSP reason-mix comparison. | | [`viva_revenue_by_country`](/nerve-centre/kpi-cards/viva-payments/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](https://www.viva.com/en/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. | **Cross-connector reconciliation:** | 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. | ***
Documentation cross-reference * [`stripe.stripe_top_decline_reasons`](/nerve-centre/stripe/stripe_top_decline_reasons) * [`paypal.pp_top_decline_reasons`](/nerve-centre/paypal/pp_top_decline_reasons)
## Known limitations / merchant FAQs **"What does `DO_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. *** ### Tracked live in Vortex IQ Nerve Centre *Top Decline Reasons* is one of hundreds of KPI pulses Vortex IQ tracks across Viva Payments and 70+ other ecommerce connectors. Nerve Centre runs the detection layer; Vortex Mind investigates the cause when something moves; Ask Viq lets you interrogate any number in plain English. [Start for free](https://app.vortexiq.ai/login) or [book a demo](https://www.vortexiq.ai/contact-us) to see this metric running on your own data.