Skip to main content
Square Sandbox simulates Terminal API checkouts without a physical Terminal or real card. Use it to prove the workflow and failure recovery before any Production credential is saved.
Square hardware cannot be paired to Sandbox. Tuturuuu uses Square’s special Sandbox Terminal device IDs to produce deterministic results. Sandbox payments do not reach a bank and do not incur processing fees.

​
What Sandbox can and cannot prove

​
Create isolated demo data

Use records that are unmistakably temporary and owned by the test:
Use a fictional customer name and email, or omit customer details. Square warns against storing personal information in Sandbox. Do not reuse a real customer’s name, phone number, address, or card data.
Do not delete or archive pre-existing Square records. Import or modify only the clearly labeled demo item. Tuturuuu catalog sync never deletes Square objects; any later manual cleanup in Square requires the account owner’s separate approval.

​
Simulator device IDs

Copy these from Square’s current Terminal API Sandbox test values into the Sandbox device ID field one scenario at a time: Keep the test total at or below USD 25 for the standard success simulator. Square deliberately leaves larger attempts pending rather than treating them as an ordinary approval.

​
Test flow

For every scenario:
  1. Open Payments → Connect & set up → Square POS → Sandbox and save the intended simulator ID.
  2. Confirm all five Sandbox checks are complete.
  3. Confirm the demo Storefront uses Square Terminal checkout.
  4. Open Payments → Test & verify in one tab and the Sandbox Square Dashboard in another.
  5. Submit one checkout only. Do not double-click or start a second checkout while the first is pending.
  6. Match the checkout ID, amount, currency, status, and timestamps across both systems.
  7. Record the final stock and reservation result before changing the simulator.

​
Required checkout matrix

A pending result is not permission to send the order again. First cancel or reconcile the existing Terminal checkout. Re-sending an uncertain order can create a second payment request.

​
Reservation expiry test

Tuturuuu checkout reservations expire 15 minutes after creation. Expiry is materialized by the scheduled sweep and also reconciled during checkout reads and new checkout creation.
  1. Use the unavailable Terminal simulator.
  2. Create one checkout and verify the item becomes reserved.
  3. Do not create a replacement checkout.
  4. Cancel it through the Inventory Commerce action for a fast test, or allow the reservation to expire for the full expiry-path test.
  5. Verify the checkout is no longer sellable as pending, the reservation is released, and stock returns exactly once.

​
Duplicate webhook test

Square can retry webhooks and does not guarantee delivery order. Tuturuuu uses Square event IDs and provider identifiers to reconcile duplicates safely.
1

Complete one successful Sandbox checkout

Record its Tuturuuu checkout ID, Square Terminal checkout ID, payment ID, stock before and after, and finance transaction if the workspace records one.
2

Resend a Square webhook delivery

In the Square Developer Console, open the relevant Sandbox webhook delivery and resend it once. Use the same event; do not create a second payment.
3

Verify idempotency

The webhook may appear twice in delivery history, but Tuturuuu must still show one checkout, one payment link, one completion transition, one stock change, and at most one finance sale.

​
Catalog and stock rehearsal

Run this after the checkout matrix so the payment flow and catalog flow can be diagnosed separately.
  1. Open Payments → Catalog sync.
  2. Enable sync actions with the compact edit control.
  3. Choose Import from Square and verify the demo item appears as one linked Square variation.
  4. Change only the demo item’s name, price, or physical count on one side.
  5. Run the matching one-way sync and verify the other side once.
  6. Make different changes on both sides, run Two-way sync, and confirm the item becomes a review conflict instead of silently overwriting either side.
  7. Restore the demo item through an intentional one-way sync after deciding which side is authoritative.
An unchanged Square inventory count might not emit an inventory.count.updated event. Use an actual demo count change when validating that webhook, then restore the count deliberately. For the full data model and conflict rules, see Catalog and stock synchronization.

​
Exit criteria

Sandbox is complete only when:
  • all five connection checks are ready;
  • the seven webhook events are subscribed and a test delivery returns 2xx;
  • approved, canceled, timed-out, and unavailable-device scenarios match the matrix;
  • duplicate webhook delivery does not duplicate payment, stock, or finance;
  • a 15-minute or explicitly canceled reservation releases correctly;
  • the demo catalog item is visible as a linked variation;
  • a two-sided edit becomes a review conflict;
  • no Production token, object, device, or payment was touched.

​
Test evidence template

When every exit criterion passes, continue with Production launch.