Troubleshoot the Payments API

Applies to: Payments API

Learn about the error codes returned by the Payments API.

Like other Square API endpoints, CreatePayment returns an errors array with one or more Error objects if errors are encountered during the request. Error objects use the following properties to describe the issues:

• category - A high-level classification of the error. For a complete list of category values, see ErrorCategory.
• code - A specific identifier for the error. For a complete list of error codes, see ErrorCode.
• detail - A human-readable error description for developers, which isn't intended to be customer facing. This is an optional error field.
• field - The name of the field in the original request (if applicable) that the error pertains to. This is an optional error field.

The following is an example error:

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

The Error descriptions section in the Square API Reference lists errors that are specific to an endpoint. For example, see CreatePayment and RefundPayment. The Square API Reference also lists the error codes returned by all endpoints.

The following section provides additional information about specific CreatePayment errors that might require special handling.

When a Square gift card payment fails due to insufficient funds, the CreatePayment endpoint returns both INSUFFICIENT_FUNDS and GIFT_CARD_AVAILABLE_AMOUNT errors, as shown in the following example response:

{
  "errors": [
    {
      "code": "INSUFFICIENT_FUNDS",
      "detail": "Gift card does not have sufficient balance for requested amount.",
      "category": "PAYMENT_METHOD_ERROR"
    },
    {
      "code": "GIFT_CARD_AVAILABLE_AMOUNT",
      "detail": "4494",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}

The detail field of the GIFT_CARD_AVAILABLE_AMOUNT error contains the available gift card balance in the smallest denomination of the applicable currency (for example, in cents for USD).

These errors can occur in different payment flows, depending on your configuration.

Square processes payments from Square gift cards based on how accept_partial_authorization and other payment fields are configured.

For this payment flow, the accept_partial_authorization field is false (default) and the autocomplete field is true (default). Use this configuration when you want to process gift card payments only if the gift card has sufficient funds to cover the entire amount.

If the gift card balance is insufficient, Square returns an INSUFFICIENT_FUNDS error along with GIFT_CARD_AVAILABLE_AMOUNT showing the gift card balance. You can use this balance information to request a new payment within the available amount or request alternative payment methods.

For this payment flow, the accept_partial_authorization field is true and the autocomplete field is false. Use this configuration to implement a multi-tender payment flow where Square automatically uses up to the remaining gift card balance and allows collecting additional payments for any remaining balance.

Note the following important considerations when accept_partial_authorization is true:

• autocomplete must be set to false. Otherwise, Square returns a BAD_REQUEST error.
• app_fee_money isn't supported. If included in the payment request, Square returns a BAD_REQUEST error.
• tip_money isn't supported. If included in the payment request, Square ignores the accept_partial_authorization setting and attempts a full payment (payment amount + tip amount). If the gift card has insufficient funds, Square returns INSUFFICIENT_FUNDS and GIFT_CARD_AVAILABLE_AMOUNT errors. In this case, request a new payment with a valid amount.

For step-by-step instructions for creating an order, handling partial authorizations payments for Square gift cards, and collecting additional payments, see Take Partial Payments with Square Gift Cards.

• Take Payments
• Handling Errors