Skip to main content
This guide prepares the Square account, Tuturuuu workspace, webhook, location, and in-person hardware route. Start with the safe Sandbox checks even when the store already owns a Square Terminal, Square Reader, or Tap to Pay device.
Do not paste credentials, tokens, application secrets, or webhook signature keys into chat, tickets, or documents. Enter them only in the Square settings editor inside the intended Inventory workspace.

​
Who should be present

One person can hold several roles, but the Square owner should explicitly approve the Production seller, location, item, amount, and payment card.

​
Prepare the account and hardware

Have these items ready before opening the setup editor:
  • a Square seller in a country and currency supported by Square;
  • owner access to the Square Developer Console;
  • an Inventory workspace where you can manage Payments and Storefronts;
  • a Square location dedicated to or clearly associated with this counter;
  • either a phone or tablet with the latest Square POS app and a connected Square Reader/Tap to Pay, or a standalone Square Terminal with current software;
  • reliable Wi-Fi or Ethernet without a browser-based captive portal;
  • a clearly named Sandbox demo product with known price and stock;
  • a clearly named, low-value Production test item for the later go-live check.
Review Square’s official Terminal setup guide and hardware network requirements before the launch day when using standalone Terminal hardware. For a phone or tablet, review Square’s Point of Sale mobile web guide.

​
Choose the correct hardware path

Square exposes these devices through different APIs. Choosing the correct path prevents the most common setup failure.
A Square POS device ID such as a phone installation ID is not a Terminal API device ID. Do not paste it into the Terminal dropdown. Tuturuuu opens Square POS on the phone instead, then verifies the returned Square Order and card Payment before completing inventory.

​
Prepare event staff access

Do not share a full workspace administrator account at the counter. In Settings → Members & roles, choose Invite member, then select POS operator — start payments only. The first limited POS invitation performs one confirmed, atomic access migration:
  1. every current workspace member receives the explicit Workspace Admin (preserved) role;
  2. the member-wide default Admin permission is disabled so new members do not inherit it;
  3. Tuturuuu creates a POS Operator role containing only Start POS checkout; and
  4. the pending invitation records that role so it is assigned as soon as the invited person accepts.
The confirmation panel lists the number of current members being protected and explains the resulting access. A POS operator can start an approved Square payment, but cannot edit products, stock, sales, payment settings, members, or roles. For multiple standalone Terminals, staff choose the Payment station in the Storefront checkout form. Tuturuuu validates that the selected device is a paired Terminal API device at the configured selling location before it reserves stock. Square POS App + Reader remains a same-device flow: open the Storefront on the compatible phone or tablet that should launch Square POS.
Never use a public shopper account as event staff. The checkout API enforces the POS permission server-side and rate-limits repeated dispatches; hiding the button is not the security boundary.

​
Open the correct Tuturuuu workspace

  1. Sign in to Inventory.
  2. Select the customer’s workspace.
  3. Open Payments in the sidebar.
  4. Stay on Connect & set up.
  5. Choose Square POS.
  6. Confirm the environment badge before changing anything.
The page shows five detected checks: Use the compact Edit Square settings button only when you are ready to complete the next check. Stop editing afterward so accidental changes are less likely.

​
Fast handoff when Production is preconfigured

If a technical helper already prepared Production, do not paste or rotate the credentials again. Keep the page read-only and verify these visible facts with the Square account owner:
  • the environment is Production;
  • the masked connection and webhook checks are complete;
  • the location is the real owner-approved selling location;
  • Catalog sync shows the expected Production links and no unexplained conflicts;
  • the intended hardware path is clear. A phone/Reader path does not require a Terminal API device or Terminal webhook key; a standalone Terminal does.
The customer can then skip credential entry and continue directly to the Production hardware path. The owner still needs to confirm business, bank, tax, tip, and receipt settings inside Square. Tuturuuu cannot safely choose those business settings on the customer’s behalf.

​
Part 1: configure Sandbox

1

Create or select the Square application

Open the Square Developer Console, create an application for the Tuturuuu integration, and keep the environment toggle on Sandbox. Use a recognizable name such as Tuturuuu Sandbox.In Inventory, choose Sandbox, enable editing, and copy the Sandbox Application ID and Application secret into Square app credentials. Save them before starting OAuth.
2

Register the OAuth redirect URL

Copy the OAuth redirect URL displayed by Inventory. In the Square application’s Sandbox OAuth settings, add that exact HTTPS URL as an authorized redirect.Do not type the URL from memory. The scheme, domain, path, and trailing characters must match what Inventory displays.
3

Authorize the Sandbox seller

Choose Connect OAuth in Inventory. Sign in to or select the intended Sandbox test seller and approve the requested permissions. Return to Inventory and confirm the read-only connection summary shows a token ending in four characters.OAuth is preferred because the connection can refresh and the seller can revoke it. A manual Sandbox token is available for a controlled rehearsal, but it must still belong to the same application and environment.
4

Create the Sandbox webhook subscription

Copy the Webhook notification URL shown in Inventory. In the Square application’s Webhooks section, create a Sandbox subscription with that exact URL and these seven events:
  • device.code.paired
  • terminal.checkout.created
  • terminal.checkout.updated
  • payment.updated
  • oauth.authorization.revoked
  • catalog.version.updated
  • inventory.count.updated
Copy the subscription’s signature key into Inventory and save. Send a Square test event and confirm its delivery returns a 2xx response. Square can deliver the same event more than once, so duplicate delivery is expected and handled idempotently.
5

Select the Sandbox location

Refresh locations in Inventory and choose the test location owned by the Sandbox seller. Confirm its country and currency match the rehearsal. Catalog stock counts are associated with this selected Square location.
6

Select a Sandbox simulator device

Square Sandbox cannot pair real hardware through the Devices API. Paste a supported Terminal simulator device ID into the Sandbox device field and save it as the default. Start with the success simulator from Square’s current Sandbox test values.
The Sandbox guide should now show 5/5 checks complete. Continue with the Sandbox test plan before creating any Production connection.

​
OAuth permissions

Tuturuuu requests only the permissions needed for the Terminal, orders, payments, catalog, and inventory workflows: If the customer declines a required permission, the corresponding readiness check or API action fails closed. Re-authorize the correct seller instead of adding a second unrelated token.

​
Part 2: create a separate Production connection

Do this only after Sandbox exit criteria pass.
1

Switch both systems to Production

In Square Developer Console, switch the application to Production. In Inventory, switch the Square setup guide to Production. Verify both environment labels before copying anything.
2

Repeat credentials, OAuth, and webhook setup

Save the Production Application ID and secret, register the Production OAuth redirect URL, authorize the real seller, and create a separate Production webhook subscription using the URL shown in Inventory. Save the Production signature key. Never reuse a Sandbox credential or key.
3

Choose the real selling location

Select the Square location that owns the counter, currency, receipts, tax, and reporting. Ask the Square owner to verify the location name before saving.
4

Prepare the in-person hardware

For Square POS app + Reader, install or update Square POS, sign in to the selected location, and connect the Reader or enable Tap to Pay. For a standalone Terminal, power it, install updates, load paper, and connect to the final counter network. Continue with the matching Production path.

​
Connection review

Before pairing, the read-only Production summary should show: If any row is unexpected, stop and correct it before creating a device code. Continue with the Production launch guide.

​
Official Square references