Sandbox & Environments

Sandbox basics

A real, stateful test world — not a mock.

The sandbox is a full copy of the merchant experience running on test data. Payments settle, invoices are issued, disputes open and close, payouts pay out — all with fake money, on a real ledger.

What is isolated

• Its own test merchants, one per environment
• Its own credentials (test client id / secret, spat_test_… tokens)
• Its own webhook endpoints and delivery logs
• Its own rate-limit counters

Nothing in the sandbox can read or write live data, and no email is ever sent to a real customer.

Instant verification

Sandbox payout onboarding completes immediately: no documents, no bank details, no real identity. Bank management and live-access UI stay hidden until you switch to live mode.

Seeding

Seed data fills an environment with a plausible merchant: products, prices, customers, a handful of settled payments and one open dispute. Wipe data clears objects but keeps the environment and its installs.

Resetting

Resetting an environment clears data, installs and webhook logs and re-issues the test merchant. Use it when a broken test state is faster to throw away than to repair.

Working with environments

Multiple isolated workspaces, multiple installed apps.

An environment is one isolated test workspace: a test merchant, its data, its installations and its logs.

Why more than one

You can hold up to five environments per organization and switch between them from the sandbox header. The selection is remembered per browser; if an environment disappears (deleted, or from another organization) the dashboard falls back to your default one.

Installing apps

Any of your apps can be installed into any environment, and one environment can hold several apps at once. Installing runs the real consent flow and issues a real sandbox token, so multi-app scenarios ("my app plus a competitor's webhook noise") are testable.

Uninstalling revokes the tokens and emits installation.uninstalled to your endpoints.

Deleting

Deleting an environment cascades: test merchant, objects, installations, tokens, webhook endpoints and logs are removed. The default environment is recreated automatically if you delete everything.

Environment dashboard

Each environment shows, in real time:

• installed apps and their granted scopes
• API requests: method, path, status, latency, rate-limit headroom
• webhook deliveries with payload, response and retry history
• the financial ledger: payments, refunds, disputes, payouts, balance

Simulating money flows

Drive payments, refunds, disputes and payouts by hand.

Every state change a real merchant can experience is triggerable from the environment's ledger tools — and each one emits the same webhook a live account would.

Funds maturity

Sandbox funds follow a T+2 availability model, like production: a payment lands in pending, becomes available after two simulated days, and only available funds can be paid out. Advance the clock from the ledger view instead of waiting.

Raw event simulation

Any event from the event catalog can also be fired directly with a synthetic payload — useful to test handlers for cases that are awkward to reach, such as invoice.payment_failed.

Test cards

Going live

Moving from sandbox credentials to real merchants.

Checklist

1. App approved and published.
2. Payout account verified in live mode (real entity, real bank account).
3. Billing method on file for the publishing fee.
4. Live redirect URIs registered (HTTPS, exact).
5. Webhook endpoint deployed on a public HTTPS URL with signature verification.
6. Secrets stored server-side; no client id/secret pair in front-end code.

What changes

First 24 hours

Watch Logs for 401, 403 insufficient_scope and 429 — those three cover almost every launch bug. Set your alert threshold at 1 % error rate for the app.

Rollback

If something is wrong, unpublish the app. Existing installations keep working, but no new merchant can install while you fix it.