Reference
Sandbox, OpenAPI, Postman
Sandbox#
A sandbox operator is created by platform staff: POST /v1/organizations {type:"Operator", name, slug, sandbox:true}. Everything beneath it
(resellers, merchants synced in) is sandbox automatically; the flag can't be set on a live tree or removed.
- API keys from a sandbox organization are
tsk_test_…; a live key never works on a sandbox tenant and a test key never works on a live one (same 401 as a wrong key). - Webhook events from a sandbox carry
livemode:false. - Sandbox data is real rows in the same database, isolated by the usual org-path scoping. Nothing in it touches real money; transactions are whatever you post.
Run the whole flow from the docs#
BASE=https://<sandbox-host> API_KEY=tsk_test_... SIGNING_SECRET=... ./scripts/sandbox-flow.shIt syncs a merchant, branch and terminal, creates a product and stock, opens a terminal session, records a card sale, posts the matching
bank transaction and shows the reconciliation summary (the two pair up, zero exceptions). Set WEBHOOK_URL to also register an endpoint and
watch sale.created arrive. Key scopes needed: sync:write terminals:session catalog:write inventory:write sales:read transactions:write webhooks:write.
Verified live against a local API on 16 Nov 2026 (including a delivered webhook with livemode:false).
OpenAPI#
openapi/tillstack.v1.json (OpenAPI 3.1) is generated from the running API and checked in. OpenApiContractTests fails when the
API's shape drifts from it. After an intentional change: UPDATE_OPENAPI=1 dotnet test --filter OpenApi, review the diff, commit.
The spec includes auth schemes and the webhook events. Live copy: GET /openapi/v1.json.
Postman#
node openapi/make-postman.mjs → openapi/tillstack.postman_collection.json (92 requests, folder per controller). Import it, set
baseUrl, apiKey, and signingSecret (a pre-request script then signs POST/PUT/PATCH bodies), or token for a user/terminal session.
Regenerate after the spec changes; the collection is derived, never hand-edited.
Not done#
No self-serve sandbox sign-up (platform staff provision it); no sandbox reset/seed endpoint; no console screens for webhooks yet; the Postman collection has not been run in Newman against a live environment.