Payments API and Refunds API

Payments API and Refunds API Error Codes

If an error occurs, the CreatePayment and CreateRefund endpoints return a list of error objects describing the issues encountered. Each error object includes the following elements:

  • code identifies the error type.

  • detail elaborates on what caused the error and includes the error type.

  • category identifies the error category.

The following is an example error:

"errors": [
      {
           "code": "INSUFFICIENT_FUNDS",
           "detail": "Authorization error: 'INSUFFICIENT_FUNDS'",
           "category": "PAYMENT_METHOD_ERROR"
      }
   ]

The errors array can return multiple errors.

CreatePayment errors
Permalink Get a link to this section

The following are some of the error codes that you might encounter in response to your Connect v2 Payments API CreatePayment endpoint requests.

Error code Description
BAD_EXPIRATION The card expiration date is missing or incorrectly formatted.
INVALID_ACCOUNT The card issuer was not able to locate the account on record.
CARDHOLDER_INSUFFICIENT_PERMISSIONS The card issuer has declined the transaction due to restrictions on where the card can be used. For example, a Gift Card is limited to a single seller.
INSUFFICIENT_PERMISSIONS The Square account does not have the permissions to accept this payment. For example, Square might limit which sellers are allowed to receive Gift Card payments.
INSUFFICIENT_FUNDS The payment source has insufficient funds to cover the payment.
INVALID_LOCATION The Square account cannot take payments in the specified region. A Square account can take payments only in the region where the account was created.
TRANSACTION_LIMIT The card issuer has determined the payment amount is too high or too low. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or prepaid cards (for example, the card has insufficient funds).
CARD_EXPIRED The card issuer declined the request because the card is expired.
CVV_FAILURE The card issuer declined the request because the CVV value is invalid.
ADDRESS_VERIFICATION_FAILURE The card issuer declined the request because the postal code is invalid.
TEMPORARY_ERROR A temporary internal error occurred. You can safely retry your call using the same idempotency key.
VOICE_FAILURE The card issuer declined the request because the issuer requires voice authorization from the cardholder.
PAN_FAILURE The specified card number is invalid. For example, it is an incorrect length or is incorrectly formatted.
EXPIRATION_FAILURE The card expiration date is invalid or indicates that the card is expired.
CARD_NOT_SUPPORTED The card is not supported in the geographic region.
INVALID_PIN The card issuer declined the request because the PIN is invalid.
INVALID_POSTAL_CODE The postal code is incorrectly formatted.
CHIP_INSERTION_REQUIRED The card issuer requires reading the card using a chip reader.
ALLOWABLE_PIN_TRIES_EXCEEDED The card has exhausted its available pin entry retries set by the card issuer. Typically this requires the card holder to resolve the issue by contacting the card issuer.
MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.
PAYMENT_LIMIT_EXCEEDED Square declined the request because the payment amount exceeded the processing limit for this seller.
GENERIC_DECLINE An unexpected error occurred.
INVALID_FEES The app_fee_money on a payment is too high.
CARD_DECLINED_VERIFICATION_REQUIRED This payment requires verification. For more information, see SCA Overview.
GIFT_CARD_AVAILABLE_AMOUNT

When using a Gift Card as a payment source in a `CreatePayment` request, you can allow taking partial payment by adding the accept_partial_authorization parameter in the request. If the Gift Card does not have a sufficient balance to pay the entire amount_money specified in the request, the request succeeds. For more information, see Partial amount with Square Gift Cards.

However, taking a partial payment does not work if your request also includes tip_money, app_fee_money, or both. Square declines such payment and returns this error:

  • The error details provide the amount that was available on the Gift Card at the time of the request. The amount is a string representation in the smallest denomination of the applicable currency. For example, in USD the amount is specified in cents.
  • The error code appears in an array along with the INSUFFICIENT_FUNDS error.
The following is an example set of errors:
{
    "errors": [
        {
            "code": "INSUFFICIENT_FUNDS",
            "detail": "Gift card does not have sufficient balance for requested amount and tip.",
            "category": "PAYMENT_METHOD_ERROR"
        },
        {
            "code": "GIFT_CARD_AVAILABLE_AMOUNT",
            "detail": "4494",
            "category": "PAYMENT_METHOD_ERROR"
        }
    ]
}
          
In addition to the errors, it shows the Gift Card balance at 44.94 USD. You can review this amount and submit a new CreatePayment request with tip_money and amount_money that fit within the available balance.

CreateRefund errors
Permalink Get a link to this section

The following is an error code that you might encounter when calling the Connect v2 Payments API CreateRefund endpoint.

Error typeDescription
RESERVATION_DECLINEDThe card issuer declined the refund.