v0.2.0

Square Terminal for WooCommerce 0.2.0

This release replaces the 0.1.0 proof-of-concept payment flow with a production-grade Terminal payment loop, built from the hard-won lessons of our Stripe, SumUp, and Mollie Terminal plugins and Square's official integration guidance.

Highlights

A cashier flow that never dead-ends

• Live payment tracking — the checkout screen now follows the Terminal payment in real time (waiting for card, in progress, complete), with automatic retry backoff when the network is shaky.
• Safe cancellation — cancelling now confirms what actually happened on the terminal. If the customer completed payment just as you cancelled, the payment wins and the order completes; you'll never see "cancelled" for money that was taken.
• Offline terminal recovery — if a terminal is unplugged or unresponsive mid-payment, you can release the payment and collect another way (different terminal, cash) without abandoning the WooCommerce order. A ten-minute background sweep keeps checking detached payments even after the cashier leaves the page.
• Reload-proof — refreshing or reopening the payment page re-attaches to the in-flight Terminal payment instead of orphaning it.
• Timeout honesty — when a payment times out, the plugin makes one final authoritative check with Square before declaring it over, so a payment captured at the deadline boundary is never lost.

Orders you can trust

• Orders are only marked paid from server-verified Square state — a signature-verified webhook or a direct server-side Square lookup. The browser is never trusted. If webhooks are misconfigured entirely, payments still complete via polling.
• The actual collected amount is verified against Square's Payment records (tips are recorded separately), and Square payment IDs are stored immediately as the permanent record. If Square collected less than the order total, the order stays on hold for manual verification instead of being marked paid.
• If a Terminal checkout captures money after the order was already paid, the order gets a prominent duplicate-payment alert with the additional payment IDs so staff can review a refund in Square Dashboard.
• Duplicate webhooks, out-of-order Square events, and stale callbacks from earlier payment attempts are detected and ignored. Per-order locking serializes concurrent polling, webhook, cancellation, detach, order-status, and sweep mutations.

Clearer failures

• Square errors are translated into short, actionable cashier messages; raw provider details go to WooCommerce logs only.
• An optional checkout debug log setting adds a copyable log panel to the payment screen for support calls.
• New Terminal settings: skip receipt screen and collect signature.

Test without hardware

• In Sandbox mode the terminal selector lists Square's simulated test devices — success, tip, buyer-cancel, timeout, and offline-terminal scenarios — so the full flow can be exercised with no physical terminal.

Known limitations

• Production terminals are still entered by device ID; the guided pairing flow ships in the next release.
• Webhook subscriptions must still be configured manually in the Square Developer Dashboard (automatic setup ships in the next release).
• Refunds from WooCommerce are not yet supported; payment IDs are stored so refunds can be issued from the Square Dashboard.
• Background reconciliation uses WordPress WP-Cron, so on a store with no traffic a scheduled ten-minute sweep can run late until WordPress receives another request.
• Validated with the automated PHP and JavaScript test suites; end-to-end validation against live Square Sandbox is in progress on our hosted test environment.

Upgrade notes

• No settings changes are required when upgrading from 0.1.0.
• Requires PHP 8.1+, WordPress 6.5+, WooCommerce 8.0+.