Linking of a kiosk to a Square Terminal

Questions
,
1

Hello,

We are currently working on developing a kiosk application that will use the Square Terminals to take payments.

Currently, we’re working on the configuration phase of the kiosk and we just wanted some clear guidance on the recommended process of attaching a square terminal to a kiosk.

They way we envision doing it is as follows:

  1. Generate a kiosk ID (abc-123 for example)
  2. Select a location
  3. Call the v2/devices?location_id=xxx API to get a list of devices
  4. Let the person setting up the kiosk choose a device from the list (e.g if they see abc-123-terminal) OR let them create a new one
  5. If they create a new one, call the POST v2/devices/codes to create a new device code passing in the name field as abc-123-terminal (same as kiosk ID).
  6. If they choose a pre-existing terminal (from step 4), store this terminal’s ID (unsure wether to store x.id or x.type == APPLICATION => x.device_code_id - please advise)
  7. Use the stored device ID on checkout to send to that terminal.

While this does seem like a good plan, we’re not 100% certain that this is the Square recommended approach and would love to have a Square developer weigh in on the matter.

For example, in step 3 will we need to filter out some devices? If so, based on what criteria? I imagine we don’t want to display already paired devices?

Thanks,
C

2

This is the exact flow however when you pair a device code that’s created by CreateDeviceCode that device code that’s used to log into the Terminal can only be used for that Terminal. If your listing device codes you would be doing so to log into previously paired devices or to see any newly created unparied devices.

Once the customer creates and pairs the device then you’ll have the device_id that will be used in the checkouts to prompt the customer to make a payment. :slightly_smiling_face:

3

So should I provide the kiosk configuration with the list of devices or the list of device codes? I’m a little bit confused as to how this flow should be handled. Ultimately we want the person on the kiosk to just assign the correct terminal to the kiosk.

Currently we’re calling:
List devices GET /v2/devices

which we display the information to the operator as follows:
TERMINAL-NAME, TERMINAL-ID, TERMINAL-STATUS

but the issue we’re facing is we don’t know what to do with this information? So the person would choose the terminal that’s next to the kiosk based on the terminal ID (makes sense) but then would we need to create a new code to pair them? Do we need to list codes? I’m not too sure.

4

I’m not sure I fully understand what’s going on in this process. Is this the setup process? If so Terminal API is supper simple. All your kiosk setup needs to do is to CreateDeviceCode. Once the device code is create the person setting up the kiosk will pair it by logging in with the generated code. When they’ve logged in you’ll listen for webhooks for the device_id that we generate to create the checkouts to send to the Terminal. Or you can call ListDeviceCodes to get the device_id. :slightly_smiling_face:

5

Hello,

Yeah this is for the setup process. The issue with the method you’re suggesting is that we could end up hundreds of different devices, no?

For example if:

  1. Generate code
  2. Put code into terminal
  3. After some time the kiosk disconnects or whatever so we need to input a code again
  4. Create new code
  5. Connect with new code

Won’t this approach means we end up with the same device appearing twice?

6

How would you end up with hundreds of device codes? You wouldn’t need a new device code. You can use the same one you previously generated for a Terminal. For example I use the same one that I created for my Terminal back in 2020. They don’t expire once paired. :slightly_smiling_face:

7

Ahh okay thanks for clarifying. So on kiosk setup just always create a new code is generally a safe assumption to be making?

8

Yes, on setup to pair a new device your create one code. Once paired that code won’t expire and you will use it with that Terminal with the kiosk. :slightly_smiling_face: