Enable sandbox support for your public app

Enable your public app for sandbox installation.

Sandboxes 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, so your app must explicitly support both general sandboxes and test mode sandboxes.

To support more businesses to evaluate your app before they go live, add support for general sandboxes.

Enable general sandbox support for your app

You can enable sandbox installs by first updating the app manifest, then updating your keys in your back-end app, and updating your webhooks.

After you enable sandbox support, submit your app for review. Stripe verifies sandbox support as part of the app review process.

Managed sandbox

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

The public ID of your app becomes the name of your managed sandbox.
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.
You can set up connect webhooks in your managed sandbox for your sandbox users.
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.

Enable general 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.19.0 or later before uploading your app. Command Line $ stripe plugin upgrade apps ✔ upgrade to v1.19.0 complete. $ stripe -v stripe version 1.25.1 $ stripe apps -v apps version 1.19.0
Update the app manifest to support sandbox installs.
Use the API keys in your managed sandbox when making Stripe API calls for a sandbox install.
If you use webhooks, create sandbox-specific event hooks inside your managed sandbox. Update server-side logic to listen for these new endpoints.
Upload a new version of your app to your live 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

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
}

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

Keep track of the environment of the installed account to know which API keys to use. For example, if you’re listening to the account.application.authorized event, make sure the authorized accounts in your sandbox endpoint use the sandbox keys.

If you build an app with UI extensions, you can determine if the installed user is a sandbox using the account.isSandbox boolean in the UserContext.

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

Test mode API keys only work for test mode sandbox installs. Only the managed sandbox API keys work for other sandbox installs.

Configure webhook events

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

Switch to your managed sandbox in the dashboard.
Create new webhooks for sandbox events in Workbench.
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 events from the managed sandbox endpoints.

Note

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

Retrieve signing secrets

For webhooks, also retrieve the signing secret from inside the managed sandbox, and validate the secret in your endpoints.

Find install links for OAuth apps

You can find your live mode, test mode sandbox, and general sandbox OAuth URLs on the app details page. Your published app in the install links section and the External testing section have separate URLs.

Use different redirect URIs for your sandbox install links so that you know which key to use in the OAuth authorization code exchange.

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.

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.

Validate sandbox API keys and webhook behavior

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

Inside your test sandbox where you installed the app, 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’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. App sandbox support is verified as part of the app review process and listed on the details page for your app listing.