Square Terminal
Pairing a Square Terminal with a register and taking card payments through it.
Square Terminal is the hardware option: connect your Square seller account once, then pair a physical terminal to each store. Pick the terminal payment method in the POS, the terminal wakes up, the customer taps, dips or swipes, and the sale closes.
Before you start
- You need a Square seller account (squareup.com) and at least one Square Terminal device.
- The Integrations tab is only visible to owners and admins — staff cannot see or change any of this.
- Have the terminal charged, switched on and connected to the shop's Wi-Fi or ethernet dock before you begin — the pairing code only lives for five minutes, so set the hardware up first.
Step 1 — Connect your Square account
- Go to Settings → Integrations → Square Terminal.
- Press Connect to Square. You are sent to Square to sign in and authorise, then returned to the panel.
- The panel now reads Connected to your business name, with your merchant ID and primary location under it — check these to confirm the right seller account is connected.
Disconnect (top-right of the panel) severs the account link — terminal payments stop working until you reconnect. Pairing and sales history are kept.
Step 2 — Pair the terminal to a store
On the Square Terminal: tap Sign in → Use a device code, then enter:
Code expires in 5 minutes. We'll auto-detect once it's paired.
Paired terminals
+ Pair a terminal| Name | Store | Status | Code / Device | |
|---|---|---|---|---|
| Front counter | Newtown | paired | 9fa747a2-25ff-48ee | Revoke |
| Workshop bench | Newtown | unpaired | XKQP-VJRW | Revoke |
src/app/suite/settings/integrations/SquarePanel.tsx. The code is typed into the terminal itself, not into this screen — and the screen polls every three seconds while an unpaired code is showing, so the row flips to paired on its own once Square confirms it. The last column carries the pairing code until then and the device id afterwards.- In the same panel, press + Pair a terminal.
- Give the device a Name you will recognise at the counter (it defaults to "Front counter") and choose the Store it belongs to — each store pairs its own terminals.
- Press Generate code. A short device code appears in an amber banner. Do this standing at the terminal: the code expires after 5 minutes, and if it lapses you Revoke that row and generate a fresh one — there is no way to extend a code.
- On the Square Terminal itself: tap Sign in → Use a device code, and type the code in.
- There is nothing to confirm on our side — the panel detects the pairing automatically within a few seconds and the row flips to paired, showing the device's ID in place of the code.
The terminal needs to be charged, switched on and connected to the shop's Wi-Fi (or ethernet dock) before it can accept a device code or wake for a sale. A terminal that has dropped off the network shows up as a checkout that never arrives — check the device's connection before suspecting the POS.
Step 3 — Point a payment method at the terminal
The till routes a payment to the terminal through the payment method's gateway, so the last step is to bind one:
- Go to POS → Settings → Payments.
- Add a method with + Add Method (or edit an existing one, such as your current "Card" or "EFTPOS" method) and set its gateway to Square Terminal.
The method's name is up to you — the gateway setting, not the name, is what wakes the terminal. Without this step the integration is connected but nothing at the counter will ever use it.
Taking a payment
src/app/suite/pos/POSModule.tsx and src/app/suite/pos/components/SquareTerminalModal.tsx. Two things are worth knowing. The staff PIN comes first — the terminal is only sent a checkout once the sale is approved — and the sale is written to the server only after the card is captured, so a customer who cancels on the terminal leaves no sale behind and the payment screen simply re-opens for another method. Drawn as a flow because it runs across the POS screen and a piece of hardware on the counter.At the counter, the cashier picks the Square-backed payment method and confirms their staff PIN. The POS shows Sending to terminal…, the terminal wakes with the amount on screen, and the customer taps, dips or swipes. When Square confirms, the POS reads Payment captured. Finalising sale… and the sale is recorded.
The card is collected before the sale is posted — a declined card or a customer cancelling on the device never leaves a recorded sale behind; the POS returns to the payment screen. A checkout that should not go ahead can be cancelled from the POS rather than left hanging on the device.
Payments go to the most recently paired terminal at the sale's store, so run one active terminal per store — pairing a second one takes over from the first.
Refunds
Nothing extra to learn: run a normal POS refund and choose to refund to the original payment. When the sale was taken through Square, the money is sent back to the customer's card automatically — the terminal stays idle and the customer does not need to be present. If the card refund fails at Square's end, the POS refund still stands and you are told, so you can sort the card side out separately. See Refunds and returns.
Unpairing or replacing a device
Revoke on a device row disconnects that terminal — it can no longer take payments for the store until it is paired again. Replacing hardware is just revoke old, pair new; the sales history is untouched.
Reconciliation
Completed transactions are reconciled back by webhook, so the POS learns the outcome from Square rather than assuming it.