| Payment Status |
| APPROVED | Payment Approved The payment is authorized (auth-only/delayed capture). The card is valid and funds are guaranteed by the issuing bank. The seller does not yet receive funds. Must be explicitly completed via CompletePayment or canceled via CancelPayment before the delay window expires. | Pending | Common | T0 |
| PENDING | Payment Pending The payment is in a transitional state and is being processed. Used primarily for non-card payment methods such as bank transfers. Not yet a terminal state. | Pending | Occasional | T0 |
| COMPLETED | Payment Completed The payment is captured and funds are credited to the seller's Square account. This is a terminal success state. For autocomplete=true, the payment moves directly here after creation. | Success | Common | T0 |
| CANCELED | Payment Canceled The payment has been voided and any authorized card funds are released back to the cardholder. This is a terminal state. Can result from an explicit CancelPayment call or automatic cancellation after the delay_duration expires. | Info | Common | T0 |
| FAILED | Payment Failed The payment request was declined or could not be processed. The seller receives no funds. This is a terminal state. Inspect the errors array for the specific reason. | Error | Common | T2 |
| AUTHORIZED | Card Authorized The card-level status on CardPaymentDetails indicating the card has been authorized by the issuing bank but funds have not yet been captured. Corresponds to Payment.status = APPROVED. | Pending | Common | T0 |
| CAPTURED | Card Captured The card-level status on CardPaymentDetails indicating the funds have been successfully captured from the cardholder's bank. Corresponds to Payment.status = COMPLETED. | Success | Common | T0 |
| VOIDED | Card Voided The card-level status on CardPaymentDetails indicating the authorization was voided and no funds were captured. Corresponds to Payment.status = CANCELED. | Info | Common | T0 |
| FAILED | Card Failed The card-level status on CardPaymentDetails indicating the card transaction failed at the network or issuer level. Corresponds to Payment.status = FAILED. | Error | Common | T2 |
| Refund Status |
| PENDING | Refund Pending The refund has been created and is being processed. Funds have not yet been returned to the cardholder. Developers should poll or subscribe to webhooks to monitor for resolution. | Pending | Common | T0 |
| APPROVED | Refund Approved The refund has been approved by Square and funds are being returned to the cardholder. A successful terminal state for the refund flow. | Success | Common | T0 |
| REJECTED | Refund Rejected The refund was rejected by Square. The refund will not proceed. Investigate the reason (e.g., refund amount exceeds available balance) and retry or use an alternative refund method. | Error | Occasional | T1 |
| FAILED | Refund Failed The refund failed to process. The cardholder will not receive funds. Check the errors array for the specific reason and contact Square support if needed. | Error | Occasional | T1 |
| Dispute Status |
| INQUIRY_EVIDENCE_REQUIRED | Dispute Inquiry - Evidence Required A chargeback inquiry has been initiated and Square is requesting the seller submit evidence to respond. This is the initial state of an inquiry-type dispute. | Pending | Occasional | T1 |
| INQUIRY_PROCESSING | Dispute Inquiry - Processing Evidence for the inquiry has been submitted and the issuing bank is reviewing it. | Pending | Occasional | T1 |
| INQUIRY_CLOSED | Dispute Inquiry - Closed The inquiry is complete. Check the outcome (WON/LOST/ACCEPTED) separately. | Info | Occasional | T1 |
| EVIDENCE_REQUIRED | Dispute Evidence Required A formal dispute (chargeback) has been filed and Square requires the seller to submit evidence. This is the initial state of a dispute. Sellers must respond within the deadline to contest. | Pending | Occasional | T1 |
| PROCESSING | Dispute Processing The seller has submitted evidence and the issuing bank is processing the dispute. No further action is required from the seller at this time. | Pending | Occasional | T1 |
| WON | Dispute Won The bank completed processing the dispute in the seller's favor. The disputed funds are returned to the seller. This is a terminal success state for dispute resolution. | Success | Occasional | T1 |
| LOST | Dispute Lost The bank completed processing the dispute in the cardholder's favor. The disputed amount is permanently deducted from the seller's account. This is a terminal state. | Error | Occasional | T1 |
| ACCEPTED | Dispute Accepted The seller has explicitly accepted the dispute rather than contesting it. The disputed funds are forfeited. This is a terminal state. | Info | Occasional | T1 |
| Error & Decline Codes |
| INTERNAL_SERVER_ERROR | Internal Server Error A general server error occurred on Square's side. Retry with exponential backoff. | Error | Rare | T0 |
| UNAUTHORIZED | Unauthorized A general authorization error occurred. Check that the Authorization header includes a valid bearer token. | Error | Occasional | T1 |
| ACCESS_TOKEN_EXPIRED | Access Token Expired The provided OAuth access token has expired. Refresh the token and retry. | Error | Occasional | T1 |
| ACCESS_TOKEN_REVOKED | Access Token Revoked The provided access token has been revoked. The merchant must re-authorize the application. | Error | Rare | T1 |
| CLIENT_DISABLED | Client Disabled The OAuth client/application has been disabled by Square. Contact Square support. | Error | Rare | T1 |
| FORBIDDEN | Forbidden A general access error occurred. The token may lack required permissions for this resource. | Error | Occasional | T1 |
| INSUFFICIENT_SCOPES | Insufficient Scopes The access token does not have the OAuth scopes required to execute the requested action. | Error | Occasional | T1 |
| APPLICATION_DISABLED | Application Disabled The calling application has been disabled. Contact Square support. | Error | Rare | T1 |
| V1_APPLICATION | Legacy V1 Application The application was created before 2016-03-30 and is incompatible with v2 Square API calls. | Error | Rare | T1 |
| V1_ACCESS_TOKEN | Legacy V1 Access Token The access token was created before 2016-03-30 and is incompatible with v2 Square API calls. | Error | Rare | T1 |
| CARD_PROCESSING_NOT_ENABLED | Card Processing Not Enabled The location specified in the API call is not enabled for credit card processing. Enable card processing in the Square Dashboard. | Error | Rare | T1 |
| MERCHANT_SUBSCRIPTION_NOT_FOUND | Merchant Subscription Not Found A required subscription was not found for the merchant. The merchant may need to upgrade their Square plan. | Error | Rare | T1 |
| BAD_REQUEST | Bad Request A general error occurred with the request format or parameters. Review request structure. | Error | Occasional | T0 |
| MISSING_REQUIRED_PARAMETER | Missing Required Parameter The request is missing a required path, query, or body parameter. Check the API reference for required fields. | Error | Common | T0 |
| INCORRECT_TYPE | Incorrect Type A parameter value is the wrong data type, such as a string where an integer is expected. | Error | Occasional | T0 |
| INVALID_TIME | Invalid Time The time value provided is incorrectly formatted. Use RFC 3339 format. | Error | Occasional | T0 |
| INVALID_TIME_RANGE | Invalid Time Range The time range in the request is invalid, e.g. end time is before start time. | Error | Occasional | T0 |
| INVALID_VALUE | Invalid Value A provided value is invalid, e.g. including special characters like % in a phone number. | Error | Common | T0 |
| INVALID_CURSOR | Invalid Cursor The pagination cursor included in the request is invalid or expired. Restart pagination. | Error | Occasional | T0 |
| UNKNOWN_QUERY_PARAMETER | Unknown Query Parameter A query parameter was provided that is not supported by the requested endpoint. | Error | Occasional | T0 |
| CONFLICTING_PARAMETERS | Conflicting Parameters One or more request parameters conflict with each other and cannot be used together. | Error | Occasional | T0 |
| EXPECTED_JSON_BODY | Expected JSON Body The request body is not a valid JSON object. Check Content-Type header and body formatting. | Error | Occasional | T0 |
| INVALID_SORT_ORDER | Invalid Sort Order The provided sort order is not valid. Must be ASC or DESC. | Error | Rare | T0 |
| VALUE_REGEX_MISMATCH | Value Regex Mismatch The provided value does not match the expected regular expression pattern for that field. | Error | Occasional | T0 |
| VALUE_TOO_SHORT | Value Too Short The provided string value is shorter than the minimum allowed length. | Error | Occasional | T0 |
| VALUE_TOO_LONG | Value Too Long The provided string value exceeds the maximum allowed length. | Error | Occasional | T0 |
| VALUE_TOO_LOW | Value Too Low The numeric value is below the supported minimum. | Error | Occasional | T0 |
| VALUE_TOO_HIGH | Value Too High The numeric value exceeds the supported maximum. | Error | Occasional | T0 |
| VALUE_EMPTY | Value Empty A required field has an empty or default value such as a blank string. | Error | Common | T0 |
| ARRAY_LENGTH_TOO_LONG | Array Too Long The provided array contains more elements than the maximum allowed. | Error | Occasional | T0 |
| ARRAY_LENGTH_TOO_SHORT | Array Too Short The provided array contains fewer elements than the minimum required. | Error | Occasional | T0 |
| ARRAY_EMPTY | Array Empty The provided array is empty but must contain at least one element. | Error | Occasional | T0 |
| EXPECTED_BOOLEAN | Expected Boolean The endpoint expected a boolean value for this field. | Error | Occasional | T0 |
| EXPECTED_INTEGER | Expected Integer The endpoint expected an integer value for this field. | Error | Occasional | T0 |
| EXPECTED_FLOAT | Expected Float The endpoint expected a float value for this field. | Error | Occasional | T0 |
| EXPECTED_STRING | Expected String The endpoint expected a string value for this field. | Error | Occasional | T0 |
| EXPECTED_OBJECT | Expected Object The endpoint expected a JSON object for this field. | Error | Occasional | T0 |
| EXPECTED_ARRAY | Expected Array The endpoint expected an array or list for this field. | Error | Occasional | T0 |
| EXPECTED_MAP | Expected Map The endpoint expected a map or associative array for this field. | Error | Occasional | T0 |
| EXPECTED_BASE64_ENCODED_BYTE_ARRAY | Expected Base64 Byte Array The endpoint expected a base64-encoded byte array for this field. | Error | Rare | T0 |
| INVALID_ARRAY_VALUE | Invalid Array Value One or more objects in the array does not match the expected array element type. | Error | Occasional | T0 |
| INVALID_ENUM_VALUE | Invalid Enum Value The provided static string is not a valid value for this enumerated field. | Error | Occasional | T0 |
| INVALID_CONTENT_TYPE | Invalid Content Type The Content-Type header is invalid for this request. Use application/json. | Error | Occasional | T0 |
| INVALID_FORM_VALUE | Invalid Form Value Only relevant for applications created before 2016-03-30. Indicates a form value parsing error. | Error | Rare | T0 |
| CUSTOMER_NOT_FOUND | Customer Not Found The provided customer ID does not exist in the merchant's customer directory. | Error | Occasional | T0 |
| ONE_INSTRUMENT_EXPECTED | One Instrument Expected Only one payment instrument was expected but multiple were provided. | Error | Rare | T0 |
| NO_FIELDS_SET | No Fields Set The request contains no fields to update or process. | Error | Rare | T0 |
| TOO_MANY_MAP_ENTRIES | Too Many Map Entries The map field contains more key-value entries than allowed. | Error | Rare | T0 |
| MAP_KEY_LENGTH_TOO_SHORT | Map Key Too Short One of the keys in the map field is shorter than the minimum required length. | Error | Rare | T0 |
| MAP_KEY_LENGTH_TOO_LONG | Map Key Too Long One of the keys in the map field exceeds the maximum allowed length. | Error | Rare | T0 |
| CUSTOMER_MISSING_NAME | Customer Missing Name The customer record does not have a name, which is required for this operation. | Error | Occasional | T0 |
| CUSTOMER_MISSING_EMAIL | Customer Missing Email The customer record does not have an email address, which is required for this operation. | Error | Occasional | T0 |
| INVALID_PAUSE_LENGTH | Invalid Pause Length The subscription cannot be paused for longer than the duration of the current billing phase. | Error | Rare | T0 |
| INVALID_DATE | Invalid Date The subscription cannot be paused or resumed on the specified date. | Error | Rare | T0 |
| UNSUPPORTED_COUNTRY | Unsupported Country The API request references a country that is not supported by Square. | Error | Rare | T3 |
| UNSUPPORTED_CURRENCY | Unsupported Currency The API request references a currency that is not supported for this operation or location. | Error | Rare | T3 |
| APPLE_TTP_PIN_TOKEN | Apple TTP PIN Token Required The payment was declined during Apple Tap to Pay and the card issuer requires PIN entry. Returned alongside CARD_DECLINED_VERIFICATION_REQUIRED; the details field contains an issuer token needed to initiate PIN collection on the iOS device. | Decline, Soft decline | Rare | T0 |
| CARD_EXPIRED | Card Expired The card issuer declined the request because the card is expired. Ask the customer to use a different card. | Decline, Hard decline | Common | T3 |
| INVALID_EXPIRATION | Invalid Expiration The expiration date for the payment card is invalid, such as indicating a date in the past. | Error, Decline | Occasional | T0 |
| INVALID_EXPIRATION_YEAR | Invalid Expiration Year The expiration year is invalid, either in the past or containing non-numeric characters. | Error | Occasional | T0 |
| INVALID_EXPIRATION_DATE | Invalid Expiration Date The expiration date format is invalid or contains non-numeric characters. | Error | Occasional | T0 |
| UNSUPPORTED_CARD_BRAND | Unsupported Card Brand The card brand (e.g. Diners Club) is not accepted by this merchant or location. | Error, Hard decline | Occasional | T3 |
| UNSUPPORTED_ENTRY_METHOD | Unsupported Entry Method The card entry method used (swipe, dip, tap) is not supported for this transaction type. | Error | Rare | T0 |
| INVALID_ENCRYPTED_CARD | Invalid Encrypted Card The encrypted card data is invalid or corrupted. Re-tokenize the card and retry. | Error | Rare | T0 |
| INVALID_CARD | Invalid Card The credit card cannot be validated based on the provided details. Check card number, expiry, and CVV. | Error, Decline | Occasional | T0 |
| PAYMENT_AMOUNT_MISMATCH | Payment Amount Mismatch The payment amount Square expected does not match the amount provided in the request. | Error | Rare | T0 |
| GENERIC_DECLINE | Generic Decline The card was declined without additional issuer information. The customer should contact their bank for details. | Decline, Soft decline | Common | T2 |
| CVV_FAILURE | CVV Failure The card issuer declined because the CVV (security code) value is invalid or does not match. | Decline, Hard decline | Common | T0 |
| ADDRESS_VERIFICATION_FAILURE | Address Verification Failure The card issuer declined because the postal/ZIP code did not match the billing address on file. | Decline, Soft decline | Common | T0 |
| INVALID_ACCOUNT | Invalid Account The issuer was unable to locate the account on record. The card number may be incorrect. | Decline, Hard decline | Occasional | T0 |
| CURRENCY_MISMATCH | Currency Mismatch The currency associated with the payment does not match what the funding source supports, e.g. a USD gift card used for a GBP transaction. | Error, Decline | Rare | T0 |
| INSUFFICIENT_FUNDS | Insufficient Funds The funding source does not have enough balance to cover the payment amount. Customer should use another card or add funds. | Decline, Soft decline | Common | T3 |
| INSUFFICIENT_PERMISSIONS | Insufficient Permissions The Square account lacks the permissions to accept this type of payment, e.g. gift card payments may be restricted. | Error | Rare | T1 |
| CARDHOLDER_INSUFFICIENT_PERMISSIONS | Cardholder Insufficient Permissions The card issuer declined because of restrictions on where the card can be used, such as a gift card limited to a single merchant. | Decline, Hard decline | Occasional | T3 |
| INVALID_LOCATION | Invalid Location The Square account cannot process payments in the specified region. Accounts are region-locked to where they were created. | Error | Rare | T3 |
| TRANSACTION_LIMIT | Transaction Limit The payment amount is too high or too low per issuer limits. Common for credit cards hitting their credit limit or debit/prepaid cards with insufficient funds. | Decline, Soft decline | Common | T2 |
| VOICE_FAILURE | Voice Authorization Required The issuer requires verbal authorization from the cardholder before approving. The merchant should ask the customer to call their bank. | Decline, Soft decline | Rare | T2 |
| PAN_FAILURE | PAN Failure The card number (PAN) is invalid due to incorrect length or formatting. | Decline, Hard decline | Occasional | T0 |
| EXPIRATION_FAILURE | Expiration Failure The card expiration date is either invalid or the card is expired. | Decline, Hard decline | Common | T3 |
| CARD_NOT_SUPPORTED | Card Not Supported The card is not supported in the merchant's geographic region or for the merchant category code (MCC). | Decline, Hard decline | Occasional | T3 |
| READER_DECLINED | Reader Declined The Square Card Reader declined the payment for an unknown reason. Retry or use a different payment method. | Decline, Error | Rare | T0 |
| INVALID_PIN | Invalid PIN The card issuer declined because the PIN entered is incorrect. | Decline, Soft decline | Occasional | T0 |
| MISSING_PIN | Missing PIN The payment requires a PIN but none was provided. | Error | Occasional | T0 |
| MISSING_ACCOUNT_TYPE | Missing Account Type The payment requires an ACCOUNT_TYPE parameter (e.g. checking vs savings) but it was not provided. | Error | Rare | T0 |
| INVALID_POSTAL_CODE | Invalid Postal Code The postal/ZIP code provided is incorrectly formatted. | Error | Occasional | T0 |
| INVALID_FEES | Invalid Fees The app_fee_money specified in the payment request is too high relative to the payment amount. | Error | Occasional | T0 |
| MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED | Manual Entry Not Supported The card must be physically swiped, tapped, or dipped. Manually keyed-in card numbers are not permitted for this transaction. | Error, Hard decline | Rare | T3 |
| PAYMENT_LIMIT_EXCEEDED | Payment Limit Exceeded Square declined the payment because it exceeded the processing limit configured for this merchant. | Decline, Hard decline | Occasional | T1 |
| GIFT_CARD_AVAILABLE_AMOUNT | Gift Card Available Amount Returned alongside INSUFFICIENT_FUNDS for gift card payments; the details field contains the remaining gift card balance. Use accept_partial_authorization to collect the remainder with another payment method. | Info, Soft decline | Occasional | T0 |
| ACCOUNT_UNUSABLE | Account Unusable The account associated with the payment cannot carry out transactions. Customer should contact their bank. | Decline, Hard decline | Rare | T2 |
| BUYER_REFUSED_PAYMENT | Buyer Refused Payment The bank account was rejected or not authorized for the payment. Common in ACH/bank transfer flows. | Decline, Hard decline | Occasional | T3 |
| DELAYED_TRANSACTION_EXPIRED | Delayed Transaction Expired An attempt was made to update (complete or cancel) a delayed-capture payment that has already expired past its capture window. | Error | Occasional | T0 |
| DELAYED_TRANSACTION_CANCELED | Delayed Transaction Already Canceled An attempt was made to cancel a delayed-capture payment that was already canceled. | Error | Rare | T0 |
| DELAYED_TRANSACTION_CAPTURED | Delayed Transaction Already Captured An attempt was made to capture a delayed-capture payment that was already captured. | Error | Rare | T0 |
| DELAYED_TRANSACTION_FAILED | Delayed Transaction Failed An attempt was made to update a delayed-capture payment that had already failed. | Error | Rare | T0 |
| CARD_TOKEN_EXPIRED | Card Token Expired The card nonce (single-use token) has expired. Re-tokenize the card using the Web Payments SDK and retry. | Error | Occasional | T0 |
| CARD_TOKEN_USED | Card Token Already Used The card nonce was already used to process a payment or refund. Nonces are single-use; generate a new one. | Error | Occasional | T0 |
| AMOUNT_TOO_HIGH | Amount Too High The requested payment amount exceeds the maximum allowed for the provided payment source. | Decline, Hard decline | Occasional | T2 |
| UNSUPPORTED_INSTRUMENT_TYPE | Unsupported Instrument Type The payment instrument type referenced in the request is not supported for this operation. | Error | Rare | T3 |
| REFUND_AMOUNT_INVALID | Refund Amount Invalid The requested refund amount exceeds the amount available to refund on this payment. | Error | Occasional | T0 |
| REFUND_ALREADY_PENDING | Refund Already Pending The payment already has a pending refund in progress. Wait for it to resolve before issuing another. | Error | Occasional | T0 |
| PAYMENT_NOT_REFUNDABLE | Payment Not Refundable The payment cannot be refunded, e.g. it is too old or in a terminal state that does not allow refunds. | Error | Occasional | T1 |
| PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE | Payment Not Refundable - Disputed The payment cannot be refunded because it is currently under a dispute/chargeback. Handle through the Disputes API. | Error | Occasional | T1 |
| REFUND_ERROR_PAYMENT_NEEDS_COMPLETION | Payment Needs Completion Before Refund The payment is in an APPROVED state and must be completed (captured) before a refund can be issued. | Error | Rare | T0 |
| REFUND_DECLINED | Refund Declined The card issuer declined the refund request. Contact the issuer or try an alternative refund method. | Decline, Error | Occasional | T1 |
| INSUFFICIENT_PERMISSIONS_FOR_REFUND | Insufficient Permissions for Refund The Square account does not have the permissions required to process this refund. | Error | Rare | T1 |
| INVALID_CARD_DATA | Invalid Card Data The card data provided is generically invalid. Re-collect and re-tokenize card details. | Error | Occasional | T0 |
| SOURCE_USED | Source Already Used The provided source ID was already used to create a card on file. Source IDs are single-use. | Error | Occasional | T0 |
| SOURCE_EXPIRED | Source Expired The provided source ID has expired. Generate a new source token. | Error | Occasional | T0 |
| UNSUPPORTED_LOYALTY_REWARD_TIER | Unsupported Loyalty Reward Tier The referenced loyalty reward tier is incompatible with the Loyalty API, likely created via a first-party Square app. | Error | Rare | T1 |
| LOCATION_MISMATCH | Location Mismatch The location provided does not match what is expected for this resource or operation. | Error | Rare | T0 |
| ORDER_UNPAID_NOT_RETURNABLE | Order Unpaid - Not Returnable The order cannot be returned because it has not yet been paid. | Error | Rare | T0 |
| PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED | Partial Payment Delay Capture Not Supported Delay capture (auth-only) is not supported for partial payments. | Error | Rare | T1 |
| IDEMPOTENCY_KEY_REUSED | Idempotency Key Reused The provided idempotency key was already used for a different request. Use a unique key per logical operation. | Error | Occasional | T0 |
| UNEXPECTED_VALUE | Unexpected Value A value provided in the request was not expected for this field or context. | Error | Occasional | T0 |
| SANDBOX_NOT_SUPPORTED | Sandbox Not Supported The requested API action is not supported in the Square Sandbox environment. | Error | Occasional | T1 |
| INVALID_EMAIL_ADDRESS | Invalid Email Address The provided email address is not in a valid format. | Error | Occasional | T0 |
| INVALID_PHONE_NUMBER | Invalid Phone Number The provided phone number is not in a valid format. | Error | Occasional | T0 |
| CHECKOUT_EXPIRED | Checkout Expired The checkout URL or session has expired. Create a new checkout to proceed. | Error | Occasional | T0 |
| BAD_CERTIFICATE | Bad Certificate The SSL/TLS certificate provided is invalid or untrusted. | Error | Rare | T1 |
| INVALID_SQUARE_VERSION_FORMAT | Invalid Square-Version Format The Square-Version header value is incorrectly formatted. Use YYYY-MM-DD format. | Error | Rare | T0 |
| API_VERSION_INCOMPATIBLE | API Version Incompatible The Square-Version specified is incompatible with the requested action or resource. | Error | Rare | T1 |
| CARD_PRESENCE_REQUIRED | Card Presence Required The transaction type requires that a physical card be present (card-present transaction). | Error | Rare | T3 |
| UNSUPPORTED_SOURCE_TYPE | Unsupported Source Type The source type referenced in the API request is not supported for this operation. | Error | Rare | T3 |
| CARD_MISMATCH | Card Mismatch The card provided does not match what was expected for this payment or customer record. | Error, Decline | Rare | T0 |
| PLAID_ERROR | Plaid Generic Error A generic error occurred with the Plaid bank account linking integration. Retry or reconnect the bank account. | Error | Rare | T0 |
| PLAID_ERROR_ITEM_LOGIN_REQUIRED | Plaid Item Login Required The linked bank account requires the customer to re-authenticate with their bank via Plaid. | Error, Soft decline | Occasional | T2 |
| PLAID_ERROR_RATE_LIMIT | Plaid Rate Limit Square has hit the Plaid API rate limit. Retry after a short delay. | Error | Rare | T0 |
| PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET | Payment Source Not Enabled The merchant or location is not enabled to accept the requested payment source type. | Error | Rare | T1 |
| CARD_DECLINED | Card Declined The card was declined by the issuer. The customer should try another card or contact their bank. | Decline, Hard decline | Common | T2 |
| VERIFY_CVV_FAILURE | CVV Verification Failed The CVV verification check could not be completed or failed. Re-collect the security code. | Decline, Soft decline | Common | T0 |
| VERIFY_AVS_FAILURE | AVS Verification Failed The Address Verification Service (AVS) check could not be completed or failed. Verify billing address. | Decline, Soft decline | Common | T0 |
| CARD_DECLINED_CALL_ISSUER | Card Declined - Call Issuer The card was declined and the issuer is requesting the cardholder call their bank before retrying. | Decline, Hard decline | Occasional | T2 |
| CARD_DECLINED_VERIFICATION_REQUIRED | Card Declined - Verification Required The card was declined and the issuer requires additional cardholder verification (e.g. 3DS or PIN). | Decline, Soft decline | Occasional | T0 |
| BAD_EXPIRATION | Bad Expiration The card expiration date is missing or incorrectly formatted in the payment request. | Error, Decline | Occasional | T0 |
| CHIP_INSERTION_REQUIRED | Chip Insertion Required The card issuer requires the chip to be physically inserted (dipped) rather than swiped or tapped. | Decline, Soft decline | Occasional | T0 |
| ALLOWABLE_PIN_TRIES_EXCEEDED | PIN Tries Exceeded The card has exhausted its maximum PIN entry attempts set by the issuer. The cardholder must contact their bank to reset. | Decline, Hard decline | Rare | T2 |
| RESERVATION_DECLINED | Reservation Declined The card issuer declined the refund reservation. | Decline, Error | Rare | T1 |
| UNKNOWN_BODY_PARAMETER | Unknown Body Parameter A body parameter was provided that is not recognized by the requested endpoint. | Error | Occasional | T0 |
| NOT_FOUND | Not Found The requested resource does not exist. Verify the ID or path used in the request. | Error | Common | T0 |
| APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND | Apple Pay Certificate Not Found Square could not locate the Apple Pay processing certificate associated with this merchant. Re-register the domain. | Error | Rare | T1 |
| METHOD_NOT_ALLOWED | Method Not Allowed The HTTP method used is not supported for this endpoint. | Error | Occasional | T0 |
| NOT_ACCEPTABLE | Not Acceptable The server cannot produce a response matching the Accept header criteria. | Error | Rare | T0 |
| REQUEST_TIMEOUT | Request Timeout The request took too long to process. Retry with exponential backoff. | Error | Occasional | T0 |
| CONFLICT | Conflict The request conflicts with the current state of the resource. Check for concurrent modifications. | Error | Occasional | T0 |
| GONE | Gone The target resource is no longer available and this condition is permanent. | Error | Rare | T3 |
| REQUEST_ENTITY_TOO_LARGE | Request Entity Too Large The request body exceeds the maximum allowed size. | Error | Rare | T0 |
| UNSUPPORTED_MEDIA_TYPE | Unsupported Media Type The Content-Type of the request body is not supported. Use application/json. | Error | Occasional | T0 |
| UNPROCESSABLE_ENTITY | Unprocessable Entity The request was well-formed but contains semantic errors that prevent processing. | Error | Occasional | T0 |
| RATE_LIMITED | Rate Limited The application has exceeded the Square API rate limit. Implement exponential backoff with jitter before retrying. | Error | Occasional | T0 |
| NOT_IMPLEMENTED | Not Implemented The requested functionality is not implemented by this API endpoint. | Error | Rare | T1 |
| BAD_GATEWAY | Bad Gateway Square received an invalid response from an upstream service. Retry after a short delay. | Error | Rare | T0 |
| SERVICE_UNAVAILABLE | Service Unavailable Square's service is temporarily unavailable. Check status.squareup.com and retry with backoff. | Error | Rare | T0 |
| TEMPORARY_ERROR | Temporary Error A temporary internal error occurred. Safe to retry using the same idempotency key. | Error | Occasional | T0 |
| GATEWAY_TIMEOUT | Gateway Timeout An upstream service timed out. Retry with exponential backoff. | Error | Rare | T0 |
USA
