Payments API and Refunds API

Payments API and Refunds API Error Codes

If an error occurs, the CreatePayment and CreateRefund endpoints return a list of error objects describing the issues encountered. Each error object includes the following elements:

  • code identifies the error type.

  • 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.

CreatePayment errors (additional information) Permalink Get a link to this section

The endpoint-specific errors are documented in the endpoint technical reference. For example, see CreatePayment and CreateRefund. 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 Partial amount 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 that was 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.