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:
codeidentifies the error type. For a list of
CreatePaymenterror codes, see Error Descriptions in the technical reference.
detailelaborates on what caused the error and includes the error type.
categoryidentifies the error category.
The following is an example error:
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.
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
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
amount_money that fit within the available balance.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.