Skip to main content
Every integration starts in test mode. Test mode is a complete, isolated copy of the API: you build and verify the full flow against test keys, with no real money and no real cards. Going live is the deliberate switch to live keys once the flow works end to end.

​
Test mode and live mode

Each API key carries its mode in its name. The mode segment — test or live — determines which dataset the request reads and writes: Every object the API returns carries a livemode boolean, and so does every webhook event. Test-mode objects have "livemode": false; live-mode objects have "livemode": true. A test key can never see, mutate, or charge live data, and the reverse holds too.
Examples use a placeholder secret key, sk_v1_test_.... Your real keys share this shape — the test or live mode segment is what sets the environment. Copy them from the dashboard.

​
Test with a sandbox card

In test mode, tokenize this card from your client-side form to produce a payment_token: Use it to exercise the real flow — create a checkout session or payment intent, confirm it, and watch the resulting webhook arrive — exactly as you will in production. Test both the approval path and a decline so your error handling is exercised before real buyers hit it.

​
Go-live checklist

1

Prove the flow in test mode

Run your full integration against test keys: collect a payment, verify the result from your backend (not just the browser redirect), and confirm your webhook endpoint receives and verifies the event. Exercise a decline and a retry with the same Idempotency-Key.
2

Activate your account for live payments

Live processing requires your account’s payment capability to be approved and activated. Complete activation before switching keys — a live key cannot charge until the capability is active.
3

Switch to live keys

Replace your test secret key with your live secret key (sk_v1_live_…) in your server configuration, and your test publishable key with the live publishable key in your client. Keep live keys in your secret manager — never in source control or browser code.
4

Register live webhook endpoints

Webhook endpoints are mode-scoped: a test-mode endpoint only receives test events. Create your endpoints again with a live key, and store the new whsec_… signing secret each one returns — it is shown only once.
5

Verify with a real transaction

Run one real, low-value payment with a live key and a real card, confirm it settles, then refund it. This proves your live keys, payment setup, and webhook delivery all work together before you open the flow to buyers.

​
What changes between test and live

Most behavior is identical by design — that is the point of test mode. A few things differ:
Test and live data never mix. IDs created in test mode (cus_…, pi_…, sub_…) do not exist in live mode. Re-create the objects your integration needs — customers, products, prices, payment links — with a live key, or create them on first use in production.

​
Operational guidance

  • Keep test and live keys in separate configuration. A live key in a staging environment, or a test key in production, is the most common go-live mistake.
  • Register live webhook endpoints and verify a live signature before launch. A missing live endpoint means your fulfillment never fires for real orders.
  • Move idempotency keys, decline handling, and webhook verification into production unchanged — they were the point of building in test mode. Don’t simplify them for launch.
  • Retrieve the PaymentIntent or checkout session from your backend before fulfilling a live order. Do not rely on the browser redirect.
  • After go-live, watch payment_intent.payment_failed and invoice.payment_failed events to catch real-world declines you didn’t see in the sandbox.