Troubleshoot the Payments API

If an error occurs when attempting to create a payment, the CreatePayment endpoint returns 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.
• 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.

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 doesn't have a sufficient balance to pay the entire amount_money specified in the request, the request succeeds. For more information, see Partial Payment Authorizations.

However, taking a partial payment doesn't 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:

{
    "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, the example shows the gift card balance of $44.94 USD. You can review this amount and submit a new CreatePayment request (with tip_money and amount_money) that fits within the available balance.