Testing use cases

Sandboxes are Stripe’s testing environment. They allow you to test your integration without making actual charges or payments. Sandboxes simulate creating real objects without affecting actual transactions or moving real money. You can access your sandboxes using the account picker or on the Sandboxes page in the Dashboard. We recommend using our quality assurance (QA) testing use cases and importing our Postman collection to help you in the testing process.

Testing environments

In a sandbox, you can charge test credit cards and create test products and prices. Sandboxes let you simulate transactions to make sure that your integration works correctly. This helps identify bugs or errors in your Stripe implementation before you go live with actual payments.

After you create a Stripe account, Stripe places you in a sandbox. You can find a set of test API keys on the Stripe Dashboard home page or the API keys page. You can use these API keys to create and retrieve simulated data by making requests to the Stripe API.

To start accepting real payments, you need to set up your Stripe account, exit your sandbox with the account picker, and use the live API keys in your integration. Store live secret keys in a secrets vault or environment variables. Don’t store keys in source code or configuration files checked into version control. For more information, see Best practices for managing secret API keys.

Compare sandboxes

Your Stripe account includes a test mode sandbox and the ability to create additional sandboxes. Although test mode is a sandbox, it differs from the general sandboxes that you create. Understanding these differences can help you build your testing strategy.

Sandboxes versus live mode

All Stripe API requests occur in either a sandbox or live mode. API objects in one mode aren’t accessible to the other. For example, a test product object can’t be part of a live mode payment.

Being in a sandbox in the Dashboard doesn’t affect your integration code. Your test and live mode API keys affect the behavior of your code.

Create an additional sandbox

To create and set up an additional sandbox in the Dashboard:

Create the sandbox

1. Go to the Sandboxes page in the Dashboard.
2. Click Create in the top right.

Manage access

New sandboxes are private by default and don’t automatically give access to other team members. You can grant access to all team members:

1. Go to the Sandboxes page in the Dashboard.
2. Click the overflow menu () for the sandbox.
3. Select Change access.

You can manage individual-level access in any of these ways:

• Grant access to a specific sandbox.
• Grant testing-only access.
• Grant access to all sandboxes.

Get your sandbox credentials

Use these credentials to connect your integration to the sandbox. Save them where your team can access them for testing.

1. Copy the test API keys for the sandbox.
2. Copy the sandbox account ID.

Update test environment

You can update any references that depend on test data you created earlier.

1. Set up any resources you need for testing, such as products, customers, subscriptions, and payment methods.
2. Update any part of your testing processes that depends on specific test object IDs. This changes when you create new objects in a sandbox.

(Optional) Set up simulations

Set up simulations to test your Billing integration. Simulations let you move time forward in the sandbox so resources such as subscriptions change state and trigger webhook events.

Test card numbers

Stripe provides a set of test card numbers that you can use to simulate various payment scenarios. You can use these test card numbers to create simulated payments in sandboxes without processing actual payments or charges.

When you use test card numbers, you can enter any expiration date in the future and any three-digit CVC code to simulate a successful payment. If you want to simulate a failed payment, you can use specific test card numbers and CVC codes provided by Stripe.

Test card numbers are only valid in sandboxes. Don’t use them for real payments.

Delete test data

To delete all of your test data from your Stripe account, complete the following steps:

1. Log in to the Dashboard using your existing Stripe account.
2. While in your sandbox, click Developers > Overview.
3. Under Test data, click Review test data. The dialog gives you a list of all of your existing test data objects.
4. Click Delete test data to initiate the deletion process. You can’t undo the deletion of your test data.

Sandboxes are temporarily unusable while the deletion process occurs.

Test email

By default, Stripe doesn’t email customers in sandboxes. For example, paying an invoice in a sandbox doesn’t send a receipt email to the customer. Invoices finalized through the API in sandboxes also don’t send a receipt email to the customer.

If you want Stripe to email customers in a sandbox, you can do the following in the Dashboard:

1. Create and manually send an invoice to a specific customer.
2. Manually send a receipt for a paid invoice.

To verify emails for invoices and receipts, set the email address for your Team on the Customer object or receipt_email attribute on the PaymentIntent.

Testing use cases

The following table contains quality assurance (QA) testing use cases:

{
  ...
  "capture_method": "manual",
  ...
  "status": "requires_capture",
  ...
}

{
    ...
    "status": "succeeded",
    ...
  }

{
  "error": {
    "charge": "ch_uvr4nz79tcofOHUp",
    "code": "card_declined",
    "decline_code": "<<REASON HERE>>",
    "doc_url": "https://docs.stripe.com/error-codes#card-declined",
    "message": "Your card was declined.",
    "type": "card_error"
  }
}

{
  "object": {
    "id": "du_SBB5UsnW3fkJ5ReB",
    "object": "dispute",
    "charge_id": "ch_kUX6ruhYQuSMMFkN",
    ...
    "status": "needs_response"
  }
}

{
  "object": {
    "id": "du_KUnE3upSMfO5P11d",
    "object": "dispute",
    "charge_id": "ch_GEunRZcwVhVkHTE6",
    ...
    "is_charge_refundable": true,
    ...
    "status": "warning_needs_response"
  }
}

{
  "object": {
    "id": "du_6IERkLd4HIqN6tJH",
    "object": "dispute",
    "charge_id": "ch_y8U6unvF7NHiezYL",
    ...
    "status": "won"
  }
}

{
  "object": {
    "id": "du_SuJoYsOHQztUvkKb",
    "object": "dispute",
    "charge_id": "ch_RstP0piORhUfIx1t",
    ...
    "status": "lost"
  }
}

{
  "object": {
    "id": "du_x7rKsYJkwtSjwUyS",
    "object": "dispute",
    "charge_id": "ch_Wqj3pWmstElzFIN2",
    ...
    "status": "warning_closed"
  }
}

{
  "object": {
    "id": "du_MSrSJa3NdiIfuM5r",
    "object": "dispute",
    "charge_id": "ch_xLstuhduSX3d65ts",
    ...
    "status": "needs_response"
  }
}

{
  "id": "re_T0R48Ox2hz2tQ0DS",
  "object": "refund",
  "amount": "<<FULL AMOUNT>>",
  "charge": "ch_qNqwiEDooG8l8nLb",
  ...
  "payment_intent": "pi_HGSeX8mvmraKOWGw", // if you're using PaymentIntents
  ...
  "status": "succeeded"
}

{
  "id": "re_Lw1keHtmoV6Sl0yI",
  "object": "refund",
  "amount": "<<PARTIAL AMOUNT>>",
  "charge": "ch_Lmgfu9j4VhTFx1ev",
  ...
  "payment_intent": "pi_UMRPtEyhfVZ4inDp", // if you're using PaymentIntents
  ...
  "status": "succeeded"
}

Stripe’s Postman collection

Postman is a widely-used API development tool. To help integrate Stripe, we provide a Payments-specific Postman collection with the tools you need to test the server-side component of your integration.

Import the collection

To begin, you need to access the Postman app. You can use either the browser or desktop version. After launching the app, import the collection.

To start this process on the web, press the Import button at the top-left corner, followed by the Link option. Insert the Payments collection link. If you’re using the Postman desktop app, click File > Import. After successfully importing, the collection appears under Collections.

Use the collection

To use the collection, go to the collection you just imported and click Variables. Copy your Stripe sandbox secret key from the Stripe Dashboard, and paste it into the Initial Value field of the secret_key row. After you complete this step, you can begin making requests.

During collection runtime, scripts populate other variables. For example, when creating a customer, price, charge or PaymentIntent, the system saves that ID through a script in the collection, making it accessible for later requests, such as issuing a refund.