Tip from SmartRetry If you’re seeing card declines, compare decline patterns by channel (in-person vs online) and make sure AVS/CVV and billing details are consistently collected for online checkouts.
Square
Methods
- Cards
- Digital Wallets
- Cryptocurrencies
- Direct Debit
- Buy Now Pay Later
Square is a payment provider that helps merchants accept card and digital wallet payments in-store and online with built-in business tools.
Struggling with your approval ratio for this payment provider?
contact SmartRetry team →- Published
- Last updated
2 min
Proceed payment with
About Square
Product Type
Payment Processor
Foundation
2009
Stock ID
NYSE:XYZ
Company Type
public
Employees
12,980+
Location
USAChannel
In person Online
For developers
Features
In-person and online acceptance
Accept major cards and supported digital wallets across Square POS and online checkout options. Suitable for retail, food & beverage, and service businesses.
Authorization and routing (high-level)
Provides merchant payment processing with authorization handling for card-present and card-not-present transactions. Behavior can vary by payment method and region.
Approval rates and card declines visibility
Merchant dashboards and receipts help you review outcomes and identify common decline reasons (e.g., issuer declines, expired cards). Use trends to refine checkout and data capture.
Security and compliance support
Helps merchants with secure payment acceptance and data handling features aligned to industry requirements. Product capabilities vary by channel and configuration.
Authentication options for ecommerce
Supports card network authentication capabilities where applicable for online payments. Useful for reducing certain fraud-driven declines and meeting issuer expectations.
Disputes and chargeback management
Provides tools to respond to disputes, submit evidence, and track outcomes. Centralizes dispute status alongside related orders and refunds.
Reliability and operational tooling
Offers consolidated reporting, refunds, and payment history to support day-to-day operations. Helps teams monitor issues across devices, locations, and channels.
Currencies
Processing currencies USD, AUD, CAD, EUR, GBP, JPY
Available in
Available countries
- 🌍Global
FAQ
Square is used by merchants to accept payments in-store and online, manage refunds, and track sales and payouts through a unified platform.
Square is commonly described as a payment service provider/payment provider that offers merchant payment processing and related tools; the underlying acquiring setup can vary by region and product.
Square is available in select regions, and availability can differ by product. Check Square’s website for the current list of supported markets and features.
Start by reviewing decline reasons and separating issuer declines from data-quality issues. For online payments, ensure accurate billing details, collect AVS/CVV where applicable, and reduce checkout friction that leads to entry errors.
Square supports select digital wallets depending on region, device, and integration. Confirm wallet support for your POS hardware or online checkout method.
Statuses
| Code | Description | Level | Frequency | Resolution |
|---|---|---|---|---|
| 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. | Processing | 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. | Approved | Common | T0 |
| 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. | Processing | 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 | T3 |
| 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. | Approved | Common | 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. | Approved | 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 |
| 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 |
| 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. | Processing | Occasional | T0 |
| 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. | Processing | 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 |
| 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 | T3 |
| State | ||||
| 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 | T0 |
| 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. | Processing | Occasional | T1 |
| INQUIRY_CLOSED | Dispute Inquiry - Closed The inquiry is complete. Check the outcome (WON/LOST/ACCEPTED) separately. | Info | Occasional | T0 |
| 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. | Processing | Occasional | T1 |
| INQUIRY_PROCESSING | Dispute Inquiry - Processing Evidence for the inquiry has been submitted and the issuing bank is reviewing it. | Processing | 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 | T3 |
| 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. | Processing | 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. | Approved | Occasional | T0 |
| Error & Decline Codes | ||||
| 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 |
| ACCOUNT_UNUSABLE | Account Unusable The account associated with the payment cannot carry out transactions. Customer should contact their bank. | Declined | Rare | T2 |
| ADDRESS_VERIFICATION_FAILURE | Address Verification Failure The card issuer declined because the postal/ZIP code did not match the billing address on file. | Declined | Common | T0 |
| AMOUNT_TOO_HIGH | Amount Too High The requested payment amount exceeds the maximum allowed for the provided payment source. | Declined | Occasional | T2 |
| API_VERSION_INCOMPATIBLE | API Version Incompatible The Square-Version specified is incompatible with the requested action or resource. | Error | Rare | T1 |
| APPLICATION_DISABLED | Application Disabled The calling application has been disabled. Contact Square support. | Error | Rare | T1 |
| ARRAY_EMPTY | Array Empty The provided array is empty but must contain at least one element. | Error | Occasional | 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 |
| BAD_CERTIFICATE | Bad Certificate The SSL/TLS certificate provided is invalid or untrusted. | Error | Rare | T1 |
| BAD_EXPIRATION | Bad Expiration The card expiration date is missing or incorrectly formatted in the payment request. | Error, Declined | Occasional | T0 |
| BAD_GATEWAY | Bad Gateway Square received an invalid response from an upstream service. Retry after a short delay. | Error | Rare | T0 |
| BAD_REQUEST | Bad Request A general error occurred with the request format or parameters. Review request structure. | Error | Occasional | T0 |
| BUYER_REFUSED_PAYMENT | Buyer Refused Payment The bank account was rejected or not authorized for the payment. Common in ACH/bank transfer flows. | Declined | Occasional | T3 |
| CARD_DECLINED | Card Declined The card was declined by the issuer. The customer should try another card or contact their bank. | Declined | Common | T2 |
| CARD_DECLINED_CALL_ISSUER | Card Declined - Call Issuer The card was declined and the issuer is requesting the cardholder call their bank before retrying. | Declined | 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). | Declined | Occasional | T0 |
| CARD_EXPIRED | Card Expired The card issuer declined the request because the card is expired. Ask the customer to use a different card. | Declined | Common | T3 |
| CARD_MISMATCH | Card Mismatch The card provided does not match what was expected for this payment or customer record. | Error, Declined | Rare | T0 |
| CARD_NOT_SUPPORTED | Card Not Supported The card is not supported in the merchant's geographic region or for the merchant category code (MCC). | Declined | Occasional | T3 |
| 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 |
| 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 |
| 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. | Declined | Occasional | T3 |
| CLIENT_DISABLED | Client Disabled The OAuth client/application has been disabled by Square. Contact Square support. | Error | Rare | T1 |
| CONFLICT | Conflict The request conflicts with the current state of the resource. Check for concurrent modifications. | Error | Occasional | T0 |
| CONFLICTING_PARAMETERS | Conflicting Parameters One or more request parameters conflict with each other and cannot be used together. | Error | 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, Declined | Rare | 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 |
| CUSTOMER_MISSING_NAME | Customer Missing Name The customer record does not have a name, which is required for this operation. | Error | Occasional | T0 |
| CUSTOMER_NOT_FOUND | Customer Not Found The provided customer ID does not exist in the merchant's customer directory. | Error | Occasional | T0 |
| CVV_FAILURE | CVV Failure The card issuer declined because the CVV (security code) value is invalid or does not match. | Declined | Common | T0 |
| DELAYED_TRANSACTION_CANCELED | Delayed Transaction Already Canceled An attempt was made to cancel a delayed-capture payment that was already canceled. | Error | Rare | T3 |
| DELAYED_TRANSACTION_CAPTURED | Delayed Transaction Already Captured An attempt was made to capture a delayed-capture payment that was already captured. | Error | Rare | 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 | T3 |
| DELAYED_TRANSACTION_FAILED | Delayed Transaction Failed An attempt was made to update a delayed-capture payment that had already failed. | Error | Rare | T3 |
| EXPECTED_ARRAY | Expected Array The endpoint expected an array or list 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 |
| EXPECTED_BOOLEAN | Expected Boolean The endpoint expected a boolean value for this field. | Error | Occasional | T0 |
| EXPECTED_FLOAT | Expected Float The endpoint expected a float value for this field. | Error | Occasional | T0 |
| EXPECTED_INTEGER | Expected Integer The endpoint expected an integer value for this field. | 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 |
| EXPECTED_MAP | Expected Map The endpoint expected a map or associative array for this field. | Error | Occasional | T0 |
| EXPECTED_OBJECT | Expected Object The endpoint expected a JSON object for this field. | Error | Occasional | T0 |
| EXPECTED_STRING | Expected String The endpoint expected a string value for this field. | Error | Occasional | T0 |
| EXPIRATION_FAILURE | Expiration Failure The card expiration date is either invalid or the card is expired. | Declined | Common | T3 |
| FORBIDDEN | Forbidden A general access error occurred. The token may lack required permissions for this resource. | Error | Occasional | T1 |
| GATEWAY_TIMEOUT | Gateway Timeout An upstream service timed out. Retry with exponential backoff. | Error | Rare | T0 |
| GENERIC_DECLINE | Generic Decline The card was declined without additional issuer information. The customer should contact their bank for details. | Declined | Common | T2 |
| 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 | Occasional | T0 |
| GONE | Gone The target resource is no longer available and this condition is permanent. | Error | Rare | T3 |
| 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 |
| INCORRECT_TYPE | Incorrect Type A parameter value is the wrong data type, such as a string where an integer is expected. | Error | Occasional | 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. | Declined | 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 |
| INSUFFICIENT_PERMISSIONS_FOR_REFUND | Insufficient Permissions for Refund The Square account does not have the permissions required to process this refund. | Error | Rare | T1 |
| INSUFFICIENT_SCOPES | Insufficient Scopes The access token does not have the OAuth scopes required to execute the requested action. | Error | Occasional | T1 |
| INTERNAL_SERVER_ERROR | Internal Server Error A general server error occurred on Square's side. Retry with exponential backoff. | Error | Rare | T0 |
| INVALID_ACCOUNT | Invalid Account The issuer was unable to locate the account on record. The card number may be incorrect. | Declined | Occasional | 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_CARD | Invalid Card The credit card cannot be validated based on the provided details. Check card number, expiry, and CVV. | Error, Declined | Occasional | T0 |
| INVALID_CARD_DATA | Invalid Card Data The card data provided is generically invalid. Re-collect and re-tokenize card details. | 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_CURSOR | Invalid Cursor The pagination cursor included in the request is invalid or expired. Restart pagination. | Error | Occasional | T0 |
| INVALID_EMAIL_ADDRESS | Invalid Email Address The provided email address is not in a valid format. | Error | Occasional | 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_ENUM_VALUE | Invalid Enum Value The provided static string is not a valid value for this enumerated field. | Error | Occasional | T0 |
| INVALID_EXPIRATION | Invalid Expiration The expiration date for the payment card is invalid, such as indicating a date in the past. | Error, Declined | Occasional | T0 |
| INVALID_EXPIRATION_DATE | Invalid Expiration Date The expiration date format is invalid or contains non-numeric characters. | Error | 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_FEES | Invalid Fees The app_fee_money specified in the payment request is too high relative to the payment amount. | 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 |
| 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 |
| INVALID_PHONE_NUMBER | Invalid Phone Number The provided phone number is not in a valid format. | Error | Occasional | T0 |
| INVALID_POSTAL_CODE | Invalid Postal Code The postal/ZIP code provided is incorrectly formatted. | Error | Occasional | T0 |
| INVALID_SORT_ORDER | Invalid Sort Order The provided sort order is not valid. Must be ASC or DESC. | Error | Rare | T0 |
| INVALID_SQUARE_VERSION_FORMAT | Invalid Square-Version Format The Square-Version header value is incorrectly formatted. Use YYYY-MM-DD format. | Error | Rare | 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 |
| LOCATION_MISMATCH | Location Mismatch The location provided does not match what is expected for this resource or operation. | 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 |
| 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 |
| METHOD_NOT_ALLOWED | Method Not Allowed The HTTP method used is not supported for this endpoint. | 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 |
| 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 |
| NO_FIELDS_SET | No Fields Set The request contains no fields to update or process. | Error | Rare | T0 |
| NOT_ACCEPTABLE | Not Acceptable The server cannot produce a response matching the Accept header criteria. | Error | Rare | T0 |
| NOT_FOUND | Not Found The requested resource does not exist. Verify the ID or path used in the request. | Error | Common | T0 |
| NOT_IMPLEMENTED | Not Implemented The requested functionality is not implemented by this API endpoint. | Error | Rare | T1 |
| ONE_INSTRUMENT_EXPECTED | One Instrument Expected Only one payment instrument was expected but multiple were provided. | Error | Rare | T0 |
| PAN_FAILURE | PAN Failure The card number (PAN) is invalid due to incorrect length or formatting. | Declined | Occasional | 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 |
| PAYMENT_AMOUNT_MISMATCH | Payment Amount Mismatch The payment amount Square expected does not match the amount provided in the request. | Error | Rare | T0 |
| PAYMENT_LIMIT_EXCEEDED | Payment Limit Exceeded Square declined the payment because it exceeded the processing limit configured for this merchant. | Declined | Occasional | T1 |
| 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 |
| 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 |
| 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 | 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 |
| RATE_LIMITED | Rate Limited The application has exceeded the Square API rate limit. Implement exponential backoff with jitter before retrying. | 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 |
| REFUND_AMOUNT_INVALID | Refund Amount Invalid The requested refund amount exceeds the amount available to refund on this payment. | Error | Occasional | T0 |
| REFUND_DECLINED | Refund Declined The card issuer declined the refund request. Contact the issuer or try an alternative refund method. | Declined, 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 |
| REQUEST_ENTITY_TOO_LARGE | Request Entity Too Large The request body exceeds the maximum allowed size. | Error | Rare | T0 |
| REQUEST_TIMEOUT | Request Timeout The request took too long to process. Retry with exponential backoff. | Error | Occasional | T0 |
| RESERVATION_DECLINED | Reservation Declined The card issuer declined the refund reservation. | Declined, Error | Rare | T1 |
| SANDBOX_NOT_SUPPORTED | Sandbox Not Supported The requested API action is not supported in the Square Sandbox environment. | Error | Occasional | T1 |
| SERVICE_UNAVAILABLE | Service Unavailable Square's service is temporarily unavailable. Check status.squareup.com and retry with backoff. | Error | Rare | T0 |
| SOURCE_EXPIRED | Source Expired The provided source ID has expired. Generate a new source token. | 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 |
| TEMPORARY_ERROR | Temporary Error A temporary internal error occurred. Safe to retry using the same idempotency key. | Error | Occasional | T0 |
| TOO_MANY_MAP_ENTRIES | Too Many Map Entries The map field contains more key-value entries than allowed. | Error | Rare | T0 |
| 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. | Declined | Common | T2 |
| UNAUTHORIZED | Unauthorized A general authorization error occurred. Check that the Authorization header includes a valid bearer token. | Error | Occasional | T1 |
| UNEXPECTED_VALUE | Unexpected Value A value provided in the request was not expected for this field or context. | Error | Occasional | T0 |
| UNKNOWN_BODY_PARAMETER | Unknown Body Parameter A body parameter was provided that is not recognized by the requested endpoint. | 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 |
| UNPROCESSABLE_ENTITY | Unprocessable Entity The request was well-formed but contains semantic errors that prevent processing. | 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 | Occasional | T3 |
| 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 |
| UNSUPPORTED_INSTRUMENT_TYPE | Unsupported Instrument Type The payment instrument type referenced in the request is not supported for this operation. | Error | Rare | T3 |
| UNSUPPORTED_MEDIA_TYPE | Unsupported Media Type The Content-Type of the request body is not supported. Use application/json. | Error | Occasional | T0 |
| UNSUPPORTED_SOURCE_TYPE | Unsupported Source Type The source type referenced in the API request is not supported for this operation. | Error | Rare | T3 |
| 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 |
| V1_APPLICATION | Legacy V1 Application The application was created before 2016-03-30 and is incompatible with v2 Square API calls. | Error | Rare | T1 |
| VALUE_EMPTY | Value Empty A required field has an empty or default value such as a blank string. | Error | Common | 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_HIGH | Value Too High The numeric value exceeds the supported maximum. | 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_SHORT | Value Too Short The provided string value is shorter than the minimum allowed length. | Error | Occasional | T0 |
| VERIFY_AVS_FAILURE | AVS Verification Failed The Address Verification Service (AVS) check could not be completed or failed. Verify billing address. | Declined | Common | T0 |
| VERIFY_CVV_FAILURE | CVV Verification Failed The CVV verification check could not be completed or failed. Re-collect the security code. | Declined | Common | T0 |
Payment providers you might find interesting:
View all
UnionPay
UnionPay is a global card payment network used by issuers, acquirers, and merchants to accept UnionPay-branded card payments.
Authorize.Net
Authorize.Net is a payment gateway that helps merchants accept card and bank-account payments through supported merchant accounts and e‑/m‑/
Klarna
Klarna is a payment provider that lets merchants offer buy now, pay later and flexible payment options at checkout.
Paysafe Group
Paysafe Group is a payments provider supporting merchants with payment processing and related tools for accepting and managing transactions.
Articles you may find interesting:
View all
How Payment Teams Can Prevent Gateway Holds and Manage Dispute Ratios
Discover how automated risk reviews trigger gateway freezes and how payment teams can insulate revenue through multi-acquirer setups and smart retry logic.
Why Credit Cards Get Declined and How Payment Teams Can Fix It
Payment rejections cost merchants billions in lost sales and unforced churn. Discover the root causes behind issuer declines and how intelligent recovery strategies salvage legitimate revenue.
Why Payment Tests Pass in Staging and Fail in Production
Passing a sandbox check rarely guarantees live authorization success. Learn how real-world issuer ambiguity, webhook delays, and network retry rules impact revenue pipelines.
Testing Payment Systems: Why Sandboxes Lie and How to Test in Production
Sandboxes verify API formatting, but live issuers determine transaction success. Discover how multi-layered testing, safe retry logic, and real-time observability safeguard authorization rates and reduce involuntary customer churn.