At a glance
Top decline reasons grouped by Square’sfailure_codeenum. The first card to open whensqu_decline_ratespikes. 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) |
- Generic
CARD_DECLINEDat 35% is the diagnostic black box. Cluster check oncard_details.bin(BIN = first 6 digits). INSUFFICIENT_FUNDSat 23.5% is normal. Below 15% suggests issuers obfuscating; above 30% suggests subscription book has too many low-balance customers.EXPIRED_CARDat 15% is rebill-driven. Square’s card-updater catches ~70% via Visa / MC network tokens.CVV_FAILUREat 12% suggests typing errors on Square Online checkout, or fraud testing.CHIP_INSERTION_REQUIREDat 6% is cashier-training territory.
Sibling cards merchants should reference together
| Card | Why pair |
|---|---|
squ_decline_rate | The headline; this card is the diagnostic. |
squ_top_payment_methods | Method mix often correlates with reason mix. |
squ_threedsecure_abandon_rate | Cancel-side metric; pair with this for full picture. |
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 |
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
“GenericCARD_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.