We have successfully integrated the Square Terminal with our self-checkout kiosks and we are in the latest stages of testing before moving to production.
Is there a way to know the current status of the Square Terminal? Or ping it?
We’d like to know if it’s possible for the kiosk to request the status of the Terminal in order to display an error message in case the device is offline or down. At the moment the only way of knowing is something is wrong with the Terminal is to create a Checkout, but even then it could be tricky.
Example:
Terminal is Offline (no connectivity)
Kiosk generates a Checkout
Checkout created with status PENDING
Checkout remains as PENDING until timeout is reached
Checkout goes from PENDING to CANCELED (cancel_reason: TIMED_OUT)
Since we have to wait for the timeout to be reached this could be a very long time before knowing there is something wrong with the terminal.
By looking at the final state of a TIMED_OUT Checkout, there is no way to know if this was a legit TIME OUT (Payment was displayed at the terminal but customer never paid) or if terminal was simply unreachable.
The only way to know is the following as far as we know:
Checkout went from PENDING to CANCELED with cancel_reason TIMED_OUT -> Terminal unreachable
Checkout went from PENDING to IN_PROGRESS to CANCELED with cancel_reason TIMED_OUT -> Terminal OK, terminal displayed payment but customer never finished
But now we need to keep track of the changes in status of the Checkout. Unless there was a different cancel _reason.
We have thought about a workaround:
If Checkout remains as PENDING for an extended period of time (5/10 seconds) assume terminal is unreachable, display error message in Kiosk and keep trying to reach the terminal to update message in case it gets connectivity again.
We have never seen a Checkout remain as PENDING for more than a few seconds when terminal is OK, it normally goes to IN_PROGRESS in a couple of seconds at most, so this might work.
Would that even work? Any advice here is greatly appreciated.
Here are two checkout IDs for reference: Mu1a2sMgpBnqO, AHJHEuC3dsqqO
You’re correct in that the status will update to IN_PROGRESS as soon as the terminal as received the request and swapped to the payment screen. Per the docs:
The response is returned when the paired Square Terminal acknowledges the checkout request. Note that the PENDING status changes to IN_PROGRESS when the Terminal is showing the checkout to the buyer and awaiting input.
It’s up to you how to handle the cases when it doesn’t change to IN_PROGRESS, but yes, you could check after some brief period of time and display an error that sounds like it should work fine.
Understood, thanks.
We have a HW verification step that occurs when the kiosk reboots, this is just to validate that all peripherals, including the Square Terminal are working properly and notify the customer in case of a malfunction.
If the only way to check this is by doing a “fake” checkout, we run into the following problem.
Use Case: Terminal Offline
Create a “fake” checkout
Wait 5 seconds
Get Checkout and verify status (If status is still PENDING we assume terminal is unreachable, display malfunction)
Cancel Checkout
All Good here, workaround works
Use Case: Terminal Online
Create a “fake” checkout
Wait 5 seconds
Get Checkout and verify status (If status IN_PROGRESS we assume terminal is OK)
Cancel Checkout (Call fails because Checkout is already in IN_PROGRESS)
I don’t see information about that limitation in the API Docs here
But I read that from a PDF we were given prior to this version called [EXTERNAL] BETA - Terminal API User Guide
Do this limitation still apply?
If that’s the case then this workaround won’t work for us. We’d need to wait for the terminal to time out for the transaction to be canceled. Also, we would be displaying a Checkout in the terminal that is not legitimate.
I guess we can reduce the timeout by changing the deadline_duration field on this particular fake checkout?
What would you do in our position?
I checked in with the team, and this is still the way it works (an IN_PROGRESS checkout should not be cancelled via the API). Unfortunately this is not a use-case that is currently supported in the Terminal API.
Understood. Thanks for your help Stephen. We’ll try to find a workaround for this. I’m posting this as a New Feature Request. Hopefully this is something that can be implemented. I can see how this can be very useful for other customers with kiosk solution like ours.
