Square Decline Codes Explained: What Each One Means and What to Do
A plain-English reference for Square decline codes — GENERIC_DECLINE, CVV_FAILURE, CARD_EXPIRED and more — with whether each is a soft or hard decline and how to recover the payment.
When a Square charge is declined, Square returns a decline code that tells you why — but those codes are scattered across Square’s developer docs and easy to misread. This is the plain-English reference: what each common code means, whether it’s a soft decline (retry can work) or a hard decline (the card is dead), and what to actually do about it.
Common Square decline codes
| Code | What it means | Type | What to do |
|---|---|---|---|
| GENERIC_DECLINE | Bank declined without a specific reason. | Soft | Retry later; if it repeats, request a new card. |
| INSUFFICIENT_FUNDS | Not enough money in the account. | Soft | Retry in a day or two (often clears near payday). |
| CVV_FAILURE | The CVV didn’t match. | Hard | Have the customer re-enter their card. |
| CARD_EXPIRED | The card’s expiration date has passed. | Hard | Send a card-update link for a current card. |
| INVALID_EXPIRATION | Bad/invalid expiration on file. | Hard | Collect a fresh card. |
| CARD_DECLINED | Issuer declined the specific card. | Soft/Hard | Retry once; if it persists, new card. |
| CARD_DECLINED_VERIFICATION_REQUIRED | Bank wants extra verification (SCA). | Soft | Have the customer re-authorize the card. |
| ADDRESS_VERIFICATION_FAILURE | Billing address (AVS) didn’t match. | Hard | Re-collect the card with the correct address. |
| ISSUER_ALERT_CARD_CLOSED | The account/card was closed. | Hard | Card is dead — collect a new one. |
| PAN_FAILURE | Invalid card number. | Hard | Re-collect the card. |
| TRANSACTION_LIMIT | Charge exceeds a card/issuer limit. | Soft | Retry a smaller amount or later. |
| VOICE_FAILURE | Issuer requires cardholder to call the bank. | Hard | Ask the customer to contact their bank, then retry. |
Soft declines vs hard declines
A soft decline is temporary — the card itself is fine, but the charge didn’t go through right now (no funds yet, a velocity limit, a one-off issuer hiccup). The correct move is to wait and retry on a sane schedule: at least 24 hours apart, a handful of times over a few weeks. Retrying immediately or too often gets you nowhere and annoys the bank.
A hard decline means the card will never work again — it’s expired, closed, reported, or the details are wrong. Retrying is a waste; the only recovery path is getting a new card on file, ideally through a one-tap update link rather than a phone call.
Turning decline codes into recovered revenue
Reading codes one at a time in the Square Dashboard doesn’t scale. The point of a recovery tool is to do this routing automatically for every failed payment:
- Soft decline → retry on a decline-aware, card-network-safe schedule until it clears.
- Hard decline / expiry → immediately email a branded card-update page instead of retrying a dead card.
- Recovered → stop everything the instant the payment goes through.
Recoup does exactly this for Square sellers — decline-aware retries plus own-domain dunning, on a flat fee with no revenue share. If you’re seeing a lot of expiry-related codes, it also warns customers before the card expires, so the charge never fails in the first place.
FAQ
What does GENERIC_DECLINE mean on Square?
GENERIC_DECLINE means the issuing bank declined the charge without giving a specific reason. Treat it as a soft decline: retrying later can work, but if it repeats, ask the customer for a new card.
Is CVV_FAILURE a hard or soft decline?
CVV_FAILURE is effectively a hard decline for a retry — the CVV entered didn’t match, so re-charging the same stored card fails. Have the customer re-enter their card details.
What should I do when a Square card is expired?
An expired card (CARD_EXPIRED / INVALID_EXPIRATION) will never charge again — retrying is pointless. Send the customer a card-update link so they can add a current card, then re-charge.
Recover failed Square payments automatically.
Recoup retries declined Square charges on a smart, decline-aware schedule and duns from your own domain — flat monthly, no revenue share. Connect Square read-only and see what you can recover.