# Square Terminal Gateway

The Square Terminal gateway lets you collect WooCommerce order payments on [Square Terminal](https://squareup.com/hardware/terminal) hardware directly from WCPOS. A payment is requested from WooCommerce and completed on a paired Square Terminal device, and the result is written back to the order.

## Features[​](#features "Direct link to Features")

### Hardware Integration

Send payments to paired Square Terminal devices and collect card-present payments

### One-Click Connect

Authorize with Square directly — no access token to create or paste

### Reliable Completion

Payments are confirmed by polling and a background sweeper, with webhooks to speed it up

### Secure Transactions

PCI-compliant, card-present processing handled on Square hardware

### Sandbox & Production

Validate against the Square Sandbox before switching to live payments

## How It Works[​](#how-it-works "Direct link to How It Works")

Unlike browser-SDK gateways, Square Terminal uses Square's **server-side Terminal API**. When you start a payment, WooCommerce creates a Terminal Checkout for the order and Square pushes it to the paired device. The customer pays on the terminal, and the result is written back to the order.

**How a payment is confirmed.** The POS polls Square while the payment is in progress, and a background sweeper reconciles anything the poll misses — a closed browser tab, for example. Square webhooks are an *optional* addition that shortens the wait; they are not required, and a site without them never loses a payment.

The Square Terminal device must be online and signed in to the same Square account and location as the plugin.

## Setup[​](#setup "Direct link to Setup")

1

### Install Square Terminal for WooCommerce

Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/square-terminal-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`.

2

### Connect to Square

1. Go to `WP Admin > WooCommerce > Settings > Payments` and open **Square Terminal**
2. Under **Square account**, choose the **Environment** — **Test mode (sandbox)** for testing, **Live** for live payments
3. Click **Connect to Square** and approve the permissions Square shows you
4. Choose the **Location ID** — the Square location the Terminal takes payments for

Choose the environment **before** connecting. A connection covers one environment only; a sandbox connection can never authorize production payments.

Already using the official WooCommerce Square plugin?

Environment and Location ID are pre-filled from its settings. Only those two values are read — no credentials are shared between the plugins, and you still need to connect or supply an access token here.

Prefer to use your own access token?

Open **Advanced settings** and paste an access token for the selected environment instead of connecting. Everything else works identically.

3

### Pair your Square Terminal

Under **Terminal**:

1. Click **Create Device Code** — a pairing code appears. Enter it within five minutes, or create a new one
2. On the Square Terminal, open the device-code sign-in screen and enter the code. If the Terminal is currently signed in to Square POS or another integration, sign out of that first — the device-code screen is not reachable while it is in use elsewhere.
3. Click **Check for readers** to confirm it now appears under *Paired with this plugin*

An empty list before pairing is expected, not a fault. Square's device API only reports Terminals that have been set up for **Terminal API** use — a Terminal running Square POS does not appear at all until a device code is entered on it.

Test mode has no device codes

Square's sandbox has no device codes, so there is nothing to pair. In **Test mode (sandbox)**, pick one of Square's test devices at checkout instead (see [Processing Payments](#processing-payments)).

4

### Enable in WCPOS

1. Go to `WP Admin > POS > Settings > Checkout`
2. Find the **Square Terminal** gateway and enable it for the POS
3. Save your settings

note

The **Enable/Disable** checkbox on the WooCommerce settings screen controls the *online store* checkout only. WCPOS uses this gateway automatically once it is configured, whether or not that box is ticked.

## Pairing a Terminal[​](#pairing "Direct link to Pairing a Terminal")

A Square Terminal has to be paired with **this plugin** before a cashier can select it. Pairing creates a Terminal API *Device Code*, and that is the only way the plugin can address the device.

Under **Terminal** on the settings screen:

* **Create Device Code** — generates a code to enter on the Terminal. It expires after five minutes; generate a fresh one if it expires.

* **Check for readers** — lists what Square can see, in two groups:

  <!-- -->

  * **Paired with this plugin** — selectable at checkout
  * **Other devices Square can see at this location** — set up by another application, so not selectable here until paired with this plugin

* **Validate Settings** — checks the credentials and location against Square

Why a Terminal you own might not be selectable

Device Codes belong to the application that created them, so a Terminal set up by another Terminal API integration appears under *Other devices Square can see* but cannot be selected here. A Terminal running Square POS does not appear at all.

Either way the fix is the same: sign the Terminal out of whatever it is currently paired to, then enter a fresh **Create Device Code** here.

## Webhooks[​](#webhooks "Direct link to Webhooks")

Webhooks are **optional**. They shorten how long a payment takes to confirm. Polling and the background sweeper confirm every payment regardless, so a site without a webhook subscription still works correctly — just a little slower to settle.

Not available if you used Connect to Square

A webhook subscription belongs to a Square *application*, and adding one needs access to that application in the Square Developer Dashboard. If you connected with **Connect to Square** you are authorizing the WCPOS application rather than one of your own, so there is no dashboard for you to add a subscription in and no signature key for you to copy.

Payments still confirm normally — by polling and the sweeper. The steps below apply only if you set the plugin up with **your own access token** under Advanced settings.

To add one, using your own Square application:

1. On the settings screen, under **Terminal → Webhooks**, click **Copy** to copy the webhook URL
2. In the [Square Developer Dashboard](https://developer.squareup.com/apps), open your application and go to **Webhooks**
3. Add a subscription for the **`terminal.checkout.updated`** event, pasting that URL as the notification URL
4. Copy the **Webhook Signature Key** from Square into **Advanced settings** in the plugin

The **Webhooks** row then reports whether a signature-verified webhook has arrived, and when.

The URL must match exactly

Square signs each webhook over the notification URL it was given. If the URL in Square differs from the plugin's by even a character, every delivery fails verification. Use the **Copy** button rather than typing it.

Why this step is manual

Square's Webhook Subscriptions API is scoped to the *application*, not to individual sellers, and [cannot be called with a seller access token](https://developer.squareup.com/docs/webhooks/webhook-subscriptions-api). The plugin therefore cannot create the subscription for you.

### If webhooks stop verifying[​](#webhook-troubleshooting "Direct link to If webhooks stop verifying")

The **Webhooks** row shows *Not verified yet* when no webhook has arrived and verified under the **current** settings. If payments have already run, check in this order:

1. The **Webhook Signature Key** in Advanced settings matches the one in Square
2. The notification URL in Square matches the URL shown in the plugin, exactly
3. The `terminal.checkout.updated` event is subscribed
4. Your site is publicly reachable over HTTPS — check delivery attempts in the Square Dashboard

Changing the environment, webhook URL, or signature key resets this row until the next webhook arrives. That is intended: a delivery verified under the old settings says nothing about the new ones.

## Settings reference[​](#settings "Direct link to Settings reference")

The settings screen is ordered the way setup runs.

| Section                | Contains                                                   |
| ---------------------- | ---------------------------------------------------------- |
| **Square account**     | Environment, **Connect to Square**, Location ID            |
| **Terminal**           | Pairing controls, reader list, webhook status              |
| **Checkout behaviour** | Skip receipt screen, collect signature, debug logs         |
| **Advanced settings**  | Access tokens, webhook signature key, webhook URL override |

**Advanced settings** is collapsed by default. It holds the manual access tokens — needed only if you are not connecting — and the webhook signature key. The **Webhook URL override** should stay empty unless your public URL differs from the one the plugin derives, for example behind a proxy or custom domain.

## Usage[​](#usage "Direct link to Usage")

### Processing Payments[​](#processing-payments "Direct link to Processing Payments")

1. **Add Items**: Add products to your cart in the POS
2. **Select Gateway**: Press **Checkout**, open the **Legacy** tab and choose Square Terminal. The steps below describe its payment page there; a version of the extension with a tender-pane tile shows it on the **Payments** tab instead
3. **Choose Device**: Pick the paired terminal from the **Terminal Device** list
4. **Start Payment**: Click **Start Payment** — Square pushes the checkout to the device
5. **Customer Payment**: The customer taps, inserts, or swipes their card on the Square Terminal
6. **Completion**: The status updates live while you wait, and the order is marked paid once Square confirms the payment

In **Sandbox**, the device list contains Square's documented test device IDs, so every outcome — success, timeout, offline — can be exercised without hardware.

### Payment Controls[​](#payment-controls "Direct link to Payment Controls")

* **Start Payment**: Send a new payment request to the selected terminal
* **Cancel Payment**: Cancel a payment currently in progress on the terminal
* **Check Status**: Ask Square for the current state immediately
* **Release Payment**: Detach an unresponsive terminal so the order can be paid another way; the abandoned checkout is still reconciled in the background
* **Payment Log**: An optional per-order log recording each Square step and outcome

### Order Management[​](#order-management "Direct link to Order Management")

* **Verified completion**: Orders are marked paid only after the payment is verified against Square's Payment object — never on an unverified signal
* **Payment Tracking**: Square identifiers and a payment log are stored on the order, and key steps are written to order notes
* **Receipt Generation**: Standard POS receipts are generated after successful payments

## Requirements[​](#requirements "Direct link to Requirements")

Square Account

<!-- -->

: Active Square seller account

Square Location

<!-- -->

: A Square location, and its Location ID

Compatible Hardware

<!-- -->

: A Square Terminal device, online and signed in to the same Square location

Public HTTPS Site

<!-- -->

: Required only if you want webhooks; payments confirm by polling without them

WCPOS

<!-- -->

: Pro version required for POS checkout

## Hardware Compatibility[​](#hardware-compatibility "Direct link to Hardware Compatibility")

Connectivity Requirements

Square Terminal uses Square's server-side Terminal API: the checkout is created by your site and delivered to the paired device by Square. The terminal must be online and signed in to the same Square account and location as the plugin.

### Supported Terminals[​](#supported-terminals "Direct link to Supported Terminals")

* **Square Terminal** ✅ — Square's dedicated countertop card terminal

## Scope & Limitations[​](#scope-and-limitations "Direct link to Scope & Limitations")

Current scope

* Focused on **POS / order-pay** flows. Availability on the customer-facing storefront checkout is off by default and must be explicitly enabled.
* **Collects payments only** — refunds are not yet supported. Square identifiers are stored on the order so refund support can be added later.
* Webhook subscriptions must be added manually in Square; see [Webhooks](#webhooks).

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Common Issues[​](#common-issues "Direct link to Common Issues")

The Terminal Device list is empty

* The Terminal has to be paired **with this plugin** first — use **Create Device Code** and enter the code on the device
* A Terminal paired through the Square Dashboard or the Square POS app will not appear until it is paired here
* Click **Check for readers**: if it appears under *Other devices Square can see*, it exists but is not paired with this plugin
* Confirm the **Location ID** matches the location the Terminal is signed in to

Device won't pair

* Make sure you entered the Device Code before it expired — generate a fresh one with **Create Device Code**
* Confirm the terminal is online and signed in to the same Square account and **Location ID** as the plugin
* Check the **Environment** matches the account the terminal is signed in to

Validate Settings fails

* If connected, check the **Square account** row still shows *Connected to Square*; if it asks you to reconnect, the authorization lapsed
* If using an access token, verify it matches the selected **Environment** — a Sandbox token will not work in Production, and vice versa
* Confirm the **Location ID** belongs to that account

Payment completes on the terminal but the order is slow to update

* This is what webhooks fix. Without one, the order updates when polling or the background sweeper next reconciles it
* Check the **Webhooks** row — if it says *Not verified yet* after payments have run, follow [If webhooks stop verifying](#webhook-troubleshooting)
* The order is never lost: the sweeper reconciles any payment the poll misses

Payment won't start

* Confirm a terminal is selected and the device is paired and online
* Check that the device is signed in to the configured **Location ID**
* Review the **Payment Log** and `WooCommerce > Status > Logs` for Square API messages

It says reconnection to Square is required

Square authorizations are renewed automatically. If a renewal cannot complete, the plugin ends the authorization rather than leaving it in an unusable state, and the settings screen asks you to reconnect. Click **Reconnect to Square** — nothing else needs changing.

### Getting Help[​](#getting-help "Direct link to Getting Help")

For technical support:

* Visit the [GitHub repository](https://github.com/wcpos/square-terminal-for-woocommerce) to report issues
* Check the [Square Terminal API documentation](https://developer.squareup.com/docs/terminal-api/overview) for hardware and API guidance
* Contact Square support for account and hardware issues

Logs are written to `WooCommerce > Status > Logs` under the `sqtwc` handle, and record each device lookup and webhook outcome.

## Screenshots[​](#screenshots "Direct link to Screenshots")

Screenshots will be added in a future update to show:

* The Square account, Terminal, and Advanced settings sections
* Gateway enablement in WCPOS settings
* Payment processing workflow in the POS checkout
