Learn about the error codes returned by the Payments API and Refunds API.
Payments API

Troubleshooting the Payments API

If an error occurs when attempting to create a payment, the CreatePayment endpoint return a list of error objects describing the issues encountered. Each error object includes the following elements:

  • code identifies the error type. For a list of CreatePayment error codes, see Error Descriptions in the technical reference.

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

  • category identifies the error category.

The following is an example error:

The errors array can return multiple errors.


The comprehensive list of error codes is available in TechRef (see ErrorCode). The endpoint-specific errors are documented in the endpoint technical reference. For example, see CreatePayment and RefundPayment. The following sections provide additional information about specific errors.

This section provides additional details about specific errors that the CreatePayment endpoint returns.

Error code GIFT_CARD_AVAILABLE_AMOUNT. When using a Square gift card as a payment source in a CreatePayment request, you can allow taking a 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 Take partial payments 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 payments and returns the following error:

  • The error details provide the amount 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:

In addition to the errors, the example 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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.