Skip to main content

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 modeLive mode
Key prefixsk_test_, pk_test_sk_live_, pk_live_
ObjectsSeparate from live dataProduction records
Money movementSimulatedReal
Dashboard bannerOrange test-mode badgeNo 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 numberOutcomeError code
4242 4242 4242 4242Charge succeeds.None
4000 0025 0000 3155The issuer requires 3D Secure authentication.Authentication flow
4000 0000 0000 9995Decline for insufficient funds.insufficient_funds
4000 0000 0000 0002Generic decline.card_declined
4000 0000 0000 0069Decline for an expired card.expired_card
4000 0000 0000 0127Decline for an incorrect CVC.incorrect_cvc
4000 0000 0000 0119Fail 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.

  1. Success. Confirm with 4242 4242 4242 4242 and verify the PaymentIntent reaches succeeded.
  2. Soft decline. Confirm with 4000 0000 0000 9995 and verify the client offers a retry with another card.
  3. Authentication. Confirm with 4000 0025 0000 3155 and verify the client completes the challenge.
  4. 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.

OperationEffect
Create a test clockStarts a simulated timeline at a fixed time.
Attach a customerBinds the customer to that timeline.
Advance the clockTriggers 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.

warning

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​

  1. Replace every test key with a live key in the production secret store.
  2. Confirm the account default API version matches the one you tested.
  3. Register the production webhook endpoint and verify the signing secret.
  4. Run one low-value live charge and one refund.
  5. Confirm the payout schedule and the bank account on file.
  6. Turn on alerting for 5xx responses and for failed webhooks.

Next steps​