Enable Sandbox support for your public app

Enable your public app for Sandbox installation.

Sandboxes are the default testing environment.

Test mode is no longer the default testing method. Stripe accounts come with Sandboxes as the default testing method. You can access your sandboxes using the account picker or on the Sandboxes page in your Dashboard.

A sandbox is an isolated test environment. Use your sandbox to test Stripe functionality in your account and experiment without affecting your live integration. Users can install apps in sandboxes to evaluate their features and functionality.

Test mode versus sandbox support

Stripe supports three environments: Sandboxes, live mode, and test mode. However, Sandboxes is the default testing method for new Stripe businesses.

We strongly recommend implementing Sandbox support for your app so as many merchants as possible can evaluate your app before going live.

Enable sandbox support for your app

By default, users can’t install your public app into a sandbox without additional work.

Similar to test mode, you can enable sandbox installs by updating the app manifest. After you enable sandbox support, submit your app for review. App sandbox support is verified as part of the app review process.

Managed sandbox

A managed sandbox is a unique type of sandbox that Stripe automatically creates in your account to support your public Stripe app.

Stripe automatically creates a managed sandbox the first time you upload a public app.
When a user installs your app into their sandbox, it establishes a connection to your managed sandbox.
You can debug and monitor events from user sandbox installs inside your managed sandbox.
Changes made to a managed sandbox don’t affect users installing your app in live or test mode.
You can’t delete a managed sandbox.

Create a managed sandbox

Stripe automatically creates a managed sandbox for you the first time you upload a public Stripe app to your account.

For public apps uploaded before February 3, 2025, Stripe automatically created a managed sandbox in your account.

Enable sandbox installs for your public app

Run stripe apps -v to verify you’re on the latest version of the Stripe CLI and Stripe Apps plugin. You must be on version 1.5.23 or later before uploading your app.
Command Line
```
$ stripe plugin upgrade apps
✔ upgrade to v1.7.0 complete.
$ stripe -v
stripe version 1.25.1
$ stripe apps -v
apps version 1.7.0
```
Update the app manifest to support sandbox installs.
(Optional) Create sandbox-specific event hooks inside your managed sandbox. Update server-side logic to listen for these new endpoints.
(Optional) Update server-side logic to use your managed sandbox API keys when making Stripe API calls for a sandbox install.
Upload a new version of your app to your main account (not your managed sandbox).
From your main account, create an external test link for the sandbox-enabled version you just uploaded.
Create and open a new sandbox to test your updated app.
In a browser window, visit the external test link you created earlier to install your app.
Test that your app works as expected when installed in a sandbox.
Submit your new version for marketplace review.

Update the app manifest

Nota

As of February 3, 2025, you must declare sandbox support as true or false in the app manifest for apps published to the marketplace.

To support installing your app in a sandbox, declare sandbox support in the app manifest with sandbox_install_compatible.

The following example code declares sandbox support:

stripe-app.json
{
  "id": "com.invoicing.[YOUR_APP]",
  "version": "1.2.3",
  "name": "[YOUR APP] Shipment Invoicing",
  "icon": "./[YOUR_APP]_icon_32.png",
  "distribution_type": "public",
  "sandbox_install_compatible": true
}

Understanding sandbox connections

When a user installs your public app into their sandbox, a connection is made to your managed sandbox. This differs from the behavior when your app is installed in live mode or test mode.

When a user installs an app into a sandbox, a connection is made to your managed sandbox.
When a user installs an app in live mode, a connection is made to your live mode and test mode.
When a user installs an app in test mode, a connection is made to your test mode.

Webhook events

If your app listens to events from your users’ installs, there is additional setup to handle apps installed in sandboxes.

Inside your managed sandbox, create new webhooks for sandbox events.
If a user installs your app into a sandbox, Stripe sends any applicable events only to your managed sandbox endpoints.
Update your server-side logic to handle sandbox specific events.

Nota

See event behavior to learn more about how the install mode affects event behavior.

Signing secrets

For webhooks, you might also need to retrieve the signing secret from inside the managed sandbox.

API keys

Your managed sandbox has its own set of API Keys for making calls for sandbox installs. When responding to sandbox-specific webhooks or events you must use these managed sandbox keys.

You can find the correct API keys to use for sandbox installs inside your managed sandbox.

OAuth sandbox links

You can find your live, test, and sandbox OAuth URLs on the External test tab inside your app settings.

If your app uses RAK or platform authentication, no changes are required.

Testing your app in a sandbox

After you’ve updated your app to handle sandbox installs, you can test your app in your own sandbox.

From your main account, create an External test link for the sandbox-enabled version you just uploaded.
Create a new sandbox to test your updated app. Open the new sandbox.
In a new browser window visit the External test link you created earlier to install your app.
Test your app works as expected installed in a sandbox.

Validating sandbox API keys and webhook behavior

You can use Workbench to validate that your sandbox installation works correctly.

Inside your test sandbox, perform some example actions.
Next, inside your managed sandbox, open Workbench.

Use Workbench to inspect your app behavior, including reviewing API logs, and filtering events. If you have updated your app correctly you can see all the API calls and webhook events for your example actions.

If you don’t see the expected events or responses, double check you’re inside your managed sandbox. Also check you have set up your sandbox specific webhook endpoints, and that your app is using the correct sandbox API keys as appropriate.

Submit your app for review

After you enable sandbox support and validate your app works as expected inside a sandbox, you can submit your app for review. App sandbox support is verified as part of the app review process and listed on the details page for your app listing.