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 ofCreatePayment
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.
Note
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.