v0.8.1

Square Terminal for WooCommerce 0.8.1

Fixes the Square Point of Sale handoff for the common case where the payment page runs inside an iframe, and gives cashiers a debug log they can copy and send to support when a handoff does not work.

Fixed

The Square POS app now opens from a framed payment page

A merchant reported tapping Open Square Point of Sale on Android and getting nothing: the status sat at "Opening Square Point of Sale…", the button greyed out, and the app never appeared.

The payment fields render inside an iframe on the order-pay page. Browsers refuse to launch an external protocol from a subframe, so the intent: navigation on Android — and square-commerce-v1: on iOS — was being dropped with no error and no event, which is why the page appeared to freeze. The handoff now drives the top frame when it is same-origin and reachable, and otherwise clicks a target="_top" anchor to carry the user's tap out of the frame. Ordinary Terminal-mode redirects are unchanged and still navigate in place.

Silent handoff failures now report themselves

If the app does not come to the foreground within 2.5 seconds of the tap, the page now says so and re-enables the button, instead of leaving the cashier looking at a status that never changes. The check is cancelled as soon as the page is hidden, so a handoff that does work is unaffected.

The "Pay for order" button no longer competes with the real action

WooCommerce renders its own Pay for order submit beneath the payment box, but this gateway never completes through it — process_payment only redirects back to the same order-pay URL, and both collection methods finish elsewhere. Pressing it reloaded the page and wiped the status. It is now hidden while Square is the selected payment method, and restored the moment another method is selected, so switching gateways still works.

Added

Cashier debug log for the Square POS handoff

The debug log that Terminal mode already had is now available in Square Reader mode too, behind the existing Checkout debug logs setting. It records the detected platform, the browser user agent, whether the page is framed and whether the top frame is reachable, which navigation route the handoff took, the parameters Square returned, and the handoff URL itself. Cashiers can copy the whole log from the payment page and send it to support.

The order key is redacted from the logged URL — both from the request metadata and from the fallback URL that carries it as a query parameter — so the log can be shared without handing over the ability to pay the order.

Changed

Clearer Square POS payment panel

Status messages now use the same colour and spinner treatment as Terminal mode, so "Opening…" is visibly in progress and an error no longer looks identical to an informational note. The handoff button is styled as a real primary action; it previously used wp-admin button classes that have no effect on the storefront, leaving it looking weaker than the buttons around it. The redundant heading and nested card border were removed in Reader mode, where the surrounding payment box already provides them.

Upgrade notes

• No settings changes are required. Terminal mode behaviour is unchanged.
• To collect a log, enable Checkout debug logs in the gateway settings; the panel then appears under the payment button on the order-pay page.

Verification status

• Observed: composer lint clean, composer test 280 tests / 964 assertions, composer test:js 45/45. Review findings from Greptile, Codex, and CodeRabbit on PR #26 were fixed with regression tests (order key in the fallback URL, discarded navigation strategy, accumulating change listeners, hidden sole-gateway input).
• Observed: the order-key leak was reproduced directly against buildAndroidPosUrl before the fix and is now covered by a test using a realistic order-pay URL; the frame-escape logic is covered by tests for the same-origin, cross-origin, and unframed cases.
• Not verified on a real device. Square provides no sandbox for the Point of Sale API, and the iframe diagnosis was reached from the reporter's screenshots and the code rather than from a reproduction. This release is intended for the reporting merchant to test. Recommended first check: tap Open Square Point of Sale and confirm the Square app opens; if it still does not, enable Checkout debug logs, tap again, and send the log — the platform, framing, and navigation-strategy lines are what identify the remaining cause.