Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
Testing
    Test your integration
    Testing use cases
    Sandboxes
    Test Apple Pay and Google Pay rendering
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuilding with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsTesting

Testing use cases

Learn how to test your integration.

Copy page

Stripe’s testing environments, test mode and Sandboxes, allow you to test your integration without making actual charges or payments. These environments simulate creating real objects without affecting actual transactions or moving real money. We recommend using our quality assurance (QA) testing use cases, and importing our Postman collection to aid you in the testing process.

Testing environments

In a testing environment, you can charge test credit cards and create test products and prices. These environments let you simulate transactions to make sure that your integration works correctly. This feature helps to identify any bugs or errors in your Stripe implementation before you go live with actual payments. Learn how to decide between using test mode and Sandboxes.

After you create a Stripe account, you can find a set of test API keys in the Stripe Dashboard. 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 activate your account, exit your testing environment using the account picker, and use the live API keys in your integration. Stripe provides a number of resources for testing your integration.

Impact on live mode when using test mode

If you change settings in the Dashboard while in test mode, you might also change them in live mode. Many Dashboard pages have a white notification box and disable live mode settings while in test mode. In this case, any settings still enabled are safe to use. If you don’t see a white callout, assume any changes made in test mode affect live mode settings (unless you see an orange or blue test data banner).

Compare testing environments

Test mode and Sandboxes are testing environments that simulate creating real objects without the risk of affecting real transactions or moving actual money. Understanding when to use each can help you build your testing strategy.

We recommend using Sandboxes for your testing needs because they offer additional functionality and greater flexibility compared to test mode. By transitioning to Sandboxes, you can enhance your testing capabilities with multiple environments, granular access control, and isolated settings, allowing you to build a more robust and comprehensive testing strategy.

Differences in functionality between test mode and Sandboxes

View the table below to understand the differences and choose the most suitable environment for your needs.

Test modeSandboxes
Number of environmentsUse one environmentUse up to five environments
Access controlGrant all users with roles the same roles and access.Exercise granular control over access. Only admins automatically have access. Invite users to sandboxes only, without access to live mode.
SettingsShare settings between live mode and test mode. You can’t test many settings independently.Isolate settings completely for each sandbox. Copy settings from live mode at creation time, and test independently from your live integration.
Product limitationsYou can’t test IC+ pricing in test mode.You can’t test IC+ pricing in a sandbox.
Version supportSupports V1 onlySupports V1 and V2 (including products such as Usage-based billing and Event Destinations).
Rate limitsMaintain consistent rate limits.Maintain consistent rate limits.
Test card numbersUse the same test card numbers.Use the same test card numbers.

Transition from test mode to Sandboxes

To transition from test mode to Sandboxes in the Dashboard:

  1. Create a sandbox, then invite the users who need access to it.
    • When you grant a team member the Sandbox User role, you’re giving them access to create sandboxes associated with your live business account and delete sandboxes they’ve created. Unlike test mode, where all users had automatic access, only those with the Sandbox User role, Admin roles, Developer role, or Sandbox Admin role can access sandboxes.
  2. Obtain new test API keys and your account ID for your sandbox.
  3. Set up relevant testing data such as test products, customers, subscriptions, and payment methods.
    • (Optional) Set up test clocks, which help you test your Billing integration to make sure it behaves as expected. When you use test clocks, you simulate the forward movement of time in the sandbox, causing Billing resources such as Subscriptions to change state and trigger webhook events. This allows you to see how your integration handles scenarios, such as a payment failure for a quarterly or annual renewal, without waiting extended periods.
  4. Update any part of your testing processes that depends on specific test object IDs. This changes when you create new objects in a sandbox.

Testing environments versus live mode

All Stripe API requests occur in either testing environments 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.

Type When to useObjectsHow to useConsiderations
sandboxesUse a sandbox, and its associated test API keys, as you build your integration. In a sandbox, card networks and payment providers don’t process payments.API calls return simulated objects. For example, you can retrieve and use test account, payment, customer, charge, refund, transfer, balance, and subscription objects.Use test credit cards and accounts. You can’t accept real payment methods or work with real accounts.Identity doesn’t perform any verification checks. Also, Connect account objects don’t return sensitive fields.
live modeUse live mode, and its associated live API keys, when you’re ready to launch your integration and accept real money. In live mode, card networks and payment providers do process payments.API calls return real objects. For example, you can retrieve and use real account, payment, customer, charge, refund, transfer, balance, and subscription objects.Accept real credit cards and work with customer accounts. You can accept actual payment authorizations, charges, and captures for credit cards and accounts.Disputes have a more nuanced flow and a simpler testing process. Also, some payment methods have a more nuanced flow and require more steps.

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

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 testing environments 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 testing environments. 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 testing environments, 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.

Testing environments are temporarily unusable while the deletion process occurs.

Note

You must manually delete Meters because the object isn’t supported by the automated test data deletion process.

Test email

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

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

  • Create and manually send an invoice to a specific customer.
  • 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:

Use caseAction
Charge success (capturing immediately)
  • No error.
  • The charge appears as Succeeded in the Dashboard under Payments.
  • Stripe captures the charge.
PaymentIntent authorization success (capturing funds for later)
{ ... "capture_method": "manual", ... "status": "requires_capture", ... }
PaymentIntent capture success (capturing immediately or capturing funds for later)
{ ... "status": "succeeded", ... }
Charge failThe charge appears as Failed in the Dashboard under Payments.
{ "error": { "charge": "ch_U7w20plbfiIrj40j", "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" } }
Radar blockNo matter which version of Radar you use, it might block a charge due to high risk or a rule. The response is the same as what you get when a charge fails.
Charge disputed
  • The charge appears as Disputed in the Dashboard under Payments.
  • Stripe debits the charge amount plus the dispute fee from the balance, creates a Dispute object along with its associated charge.dispute.created event.
{ "object": { "id": "du_qyzuG7WFsPfeIiCY", "object": "dispute", "charge_id": "ch_dzLgtllJvCihOOoM", ... "status": "needs_response" } }

Charge inquiry opened

Inquiries are similar to disputes, with three key distinctions: no funds are withdrawn unless we elevate an inquiry to a dispute, they remain refundable until disputed, and have a different set of statuses. In this case, Stripe fires a charge.dispute.created event.

{ "object": { "id": "du_cmeQlX2ehtYxZmG3", "object": "dispute", "charge_id": "ch_Fg0XGfy8aXZtpc4U", ... "is_charge_refundable": true, ... "status": "warning_needs_response" } }

Dispute won

  • When a customer wins a dispute, the funds of the original charge are restored to the account, less the dispute fee.
  • Stripe updates the existing Dispute object, and fires a charge.dispute.closed event.
{ "object": { "id": "du_c41jvh7kzMBTT7P7", "object": "dispute", "charge_id": "ch_2ho1nVLaJcA8gNsm", ... "status": "won" } }

Dispute lost

When a customer loses a dispute, Stripe updates the existing Dispute object, and fires a charge.dispute.closed event.

{ "object": { "id": "du_k8IPYXs1TvDfiQE4", "object": "dispute", "charge_id": "ch_tvD8ywppATqOE1YO", ... "status": "lost" } }

Inquiry won

When you win an inquiry, your balance remains the same, as no funds were removed when you initially opened the inquiry. Stripe updates the existing Dispute object, and fires a charge.dispute.closed event.

{ "object": { "id": "du_6bcbi5Tnfd7iEcxa", "object": "dispute", "charge_id": "ch_YFD6c1nEnGRIVJWo", ... "status": "warning_closed" } }

Inquiry lost

  • When you lose an inquiry, it escalates to a dispute.
  • When it escalates to a dispute, its status changes with a charge.dispute.updated event, and funds are withdrawn in a charge.dispute.funds_withdrawn event:
{ "object": { "id": "du_gzU5m7EtwHWkDCrS", "object": "dispute", "charge_id": "ch_Gd8Y8wZGwZWQgvjo", ... "status": "needs_response" } }

Charge refunded

The charge appears as Refunded in the Dashboard under Payments.

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

Charge partially refunded

  • The charge appears as Refunded in the Dashboard under Payments.
  • The refund amount is different from the charge amount, and you can still dispute partially-refunded charges.
{ "id": "re_M8StgJSpU58OB7IL", "object": "refund", "amount": "<<PARTIAL AMOUNT>>", "charge": "ch_sC3ZLIn5Y3NeDtC3", ... "payment_intent": "pi_7FeZ4mvv4OkDLPSf", // if you are using PaymentIntents ... "status": "succeeded" }
Account balance goes negativeMake sure to test for a negative balance on Stripe and verify that your bank accounts can accept debits from us.
Successful payoutIf you enable webhooks for a successful payout (recommended), test your handling of the event.
Failed payoutIf you enable webhooks for a failed payout (recommended), test your handling of the event.

Stripe’s Postman collection

Postman is a widely-used API development tool. To make integrating Stripe easier, 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.

The Import dialog

The import dialog

Use the collection

To use the collection, navigate to the collection you just imported and click Variables. Copy your testmode Stripe secret key from the Stripe Dashboard, and paste it into the Initial Value field. After you complete this step, you’re ready to begin making requests.

Other variables are populated by scripts during the runtime of the collection. For example, when creating a customer, price, charge or PaymentIntent, the system saves that ID through a script in the collection, which is then accessible for later requests, like issuing a refund.

The Variables Tab for the Collection

Add a secret key to a Postman collection

See also

  • Test your integration
  • Sandboxes
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc
Related Guides
Testing
API keys