Use PSP-provided test card numbers for different scenarios: most PSPs publish specific PANs that simulate successful charges, declines, 3DS challenges, insufficient funds, and network errors — use these rather than real cards in all non-production environments.
For time-dependent flows (subscription renewals, trial expirations, mandate notice periods), use test clocks where available (Stripe's Test Clocks API: POST /v1/test_helpers/test_clocks) to advance time programmatically in the test environment without waiting for real time to pass.
Isolate your sandbox credentials from production credentials using environment variables; assert at application startup in non-production environments that the API key prefix or domain matches the expected sandbox value — this prevents accidental production charges in CI.
Configure your webhook handler to accept test webhook events from the PSP's test environment; use the PSP's CLI or dashboard 'trigger' feature to fire specific webhook events on demand (e.g., stripe trigger payment_intent.succeeded) rather than relying on real payment flows in CI.
Write integration tests that cover the full payment lifecycle: create payment intent → confirm → capture → refund, and the failure path: create → confirm → decline → retry with new method; run these against the sandbox in CI on every pull request.
Add a canary test that makes a real API call to the sandbox (with a tiny amount like $0.50 using a test card) in your CI pipeline to catch credential rotation issues or PSP sandbox outages before they affect production.
Known gotchas
Sandbox environments at most PSPs are eventually consistent and occasionally unreliable — flaky sandbox responses can cause false CI failures; implement a retry policy specifically for sandbox calls in CI and tag test failures from sandbox outages separately from real code failures.
Test clocks in Stripe are isolated per clock object — subscriptions, customers, and payment methods must all be created under the same test clock to advance time correctly; mixing test-clock-scoped and non-scoped objects produces unpredictable results.
Simulator card numbers for 3DS testing often require specific handling in the test environment (e.g., Stripe's 4000002500003155 always requires authentication) — ensure your test environment can complete the 3DS challenge flow, either via a headless browser or the PSP's test authentication endpoint, or the test will hang waiting for user interaction.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp