Terminal checkout request fails for tip only payment

Questions
1

The use case here, is that a customer is purchasing items, but they have also been given a discount that actually lowers the total amount due down to zero. However, the customer is still given the option to provide a tip amount.

If we try process this scenario using Square’s Terminal “Checkout” API to take payment on a Square Terminal device, we immediately get an error back:

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "detail": "amount must be > 0",
      "field": "amount_money.amount",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}

NOTE: We have verified that it is possible to apply this kind of tip only payment to a Square Order using the Payments API. We just can’t seem to take a tip only payment using the Terminal API and a Square device.

Any help or guidance would be greatly appreciated.

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Take a Cash Payment
Working with Monetary Amounts in Square APIs
Update Payment and Tip Amounts

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

The Terminal API currently does not support processing payments with a zero amount. This is why you’re receiving the error message “amount must be > 0”. This means you cannot process a tip-only payment using the Terminal API and a Square device.

However, as you’ve noted, you can apply a tip to a zero-amount order using the Payments API. This discrepancy is due to the different capabilities of the APIs.

Unfortunately, there’s no workaround for this limitation in the Terminal API at this time.

This answer was reviewed by @Bryan-Square.