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:

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

The errors array can return multiple errors.

Link to section

CreatePayment errors (additional information)

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:

{
    "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 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.