Test mode and test cards
Test mode runs the full API against a separate data set. Charges succeed, balances settle, and payouts complete without moving real money. The response shapes match live mode.
Separate the environments
| Test mode | Live mode | |
|---|---|---|
| Key prefix | sk_test_, pk_test_ | sk_live_, pk_live_ |
| Objects | Separate from live data | Production records |
| Money movement | Simulated | Real |
| Dashboard banner | Orange test-mode badge | No badge |
Objects never cross the boundary. A test customer doesn't exist for a live key, and a live charge is invisible to a test key. A 404 on an object you just created usually means the key and the object belong to different modes.
Trigger an outcome with a test card
Stripe reserves card numbers that produce a specific result. Use any future expiry date and any three-digit card verification code, or CVC, unless the table says otherwise.
| Card number | Outcome | Error code |
|---|---|---|
4242 4242 4242 4242 | Charge succeeds. | None |
4000 0025 0000 3155 | The issuer requires 3D Secure authentication. | Authentication flow |
4000 0000 0000 9995 | Decline for insufficient funds. | insufficient_funds |
4000 0000 0000 0002 | Generic decline. | card_declined |
4000 0000 0000 0069 | Decline for an expired card. | expired_card |
4000 0000 0000 0127 | Decline for an incorrect CVC. | incorrect_cvc |
4000 0000 0000 0119 | Fail while processing. | processing_error |
A decline response also carries decline_code, which your client should map to its own copy. See Errors and retries for the mapping table.
curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_SECRET_KEY:" \
-d "amount=2120" \
-d "currency=usd" \
-d "payment_method=pm_card_visa" \
-d "confirm=true"
Stripe publishes test payment method IDs such as pm_card_visa, which skip card entry in a server-only test.
Run the four paths
A checkout integration needs coverage for four outcomes before it ships.
- Success. Confirm with
4242 4242 4242 4242and verify the PaymentIntent reachessucceeded. - Soft decline. Confirm with
4000 0000 0000 9995and verify the client offers a retry with another card. - Authentication. Confirm with
4000 0025 0000 3155and verify the client completes the challenge. - Duplicate protection. Replay a confirm call with the same idempotency key and verify one charge exists.
Inspect the result
Test data behaves like production data. Read the balance, list the charges, and replay a webhook to check each path.
curl -s https://api.stripe.com/v1/charges -u "$STRIPE_SECRET_KEY:" | jq '.data[] | {id, amount, status}'
Use the request log in the Dashboard to confirm the exact payload. The request_log_url in an error envelope opens the same entry.
Advance time with test clocks
Subscription tests depend on time. A test clock moves billing cycles forward without waiting for the calendar.
| Operation | Effect |
|---|---|
| Create a test clock | Starts a simulated timeline at a fixed time. |
| Attach a customer | Binds the customer to that timeline. |
| Advance the clock | Triggers renewals, trials endings, and invoice attempts on schedule. |
A test clock isolates its customers. Use one clock per test case so a shared customer doesn't receive two competing schedules.
Clear test data
Test mode accumulates objects. Periodically delete the records a test run created, or recreate the test account, so a demo doesn't show a hundred identical charges.
Deleting an object in test mode is permanent. Confirm that the key belongs to test mode before you run a cleanup script against a list of IDs.
Go-live checklist
- Replace every test key with a live key in the production secret store.
- Confirm the account default API version matches the one you tested.
- Register the production webhook endpoint and verify the signing secret.
- Run one low-value live charge and one refund.
- Confirm the payout schedule and the bank account on file.
- Turn on alerting for
5xxresponses and for failed webhooks.
Next steps
- Errors and retries for the decline handling behind each test card.
- Authentication and key management for the live key rollout.
- API versioning and upgrades to freeze the version you tested.