# 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 #### Easy Pairing Pair terminals from WooCommerce using a short-lived Square Device Code #### Webhook-Confirmed Verified Square webhooks confirm completion, with live status while you wait #### 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 Square notifies your site with a signed webhook. The webhook is the authoritative completion signal; the POS also polls so the status updates while you wait. This means the Square Terminal device must be online and signed in to the same Square account and location, and your site must be publicly reachable over HTTPS so Square can deliver webhooks. ## Installation[​](#installation "Direct link to Installation") 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 #### Configure Square Settings 1. Navigate to `WP Admin > WooCommerce > Settings > Payments` 2. Find **Square Terminal** in the payment methods list and click it to open the settings 3. Choose the **Environment** (`Sandbox` for testing, `Production` for live payments) 4. Enter your **Access Token** for the selected environment (Sandbox or Production), available from the [Square Developer Dashboard](https://developer.squareup.com/apps) 5. Enter your **Location ID** — the Square location where Terminal payments are taken 6. Enter your **Webhook Signature Key** and **Webhook Notification URL** (see the next step) 7. Click **Validate Settings** to confirm the credentials work, then save note You do not need to enable the Square Terminal gateway in WooCommerce settings. It will be enabled specifically for the POS in a later step. 3 #### Set Up Webhooks in Square Square sends a signed webhook when a Terminal payment finishes, and this is what marks the order as paid. 1. In the [Square Developer Dashboard](https://developer.squareup.com/apps), open your application and go to the **Webhooks** section 2. Add a subscription for the **`terminal.checkout.updated`** event 3. Set the notification URL to the **Webhook Notification URL** shown in the plugin settings — it must match **exactly** 4. Copy the **Webhook Signature Key** into the plugin settings so incoming events can be verified Important The Webhook Notification URL in Square must exactly match the value in the plugin settings, and the Webhook Signature Key must be correct. If they don't match, Square payments will complete on the device but the WooCommerce order will not update. 4 #### Pair Your Square Terminal 1. On the same settings page, click **Create Device Code** 2. A pairing code is generated and shown to you 3. On your Square Terminal, sign in and enter the code on the device-pairing screen 4. Once paired, the terminal is linked to your configured location. Note its **Device ID** — you'll enter this when taking a payment Important The terminal must be successfully paired and online before you can process payments. Make sure pairing is complete before proceeding. 5 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **Square Terminal** gateway in the list 3. Enable the gateway for use in the POS 4. Save your settings ## 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**: Choose "Square Terminal" as the payment method 3. **Choose Device**: Enter the **Terminal Device ID** of the paired terminal that should take the payment 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. **Automatic Completion**: When Square's verified webhook confirms the payment, the order is marked paid. The live status updates while you wait. ### Payment Controls[​](#payment-controls "Direct link to Payment Controls") When using the Square Terminal gateway, you have the following options: * **Start Payment**: Send a new payment request to the selected terminal * **Cancel Payment**: Cancel a payment that is currently in progress on the terminal * **Payment Status**: A live status area shows the current state of the payment * **Payment Log**: A per-order log records each meaningful Square step and outcome ### Order Management[​](#order-management "Direct link to Order Management") * **Webhook-Authoritative Completion**: Orders are marked paid only when a verified Square webhook confirms the Terminal payment * **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 API Credentials : Access Token, Location ID, and Webhook Signature Key from the Square Developer Dashboard Compatible Hardware : A Square Terminal device, online and signed in to the same Square location Public HTTPS Site : Your site must be reachable over HTTPS so Square can deliver webhooks 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, and your site must receive Square webhooks over HTTPS for orders to update. ### 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") v0.1 scope * This early release is focused on **POS / order-pay** flows. Availability on the customer-facing storefront checkout is off by default and must be explicitly enabled. * It **collects payments only** — refunds are not yet supported. Square identifiers are stored on the order so refund support can be added later. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") Device won't pair * Make sure you entered the Device Code before it expired — generate a fresh one with **Create Device Code** if needed * Confirm the terminal is online and signed in to the same Square account and **Location ID** as the plugin * Check that the **Environment** (Sandbox/Production) and **Access Token** match the account the terminal is signed in to Validate Settings fails * Verify the **Access Token** matches the selected **Environment** (a Sandbox token won't work in Production, and vice versa) * Confirm the **Location ID** belongs to that account * Re-copy the token from the Square Developer Dashboard in case of stray characters Payment completes on the terminal but the order doesn't update * The **Webhook Notification URL** in Square must match the plugin setting **exactly** * Make sure the **`terminal.checkout.updated`** event is subscribed in the Square Developer Dashboard * Confirm the **Webhook Signature Key** in the plugin matches the one in Square * Ensure your site is publicly reachable over HTTPS; check webhook delivery attempts in the Square Dashboard Payment won't start * Confirm a valid **Terminal Device ID** is entered and the device is paired and online * Check that the device is signed in to the configured **Location ID** * Review the **Payment Log** and WordPress error logs for Square API messages ### 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 ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * Square credentials, webhook, and device-pairing configuration * Gateway enablement in WCPOS settings * Payment processing workflow in the POS checkout