> ## 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, Square > Top Decline Reasons for Square 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 > Top decline reasons grouped by Square's `failure_code` enum. The first card to open when [`squ_decline_rate`](/nerve-centre/kpi-cards/square/decline-rate) spikes. Tells you whether the cause is issuer-side, fraud-side, or expiration. | | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **What it counts** | `COUNT(*) GROUP BY failure_code` over `/v2/payments WHERE status = FAILED`. Top 10 codes shown. | | **Common Square codes** | `CARD_DECLINED` (generic issuer reject), `INSUFFICIENT_FUNDS`, `CVV_FAILURE`, `INVALID_EXPIRATION`, `EXPIRED_CARD`, `INVALID_CARD`, `CARD_DECLINED_CALL_ISSUER`, `CHIP_INSERTION_REQUIRED`, `INVALID_PIN`, `PAN_FAILURE`. | | **Channel context** | Reasons differ wildly by channel. POS skews `INSUFFICIENT_FUNDS` + `EXPIRED_CARD`; Online skews `CARD_DECLINED` generic + `CVV_FAILURE`. | | **Currency** | Currency-neutral. | | **Time window** | `7D`. | | **Alert trigger** | `top reason >40% share` (any single reason dominating signals a specific issue). | | **Roles** | owner, finance, operations | ## Calculation Calculated automatically from your Square data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading. ## Worked example 7-day window, breakdown of 34 declines: | Reason | Count | Share | Channel skew | | --------------------------- | ----- | ----- | ------------------------------------ | | `CARD_DECLINED` (generic) | 12 | 35.3% | Mostly online | | `INSUFFICIENT_FUNDS` | 8 | 23.5% | Mix POS + online | | `EXPIRED_CARD` | 5 | 14.7% | Mostly subscription rebills | | `CVV_FAILURE` | 4 | 11.8% | Online only | | `INVALID_CARD` | 2 | 5.9% | Online (typed wrong number) | | `CHIP_INSERTION_REQUIRED` | 2 | 5.9% | POS (magstripe attempt on chip card) | | `CARD_DECLINED_CALL_ISSUER` | 1 | 2.9% | Online (likely fraud-flag) | Reads: 1. **Generic `CARD_DECLINED` at 35% is the diagnostic black box.** Cluster check on `card_details.bin` (BIN = first 6 digits). 2. **`INSUFFICIENT_FUNDS` at 23.5% is normal.** Below 15% suggests issuers obfuscating; above 30% suggests subscription book has too many low-balance customers. 3. **`EXPIRED_CARD` at 15% is rebill-driven.** Square's card-updater catches \~70% via Visa / MC network tokens. 4. **`CVV_FAILURE` at 12%** suggests typing errors on Square Online checkout, or fraud testing. 5. **`CHIP_INSERTION_REQUIRED` at 6%** is cashier-training territory. ## Sibling cards merchants should reference together | Card | Why pair | | -------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [`squ_decline_rate`](/nerve-centre/kpi-cards/square/decline-rate) | The headline; this card is the diagnostic. | | [`squ_top_payment_methods`](/nerve-centre/kpi-cards/square/top-payment-methods) | Method mix often correlates with reason mix. | | [`squ_threedsecure_abandon_rate`](/nerve-centre/kpi-cards/square/3ds-abandonment-rate) | Cancel-side metric; pair with this for full picture. | | Stripe [`stripe_top_decline_reasons`](/nerve-centre/stripe/stripe_top_decline_reasons) | Same archetype on Stripe. | ## Reconciling against the vendor's own dashboard **Where to look in the Square Dashboard:** > **Reports → Risk Manager → Failed payments** breakdown (where Risk Manager is enabled), or **Reports → Transactions** filtered by `Status: Failed`, grouped by reason. **Why our taxonomy may look slightly different:** | Reason | Direction | | -------------------- | -------------------------------------------- | | Reason-code grouping | Square groups some codes; this card maps 1:1 | | Time zone | Boundary days | **Cross-connector reconciliation:** decline-reason taxonomies differ between PSPs. Square's `CARD_DECLINED` ≈ Stripe's `generic_decline`; Square's `INSUFFICIENT_FUNDS` matches across the industry; Square's `CHIP_INSERTION_REQUIRED` is POS-specific and has no Stripe equivalent. ## Known limitations / merchant FAQs **"Generic `CARD_DECLINED` is 40% of my declines, what does that mean?"** The issuer rejected without specifics. Cluster check: slice by `card_details.bin`. If 60%+ of generic declines come from one BIN, that issuer has a fraud-filter triggered against your store; contact Square support. **"`INSUFFICIENT_FUNDS` jumped 50% week-over-week, normal?"** Often seasonal (post-payday vs pre-payday). If the spike persists 3+ weeks, subscription book quality is degrading. **"`EXPIRED_CARD` is mostly subscription rebills, can I prevent it?"** Square's card-updater (Visa / MC network tokens) automatically refreshes \~70% of US issuers. Remaining 30% need a customer-facing email asking to update card. **"`CVV_FAILURE` rate of 10%+ on Online, what's wrong?"** Either typing UX issues (mobile autofill conflicts) or a fraud test (someone trying card numbers without matching CVV). If clustered on one IP / device fingerprint, it's a fraud test; block via Square Risk filters. **"`CHIP_INSERTION_REQUIRED` keeps coming up, can I stop the magstripe fallback?"** Cashier training reduces it. Some legacy mag-only foreign cards still need magstripe; you cannot fully disable. **"`CARD_DECLINED_CALL_ISSUER` what does that mean?"** The issuer wants the cardholder to call them, almost always a fraud-flag. Tell the customer to call the number on the back of their card. **"Multi-currency, does the breakdown work?"** Yes; `failure_code` is currency-neutral. **"Tap to Pay on iPhone reasons, any unique?"** Mostly the same as Square Reader. One unique: `DEVICE_TIME_OUT` (the iPhone Tap to Pay session timed out); cashier should re-initiate. *** ### Tracked live in Vortex IQ Nerve Centre *Top Decline Reasons* is one of hundreds of KPI pulses Vortex IQ tracks across Square 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.