# Enable sandbox support for your public app

Enable your public app for sandbox installation.

[Sandboxes](https://docs.stripe.com/sandboxes.md) are Stripe’s testing environment. Your users can install apps in sandboxes to evaluate app features and functionality.

## General sandbox versus test mode sandbox support

Stripe supports two environments: live mode and sandboxes. Every Stripe account has sandboxes, including a test mode sandbox. The test mode sandbox is a unique type of sandbox with characteristics that [differ from general sandboxes](https://docs.stripe.com/testing-use-cases.md#compare), so your app must explicitly support both general sandboxes and test mode sandboxes.

You can support both types of sandboxes so more businesses can evaluate your app before they go live.

### Enable general sandbox support for your app

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

You can enable sandbox installs by updating the [app manifest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md). After you enable sandbox support, [submit your app for review](https://docs.stripe.com/stripe-apps/publish-app.md). Sandbox support is verified as part of the [app review process](https://docs.stripe.com/stripe-apps/review-requirements.md).

### Managed sandbox

A *managed sandbox* is a 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](https://docs.stripe.com/workbench/guides.md) events from user sandbox installs inside your managed sandbox.

- Changes made to a managed sandbox don’t affect users installing your app in live mode or test mode sandboxes.

- 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](https://docs.stripe.com/stripe-apps/upload-install-app.md) to your account.

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

## Enable general sandbox installs for your public app

1. Run `stripe apps -v` to verify you’re on the latest version of the [Stripe CLI](https://docs.stripe.com/stripe-cli/upgrade.md) and [Stripe Apps plugin](https://docs.stripe.com/stripe-apps/create-app.md#install-stripe-apps-cli). You must be on version 1.5.23 or later before uploading your app.
   ```bash
   $ 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
   ```
1. Update the app manifest to support sandbox installs.
1. *(Optional)* Create sandbox-specific event hooks inside your managed sandbox. Update server-side logic to listen for these new endpoints.
1. *(Optional)* Update server-side logic to use your [managed sandbox API keys](https://docs.stripe.com/sandboxes/dashboard/manage-access.md) when making Stripe API calls for a sandbox install.
1. Upload a new version of your app to your main account (**not** your managed sandbox).
1. From your main account, [create an external test link](https://docs.stripe.com/stripe-apps/test-app.md) for the sandbox-enabled version you just uploaded.
1. Create and open a new sandbox to test your updated app.
1. In a browser window, visit the external test link you created earlier to install your app.
1. Test that your app works as expected when installed in a sandbox.
1. Submit your new version for marketplace review.

### Update the app manifest

> 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](https://docs.stripe.com/stripe-apps/reference/app-manifest.md#schema) with `sandbox_install_compatible`.

The following example code declares sandbox support:

```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
}
```

### Understand 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 sandboxes.

- 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 sandbox.

- When a user installs an app in a test mode sandbox, a connection is made to your test mode sandbox.

### Configure 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.

> See [event behavior](https://docs.stripe.com/stripe-apps/build-backend.md#event-behavior-depends-on-install-mode) to learn more about how the install mode affects event behavior.

### Retrieve signing secrets

For webhooks, you might also need to [retrieve the signing secret](https://docs.stripe.com/webhooks/signature.md#check-the-endpoint-secret) from inside the managed sandbox.

### Configure API keys

Your managed sandbox has its own set of [API keys](https://docs.stripe.com/keys.md) for making calls for sandbox installs. When responding to sandbox-specific webhooks or events you must use these [managed sandbox keys](https://docs.stripe.com/sandboxes/dashboard/manage-access.md).

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

### Find OAuth sandbox links

You can find your live mode, test mode sandbox, and general sandbox OAuth URLs on the [External test](https://docs.stripe.com/stripe-apps/test-app.md) tab inside your app settings.

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

## Test your app in a sandbox

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

1. From your main account, [create an external test link](https://docs.stripe.com/stripe-apps/test-app.md) for the sandbox-enabled version you just uploaded.

1. Create a new sandbox to test your updated app. Open the new sandbox.

1. In a new browser window visit the external test link you created earlier to install your app.

1. Test your app works as expected installed in a sandbox.

### Validate sandbox API keys and webhook behavior

You can use [Workbench](https://docs.stripe.com/workbench.md) 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](https://docs.stripe.com/workbench/guides.md#view-logs-by-source), and [filtering events](https://docs.stripe.com/workbench/guides.md#filter-events). If you’ve 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’ve 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](https://docs.stripe.com/stripe-apps/publish-app.md). App sandbox support is verified as part of the [app review process](https://docs.stripe.com/stripe-apps/review-requirements.md) and listed on the details page for your app listing.