search

sde1000 / quicktill

Figure out where all the money and stock went to
GNU General Public License v3.0
43 stars 8 forks source link

Square Terminal: multiple Payment objects for a transaction #254

Closed sde1000 closed 1 year ago

sde1000 commented 1 year ago

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

sde1000 commented 1 year ago

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.

sde1000 commented 1 year ago

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

sde1000 commented 1 year ago

Tentative fix is in eda8c6606e5bd98893d75857a5c4862a2e9f5b8e; leaving this open until we have more experience and an answer about approved_money on the developer forums.

sde1000 commented 1 year ago

For reference, this was transaction 880375 at the Haymakers.

sde1000 commented 1 year ago

Apparently this isn't supposed to happen: https://developer.squareup.com/forums/t/terminalcheckout-with-multiple-payment-ids/9196