# Square CARD_DECLINED with cvv_failure on a saved card

## TL;DR
cvv_failure on a saved card means Square sent the transaction with CVV data the issuer rejected, or the saved card was charged in a way that required CVV it did not have. Do not retry the same charge unchanged. Re-collect the CVV from the shopper (Square can verify a saved card with a fresh CVV) or ask for a different card, then charge again.

```text
square CARD_DECLINED with cvv_failure on a saved card
```

## Steps

1. Confirm the decline details: CARD_DECLINED with a cvv_failure reason in the payment response. Success check: your logs show cvv_failure specifically, not expired_card or generic decline.

2. Do not retry the identical request; the CVV outcome will not change on its own. Success check: your retry logic excludes cvv_failure from automatic retries.

3. Present the saved card with a CVV field and ask the shopper to enter the 3-4 digit code, then create the payment with the fresh verification. Success check: the new payment attempt includes newly entered CVV data.

4. If the shopper cannot provide the CVV, offer a different saved card or a new card entry. Success check: the checkout does not dead-end on the failed card.

5. On success, keep the card on file as before; the CVV itself is never stored. Success check: the saved card works for the next charge and no CVV is persisted anywhere.

## When this applies

- Square returns CARD_DECLINED with cvv_failure for a Card on File payment.
- You run one-click or recurring billing against saved Square cards.
- An agent flow retries saved-card charges without re-verification.

## When it doesn't

- New (unsaved) card CVV failures; those are checkout-time typos with simpler handling.
- Expired-card declines; those need a new expiry, not a CVV.
- Square risk or velocity declines; those are not CVV problems.

## Tool + version compatibility

Square Payments API (all current versions), Cards API / Card on File, Web Payments SDK for CVV re-collection.

### "square saved card cvv failed"
Same handling: re-collect the CVV or switch cards.

### "square card on file declined cvv"
Check whether the charge actually needs CVV; some saved-card flows can run without it depending on your settings.

### "square cvv_failure retry"
Retrying the same payload never clears a CVV failure. New verification data is required.

## Why it happens

Card-on-file transactions often run without CVV, but when CVV verification is part of the request (your settings, the issuer's rules, or a verification step), Square submits whatever CVV data accompanies the saved card. If that data is absent or wrong, the issuer fails the CVV check and Square reports CARD_DECLINED with cvv_failure. It is a verification-data problem, not a funds problem.

## Edge cases / pitfalls

- Never store the CVV, even temporarily beyond the single transaction; collect it, use it, discard it.
- If cvv_failure appears on cards that previously charged fine, check whether your Square risk or verification settings changed.
- A shopper who fails CVV multiple times may be guessing; after a few attempts, steer them to a different card.
- Log the decline reason, never the CVV value.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Imxgo8W-yG9XB4h3r_qtPg