Stripe test mode vs sandbox: what changed, and how to move off legacy
Updated 2026-07-26
The confusing part is that "test mode" hasn't disappeared from how people talk about Stripe. Nothing changes about the money. No real charge happens in a sandbox, and the same test card 4242 4242 4242 4242 still works. What changed is where that testing lives. Legacy test mode was one non-live view bolted onto your single account. A sandbox is a separate copy of the account. So the real question isn't "test or live," it's "which environment do I test in now, and how do I get my old integration off the legacy view."
The one table you need
| Environment | Keys / data | Isolation | Best for |
|---|---|---|---|
| Legacy test mode | One set of test keys, tied to your single account | Shares config with live; no separation between testers | Older integrations not yet migrated |
| Sandbox | Own API keys, webhooks, data and settings per sandbox (up to 5) | Fully isolated copy of the account | Day-to-day development, CI, staging, demos |
| Production | Live keys, real customers, real charges | The real account; changes affect real money | Serving actual payments |
Why the model changed
With one shared test view, everyone stepped on each other. One developer's webhook change, test data or setting was visible to everyone else testing against the same account. Sandboxes fix that by isolation. Each sandbox is its own copy with independent keys and configuration, so a change in one doesn't leak into another or into production. That's the whole point: you can hand a sandbox to CI, another to a developer rebuilding checkout, and another to sales for demos, without any of them colliding.
Choose by job
- Building or debugging an integration: a sandbox. It's the default now, and its isolation means your test data and webhook tweaks stay yours.
- Automated tests in CI: a dedicated sandbox with its own keys, so a test run can't disturb a developer's environment.
- Staging or demos: a separate sandbox again, kept stable, so a demo doesn't inherit half-finished test data.
- Serving real customers: production. Nothing else touches real money.
How to migrate off legacy test mode
- Create a sandbox for each distinct need (dev, CI, staging) rather than reusing one for everything. You have room for up to five.
- Swap the API keys. Each sandbox issues its own publishable and secret keys. Replace the legacy test keys in your config with the sandbox's keys.
- Re-point every webhook. Webhook endpoints are per environment. Register your endpoints inside the sandbox and update the signing secret you verify against, or events won't arrive.
- Re-seed configuration. A sandbox is a fresh copy, so products, prices, coupons and other setup you relied on in test mode may need to be recreated or re-imported.
The mistakes that cost teams a day
- Assuming a sandbox inherits your test-mode data. It's an isolated copy, not a mirror of the old view. Check what actually carried over before you trust a test.
- Forgetting the webhook signing secret. New environment, new secret. Verification silently fails if you keep the old one.
- Expecting perfect parity with production. Some features behave differently outside live mode. Treat a green sandbox run as strong evidence, not a guarantee, for anything money- or fraud-related.
- Sharing one sandbox for everything. You gave up the shared-test-view problem for a reason. Don't recreate it by piling CI, dev and demos into a single sandbox.
FAQ
What is the difference between Stripe test mode and a sandbox?
Legacy test mode was a single non-live view of your one Stripe account, sharing configuration with the live side. A sandbox is an isolated copy of the account with its own API keys, webhooks, data and settings. You can run several sandboxes at once, and changes in one do not touch production or another sandbox.
Are Stripe sandboxes free?
Yes. Sandboxes are part of every Stripe account at no extra cost. You are not billed for creating or using them, and no real money moves through them.
How many sandboxes can I have?
Up to 5 per account. That is usually enough to give a few developers, a CI pipeline and a staging environment their own isolated space instead of everyone sharing one test view.
Do I still need to update my webhooks and API keys when I migrate?
Yes. Each sandbox has its own publishable and secret keys and its own webhook endpoints. Any key or endpoint you hardcoded against legacy test mode has to be re-pointed at the sandbox, or events and calls will go to the wrong place.
Sources: Stripe: Sandboxes ↗
Sandbox limits and behaviour are Stripe-published as of 2026-07-26; some features differ from production, so confirm parity for anything payment-critical against the current docs.