Square Terminal Gateway

The Square Terminal gateway lets you collect WooCommerce order payments on Square 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

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

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

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 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 — Sandbox for testing, Production 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
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.

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

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 is short-lived; 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 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, 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. The plugin therefore cannot create the subscription for you.

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

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

Processing Payments

1. Add Items: Add products to your cart in the POS
2. Select Gateway: Choose "Square Terminal" as the payment method
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

• 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

• 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

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

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

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

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.

Troubleshooting

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
• 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

For technical support:

• Visit the GitHub repository to report issues
• Check the Square Terminal API documentation 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 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