Square Terminal integration

This runbook covers the Inventory and Storefront integration with Square Terminal. Use Square Terminal API for countertop terminal payments; the Square POS API opens the mobile Square Point of Sale app and is not the right integration for driving physical terminals from Tuturuuu.

​

How the flow works

1. A shopper checks out on a checkoutMode: 'square_terminal' storefront. Tuturuuu validates Square readiness, creates a local checkout reservation, stores the provider as square_terminal, and returns the buyer to the local order reference page.
2. Inventory staff sends the reserved checkout to a Square Terminal from the commerce workflow. Tuturuuu creates a Square order, then creates a Terminal checkout for the selected location and device with the Square order id and itemized cart display enabled.
3. Square sends terminal checkout and payment webhooks. Tuturuuu verifies the raw webhook body signature before parsing, reconciles duplicate deliveries idempotently, and completes the checkout only after a verified paid payment.
4. On Square create failure, cancellation, expiry, or failed terminal checkout, Tuturuuu releases the local reservation so stock returns to availability.

V1 does not sync the Square catalog. Tuturuuu Inventory remains the source of truth for products, stock, bundles, listing prices, and checkout reservation state.

​

Workspace credentials

Square credentials are self-serve per workspace, like Inventory Polar settings. Do not configure Square app credentials, access tokens, or webhook signature keys as deployment secrets. Workspace admins save these values in Inventory → Settings → Square Terminal, where Tuturuuu encrypts secret values before private-schema storage. The Square REST client pins Square-Version: 2026-05-20 and uses native fetch. OAuth is the recommended connection method because Tuturuuu can refresh tokens and validate granted scopes. Manual access-token configuration remains available for controlled deployments and does not require saved Square OAuth app credentials.

​

Configure Square

1. Create or open a Square application in the Square Developer Dashboard.
2. Configure the OAuth redirect URL:
   https://<your-tuturuuu-domain>/api/v1/inventory/square/oauth/callback
   
3. Grant these OAuth scopes:
   • MERCHANT_PROFILE_READ
   • ORDERS_READ
   • ORDERS_WRITE
   • PAYMENTS_READ
   • PAYMENTS_WRITE
   • DEVICE_CREDENTIAL_MANAGEMENT
4. Create a webhook subscription for the Inventory Square endpoint:
   https://<your-tuturuuu-domain>/api/v1/inventory/square/webhook/<workspace-id>
   
   Subscribe at minimum to:
   • device.code.paired
   • terminal.checkout.created
   • terminal.checkout.updated
   • payment.created
   • payment.updated
   • oauth.authorization.revoked
5. Copy the webhook signature key into Inventory → Settings → Square Terminal for the matching environment.

For local development, expose apps/web with an HTTPS tunnel and either use the tunnel URL in Square or save that exact URL as the workspace webhook notification URL so signature validation uses the same value.

​

Connect a workspace

1. Open Inventory → Settings → Square Terminal.
2. Choose Sandbox or Production.
3. Save the Square Application ID and Application Secret for that environment. If Square is configured with a tunnel or canonical URL that differs from the actual request URL, also save the exact webhook notification URL so HMAC validation uses the same URL Square signed.
4. Prefer Connect OAuth. For manual setup, paste an access token and save it with the matching environment.
5. Save the webhook signature key for the same environment.
6. Select a Square location.
7. Pair or select a terminal:
   • Production: create a device pairing code, enter it on the physical Square Terminal, then select the paired device. The pairing request uses Square’s TERMINAL_API product type.
   • Sandbox: use Square’s sandbox terminal device id when device listing is not available.
8. Set a storefront’s checkout mode to Square Terminal.

Readiness fails closed until the connection, required scopes, webhook signature key, location, device, and environment all match. OAuth-backed connections also require saved workspace Square app credentials so refresh can continue without deployment secrets. Storefront checkout returns a configuration error instead of reserving stock when Square is not ready.

​

Hardware-free verification

No mocked test can prove that a specific production countertop terminal is online, paired to the right Square seller account, assigned to the selected location, has a working network path, and can complete a real card-present payment. Without hardware, treat the automated suite as Square contract and reconciliation verification, not physical-device certification. The no-hardware suite must cover these Square contracts before release:

• OAuth authorization URL, token exchange, refresh, scope parsing, encrypted storage, and secret redaction.
• REST base URLs for sandbox and production, Square-Version, bearer auth, sanitized upstream errors, and idempotency keys.
• Orders API payloads before Terminal checkout creation.
• Terminal checkout payloads with order_id, device_options.device_id, and device_options.show_itemized_cart.
• Device Code creation with product_type: TERMINAL_API and paired-device webhook reconciliation.
• Raw-body webhook HMAC validation against the exact Square notification URL before JSON parsing.
• Terminal checkout, payment, OAuth revocation, cancellation, expiry, failure, duplicate delivery, and event-id reconciliation behavior.
• Reservation-first lifecycle: create local reservation before Square calls, release on Square create/cancel/failure/expiry, and complete stock/ledger state only after verified Square payment success.

​

Physical-terminal smoke checklist

Use sandbox first when terminal coverage is available. If hardware sandbox coverage is not sufficient, use a production test procedure that avoids real customer inventory and refunds immediately after verification.

1. Pair a terminal for the selected Square location.
2. Create a small Storefront order and confirm Inventory shows it as reserved.
3. Use Inventory commerce actions to send it to the terminal.
4. Complete the payment on the terminal.
5. Confirm Square webhook delivery succeeded and Tuturuuu marked the checkout completed with Square order, terminal checkout, payment, and receipt URL metadata.
6. Confirm stock reservations were consumed and the finance ledger sale was booked once.
7. Repeat cancel, expiry/failure, duplicate webhook delivery, and transient Square failure cases. Cancel/failure/expiry must release inventory.