The new Stripe sandboxes feature makes it easier to manage multiple test environments from a single Stripe account. Sandboxes provide richer functionality than the existing test mode feature and enable you to map test environments more easily to multiple developers in your AWS accounts.
This blog post summarizes the key differences between test mode and sandboxes, shows how to use sandboxes from an AWS-hosted application, and explains how to manage sandbox access if you have more than one developer working on a project.
The differences between test mode and sandboxes
Stripe’s existing test mode feature is useful for developers testing integrations, offering different API keys from production. It’s designed to allow you to simulate successful payments, card errors, disputes, refunds, and authentication scenarios. Its purpose is to allow you to ensure your application responds correctly to the variety of outcomes that can happen in payment flows, and isn’t intended for load-testing or representing all Stripe objects available.
Stripe sandboxes provide a significant evolution of functionality that improves the testing experience for developers. A sandbox is a completely isolated account containing its own set of data, separate from production accounts or other sandboxes. Unlike test mode, which is available to all users who have access to your production account, you can define who has access to sandboxes.
With Sandboxes, you can simulate external events to test payments, accumulating a fake balance instead of real money movement, and use the Test Payouts functionality using API v2 keys, calling API v2. You can use the CLI or SDK to interact with sandboxes by simply changing the API keys used.
While sandboxes are intended to replace test mode, you can continue to use the legacy test mode if preferred. Sandboxes are intended as an additive product experience, and do not require you to migrate or make any changes to your development workflow.
| Legacy test mode | Sandboxes | |
|---|---|---|
| Number per account | 1 | 5 |
| API key access | Unique API key per account | Unique API key per sandbox |
| Isolation | Some settings changed in test mode also affect your live account | Complete isolation per sandbox, separate from your production account |
| Access control | Users who can access the account can also access both production and test modes | You can define which users can access sandboxes, separate from production access |
Using sandboxes from an AWS-hosted application
From the Stripe dashboard, you can access sandboxes from the account picker menu in the upper left. One sign-in may have access to multiple accounts, and each account may have up to 5 sandboxes.
Sandboxes must be created in the Dashboard UI by clicking Create sandbox from this page. Each sandbox must have a name that can be changed after creation. You can also choose to copy settings from your live account, such as the country where the account is based - see the sandbox settings page in the documentation to see exactly which attributes are copied.
Once you have created all the sandboxes needed, you can access the list from the account dropdown or by visiting https://dashboard.stripe.com/sandboxes. As with sandbox creation, the deletion process is also managed in this page - click the trashcan icon to delete a sandbox when finished.
You can access a sandbox from your AWS-hosted application by using its API keys. To see these, click Open next to the sandbox you want to use. The Home tab shows the publishable and secret keys. Generally, for server-based apps, you use the secret key from your workload hosted in AWS. Unlike production secret keys, which are only presented once, you can reveal secret keys in sandbox mode anytime from this screen.
Depending on your configuration and security preferences, you may prefer to use a restricted API key even in the sandbox. These keys can be scoped to specific read and write permissions per resource. This can be good practice for more complex payment configurations with many developers or teams, or where you want to mirror restricted keys in production.
You can control access to the sandbox from the Team and security option in the Settings menu, or from https://dashboard.stripe.com/settings/team. Once a developer has an API key, they have the ability to take any action that the API key has access to. As a result, if you are running your application in AWS, you should only provide login access to the Stripe dashboard to administrators or other roles as needed, and separately guard your API keys.
While a sandbox will never have access to production and cannot be used to move real money, it’s recommended that you treat API keys for these the same way as you do for production. Specifically:
- Don’t embed API keys in code, or pass keys around in chat, email, or other unsecure means. Use services like AWS Secrets Manager to retrieve the key dynamically at runtime and don’t log the key in your code.
- Don’t store keys in source repositories like GitHub, even if the repo is private since this can result in key leakage later.
- Rotate your keys periodically in the Stripe dashboard, and then update AWS Secrets Manager. Restrict who has access to create, modify or delete keys in both Stripe and AWS.
With the keys set up, you can then save production and sandbox keys in AWS Secrets Manager. By using the secret name as an alias when you retrieve the secret, you can confidently use the same code in test and production environments. This is because you haven’t embedded the key directly or used any logic pathing based on the environment, which helps to limit bugs caused by human error.
Managing sandbox access with more than one developer
Many Stripe customers use AWS to host their applications, and for enterprise workloads they often use multiple AWS accounts to separate their development environments. AWS Identity & Access Management allows you to configure granular permissions for your developers to control precise access to resources in those accounts. In larger development teams, you can integrate with directory services (like Active Directory) and use groups so that as employees join and leave your organization or its team, access control is synchronized accordingly.
Once you have configured sandboxes in the dashboard and secured the secrets in AWS Secrets Manager, you should then use IAM resource policies to control access by IAM principals. You can grant access to a single secret to multiple users and roles, or grant access to users and roles in other AWS accounts.
To add a secret in Secrets Manager, you can use the AWS Management Console, AWS SDKs, or AWS CLI. For the CLI, enter the following command in the terminal:
aws secretsmanager create-secret \ --name mySandboxSecret \ --secret-string file://mysecret.json
While the JSON payload for mysecret.json can store any arbitrary text, in this case it could contain the following:
{ "name": "mySandbox", "apiKey": "<< YOUR API KEY >>" }
Learn more about creating secrets in AWS Secrets Manager using the AWS SDKs.
For AWS accounts running beta accounts of your software, you can restrict access to the production Stripe keys to ensure they never accidentally call production APIs. Similarly, you can prevent the production AWS account from accessing sandbox secrets. By embedding this logic into policies instead of logic in code, you can systematically enforce key access and implementation and reduce human error.
Learn more about configuring permission policies or read the AWS Secrets Manager User Guide for details.
Conclusion
With Stripe sandboxes, you can work in test environments that provide greater functionality than the legacy test mode, with strict isolation between each other and production accounts.
For AWS developers using multiple AWS accounts to manage application environments with teams of developers, you can then secure the API keys in AWS Secrets Managers and use IAM resource policies to limit access to those keys. This helps to avoid sharing keys openly, and allows you to apply rigorous access control best practices. You can take advantage of integration with directory services and other automations in your AWS account to lock-down API key access to your developers.
To learn more about developing applications with Stripe, visit our YouTube Channel.
