Enable sandbox support for your public appVersion bêta à destination des développeurs
Enable your public app for sandbox installation
Version bêta à destination des développeurs
Sandboxes is currently in developer preview. Share your feedback on Stripe Insiders, our new early access program.
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.
Managed sandboxes
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 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.
Steps to enable sandbox installs for your public app
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.
(Optional) Update the server-side OAuth flow for sandboxes to use the install link found inside your managed sandbox.
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 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.
Submit your new version for marketplace review.
Update the app manifest
Remarque
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_.
The following example code declares sandbox support:
{ "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.
Remarque
See event behavior to learn more about how the install mode affects event behavior.
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
OAuth apps initiate app installation from within their platform. Like test mode, the developer is responsible for implementing a sandbox install link.
You can find your OAuth sandbox install link inside your managed sandbox.
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.