Soft vs. hard declines
Declines fall into two categories. Square's docs don't use these labels, but the split still decides what to do next.
Temporary. The card still works.
The payment failed this time, for example because of low funds. A retry later can succeed.
INSUFFICIENT_FUNDS TEMPORARY_ERRORUsually final. Retrying won't help.
The card has expired, or the bank can't find the account behind it. The customer needs to update their card details or use a new card. Recoura covers these.
CARD_EXPIRED INVALID_ACCOUNTWhen a subscription payment fails, Square immediately emails the customer an invoice with a link to pay, then retries the card on days 3, 6 and 9. It doesn’t cancel the subscription for non-payment; that’s left to you. For an invoice set to charge automatically, a failed charge turns automatic payment off for that invoice, and Square notifies you. For how that compares with Stripe, see why Stripe and Square’s retries fall short.
Square can also warn you before a saved card fails. For some Mastercard cards, the bank tells Square when the account behind the card is closed, and Square sets issuer_alert to ISSUER_ALERT_CARD_CLOSED on the card. It's in beta and isn't guaranteed to be accurate, but in Square's testing 80% of cards with an alert were declined at payment. More in Square's guide to managing card-on-file declines.
Square decline codes
Square returns these as error codes. Each error has a category and a code, and may have a detail message meant for developers, so don't show it to customers. Card problems usually come back under the PAYMENT_METHOD_ERROR category. This list covers the errors you can see on card and bank payments, grouped by what to do about them. Square's error code reference has the rest. If you also use Stripe, see Stripe decline codes.
A temporary issue
RetryTEMPORARY_ERROR- A temporary internal error
Solution: Try again. Square says it's safe to retry with the same idempotency key, which stops the same payment going through twice. If it keeps failing, contact Square support.
Not enough funds
Retry laterINSUFFICIENT_FUNDS- Not enough funds to cover the payment
Solution: Retry after a few days, which Square says might work for INSUFFICIENT_FUNDS. If the retries run out, ask the customer to use another card. Prepaid cards tend to run out of funds, and HSA and FSA cards might, so Square suggests asking customers for a secondary payment method when they save one.
Declined by the bank
Ask the customerGENERIC_DECLINE- Square received a decline without any additional information
CARD_DECLINED- The card was declined
CARD_DECLINED_CALL_ISSUER - The bank declined and asked the cardholder to call it
VOICE_FAILURE- The bank requires voice authorization from the cardholder
Solution: Ask the customer to contact their bank for details, or to use another card. For a card on file, Square says not to retry a GENERIC_DECLINE. If they just entered the card, first check the CVV and billing postal code.
Incorrect card details
Ask the customerCVV_FAILUREVERIFY_CVV_FAILURE- Wrong security code, or it couldn't be verified
ADDRESS_VERIFICATION_ FAILURE VERIFY_AVS_FAILURE- Wrong postal code, or it couldn't be verified
INVALID_POSTAL_CODE- The postal code is formatted incorrectly
PAN_FAILUREINVALID_CARDINVALID_CARD_DATA- Invalid card number or card data, or the card can't be validated
INVALID_EXPIRATIONINVALID_EXPIRATION_ YEAR INVALID_EXPIRATION_ DATE BAD_EXPIRATIONEXPIRATION_FAILURE- The expiration date is missing, invalid, or in the past
Solution: Ask the customer to re-enter their card details. On a subscription or invoice, the payment link Square emails them lets them enter a card again.
Needs verification
Ask the customerCARD_DECLINED_VERIFICATION_ REQUIRED - The bank declined and asked for additional verification
Solution: Ask the customer to complete the bank's verification or use another card. Strong customer authentication (SCA) is required in some regions and for sellers who use Square Risk Manager to enforce 3-D Secure, and it applies both when a card is saved on file and when a saved card is charged. If you build your own checkout, pass as much buyer information as you can to Square's Web Payments SDK or In-App Payments SDK, which helps reduce card-on-file declines.
Not allowed on the card
Ask the customerCARD_NOT_SUPPORTED- The card isn't supported in this region, or for your merchant category code (your type of business)
UNSUPPORTED_CARD_BRAND - The card isn't from a supported issuer
CARDHOLDER_INSUFFICIENT_ PERMISSIONS - The bank says the card can't be used here, for example a gift card limited to one merchant
CURRENCY_MISMATCH- The currency isn't valid for the payment method, for example a USD gift card used for a GBP payment
TRANSACTION_LIMIT- The bank says the amount is too high or too low. It's mostly returned for credit cards, for example one at its credit limit, but banks sometimes return it for debit or prepaid cards too
AMOUNT_TOO_HIGHAMOUNT_TOO_LOW- The amount is too high or too low for the payment method
Solution: Ask the customer to check with their bank or use another card.
The card can't be used anymore
New card neededCARD_EXPIRED- The card has expired
INVALID_ACCOUNT- The bank couldn't find the account on record
Solution: Ask for a new card. When the bank allows it, Square automatically updates the expiration date and last four digits of expiring cards on file, and sends a card.automatically_updated event to apps that subscribe to it.
Square's error list has no separate codes for lost, stolen, or fraud-blocked cards. A decline without any details from the bank comes back as GENERIC_DECLINE.
Bank transfer (ACH) payments
Ask the customerACCOUNT_UNUSABLE- The account can't carry out transactions
BUYER_REFUSED_PAYMENT - The bank account rejected the payment, or wasn't authorized for it
Solution: Ask the customer to approve the payment again or use another way to pay. INSUFFICIENT_FUNDS, INVALID_ACCOUNT, and GENERIC_DECLINE can come back for bank transfers too.
A problem with your Square account
Check your accountCARD_PROCESSING_NOT_ENABLED - The location isn't enabled for card processing
INVALID_LOCATION- The account can't take payments in the specified region. A Square account can only take payments from the region where it was created
INSUFFICIENT_PERMISSIONS - The account doesn't have permission to accept this payment. For example, Square may limit which merchants can take gift card payments
PAYMENT_LIMIT_EXCEEDED - The payment is over Square's processing limit for your account
PAYMENT_SOURCE_NOT_ENABLED_ FOR_TARGET - The merchant or location isn't enabled to accept that payment method
Solution: These aren't about the customer's card, so retrying won't help. Check your Square account settings, or contact Square support.
Used or expired payment tokens
Fix in your integrationCARD_TOKEN_EXPIRED- The card token (nonce) has expired
CARD_TOKEN_USED- The card token was already used for a payment or refund
SOURCE_USED- The source ID was already used to create a card
SOURCE_EXPIRED- The source ID has expired
Solution: Payment tokens are one-time use and expire. Collect the card again to get a new one.
In-person and other codes
READER_DECLINED- The Square Card Reader declined the payment for an unknown reason
CHIP_INSERTION_REQUIRED - The bank requires the card to be read with a chip reader
MANUALLY_ENTERED_PAYMENT_NOT_ SUPPORTED - The card must be swiped, tapped, or dipped. Typing in the number is declined
UNSUPPORTED_ENTRY_METHOD - The way the card was read (swipe, dip, or tap) isn't supported
CARD_PRESENCE_REQUIRED - The transaction requires the card to be present
INVALID_PINMISSING_PIN- The PIN is wrong, or a required PIN is missing
ALLOWABLE_PIN_TRIES_EXCEEDED - The card used up its PIN attempts. The customer typically has to contact their bank
APPLE_TTP_PIN_TOKEN- Comes with
CARD_DECLINED_VERIFICATION_REQUIREDon an Apple Tap to Pay payment when the bank asks for a PIN GIFT_CARD_AVAILABLE_AMOUNT- Comes with
INSUFFICIENT_FUNDSon a Square gift card payment and shows the card's remaining balance
Testing decline codes
To check how your integration handles declines, use these values in the Square Sandbox. Use any future expiration date other than 01/40 and the CVV Square lists for the card brand, which is 111 for most. Enter one of these in a payment form built with the Web Payments SDK or In-App Payments SDK to cause a failed payment:
Card numbers and field values
In the payment form4000 0000 0000 0002- The card is declined
4000 0000 0000 0010- The card on file authorization is declined
4811 1100 0000 0008- Fails buyer verification (SCA) with no challenge shown, in the Web Payments SDK
4811 1100 0000 0016- The same failure in the In-App Payments SDK
CVV 911- The security code is rejected
Postal code 99999- The postal code is rejected
Expiration 01/40- The expiration date is rejected
Payment tokens
As a source_idTo skip the payment form, pass one of these as the source_id in a CreatePayment request:
cnon:card-nonce-declined - The card is declined
cnon:card-nonce-rejected-cvv - The security code is rejected
cnon:card-nonce-rejected-postalcode - The postal code is rejected
cnon:card-nonce-rejected-expiration - The expiration date is rejected
cnon:card-nonce-already-used - The payment token was already used
Saved cards (card on file)
As a source_idTo test a failed card-on-file payment, use these card-on-file IDs as the source_id:
ccof:customer-card-id-declined - The card is declined
ccof:customer-card-id-rejected-postalcode - The postal code is rejected
ccof:customer-card-id-rejected-expiration - The expiration date is rejected
Bank transfers (ACH)
As a source_idBank transfer test tokens return a specific error code. In the Sandbox, a failed bank transfer starts as PENDING and changes to FAILED after a minute:
bnon:bank-nonce-failure GENERIC_DECLINEbnon:bank-nonce-insufficient-funds INSUFFICIENT_FUNDSbnon:bank-nonce-account-unusable ACCOUNT_UNUSABLEbnon:bank-nonce-invalid-account INVALID_ACCOUNTbnon:bank-nonce-buyer-refused-payment BUYER_REFUSED_PAYMENT
Square's test values list the rest, including gift cards.
FAQ
Why was a card declined in Square?
Either the customer's bank refused the payment, or Square declined it itself, for example when it goes over your account's processing limit. For a payment made through the Payments API, the reason is the error code on the payment. Sometimes that's just GENERIC_DECLINE: Square received a decline without any additional information.
Can I see why a Square payment was declined?
Sometimes. A failed payment made through the Payments API returns an error code like INSUFFICIENT_FUNDS or CVV_FAILURE. But Square says it doesn't receive complete information from card providers about why payments fail, and when an automatic invoice payment fails, the reason isn't included in the webhook or on the payment. In those cases, Square says the customer should contact their card provider for more information, and you might need to contact the customer yourself.
What does Square do when a card on file is declined?
For a subscription, Square emails the customer an invoice with a link to pay. For an invoice set to charge automatically, Square notifies you, emails the customer a link to pay, and turns automatic payment off for that invoice. It also sends an invoice.scheduled_charge_failed webhook event. For how this compares with Stripe, see why Stripe and Square's retries fall short.
How many times should I retry a declined Square payment?
For a card on file, Square says to wait at least 24 hours before retrying and to limit retries to 2 or 3 attempts over several days. Immediate retries can trigger fraud alerts or more declines, and excessive retries can be flagged as suspicious activity. It adds that retrying INSUFFICIENT_FUNDS after a few days might work, that GENERIC_DECLINE shouldn't be retried, and that a charge that keeps failing means asking for a new payment method.
Can Square tell me a saved card is about to fail?
In some cases. When the bank allows it, Square automatically updates the expiration date and last four digits of expiring cards on file and sends a card.automatically_updated event to apps that subscribe to it. For some Mastercard cards, Square can also flag a closed account with ISSUER_ALERT_CARD_CLOSED, which needs API version 2024-12-18 or later and is in beta. It isn't guaranteed to be accurate, but in Square's testing 80% of cards with an alert were declined at payment.