square CARD_DECLINED with cvv_failure on a saved card

Square CARDDECLINED with cvvfailure 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.

square CARD_DECLINED with cvv_failure on a saved card

Steps

1. Confirm the decline details: CARDDECLINED with a cvvfailure reason in the payment response. Success check: your logs show cvvfailure specifically, not expiredcard 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 CARDDECLINED with cvvfailure 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 CARDDECLINED with cvvfailure. 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/pstImxgo8W-yG9XB4h3rqtPg