Square Terminal: multiple Payment objects for a transaction
Closed this issue · 5 comments
The Square Terminal API has always allowed for the possibility of multiple Payment
objects being created by a single TerminalCheckout
.
Today we finally saw one in the wild!
A single TerminalCheckout
returned two Payment
IDs. The first Payment was in state "FAILED" and the second was in state "COMPLETED".
Unfortunately the till treated these as two valid payments; the transaction then showed as paid twice. The member of staff tried to refund the first, failed payment; obviously this refund failed. They then refunded the successful payment, leaving the till showing the transaction as closed but with us not having the money. Recording the session totals then failed, complaining that the failed payment had no associated fee.
The solution is to check the status of all the payments returned in a TerminalCheckout
and ignore any in the "FAILED" or "CANCELED" states. (The other possible states are currently "APPROVED", "PENDING" and "COMPLETED"; I don't know if the payment objects transition through these before arriving at COMPLETED in a way that might be visible to the till.)
Hmm. It might be more reliable to use the Payment
object approved_money
field when creating the till Payment
objects; on failed payments this will be zero. It's also possible that Square might break up successful charges into a series of Payment
objects that add up to the expected total.
Hmm. The documentation for approved_money
is a bit ambiguous, though. We should ask for clarification.
Going with "if the state is FAILED or CANCELED then treat the payment as having zero value".
Tentative fix is in eda8c66; leaving this open until we have more experience and an answer about approved_money
on the developer forums.
For reference, this was transaction 880375 at the Haymakers.
Apparently this isn't supposed to happen: https://developer.squareup.com/forums/t/terminalcheckout-with-multiple-payment-ids/9196