Skip to main content
Version: 1.x

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

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​

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​

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

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
  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, 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​

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​

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​

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

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​

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​

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

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​

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​

For technical support:

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