Upgrading to MockCard 2.0
POST /api/v1/generate, you probably don't need to change any code. This page lists exactly what changed.In short
| If you… | Do this |
|---|---|
call /api/v1/generate with an API key | Nothing. Same request, same response, same webhooks, same key. |
| use the website or dashboard | Sign in again once with your email. Your account, key and usage are kept. |
| parse error codes from the audit endpoints | Replace the four renamed codes (table). |
used the /simulation page or /api/simulation/* | Move to chaos runs (guide). Those endpoints are gone. |
| lost your API key | Create a new one in the dashboard and revoke the old one. Keys can no longer be displayed again. |
What's new
| Feature | What it does | Plan |
|---|---|---|
| Chaos runs | Duplicate, late, missing and abandoned-payment webhooks delivered to your handler, scored out of 100. Pull mode for CI, push mode for staging. Reference | Pro · Agency |
| GitHub Action | Runs the scenarios in your workflow and fails the build below a score. Setup | Pro · Agency |
| SDKs | Node, Next.js, PHP, Laravel, Symfony, Python, Go, Ruby and Rails, plus a WooCommerce plugin. Outcome assertions: “fulfilled exactly once”, not just “answered 200”. Install | Pro · Agency |
| Native signing | Store your gateway's test-mode secret on a project and events arrive with a real Stripe-Signature or X-Razorpay-Signature, so your unchanged verification code is tested too. | Pro · Agency |
| Production probes | A signed probe your handler recognises and skips, which proves production is reachable and guarded without creating orders. How | Pro · Agency |
| Monitors | Hourly, 6-hourly or daily checks of staging and production, with email and Slack alerts when they break and recover, and a weekly digest. | Pro · Agency |
| Run history | Every run with its commit, branch, score and checks, in the dashboard and the API. | Pro · Agency |
| Agency features | Up to 25 client projects, 5 team seats, and white-label client reports with share links. | Agency |
| Key scopes | Separate ci keys for pipelines and account keys for management. Several keys per account, each revocable. | All |
| OpenAPI spec | The full API at /openapi.yaml. | All |
What changed
API keys are hashed
Keys are now stored only as SHA-256 hashes. Your existing key keeps working; it was converted in place and has full account scope. The dashboard now shows only its prefix (mc_3f9a1c2…), and GET /api/keys/meno longer returns it. If you don't have it stored anywhere, create a new key and revoke the old one. For CI, we recommend a new ci key instead of your account key.
Website sign-in uses sessions
The website used to keep your API key in a cookie. It now uses a session (30 days), so everyone is signed out once on upgrade. Sign in again with your email code. Sign-in codes now lock after 5 wrong attempts.
Plans
| Plan | Price (USD) | Calls | New in 2.0 |
|---|---|---|---|
| Anonymous | Free | 5 in total | Unchanged |
| Free | Free | 50 / month | Unchanged allowance; projects, runs and monitors need Pro or Agency |
| Pro | $24.99/mo or $249/yr | 2,000 / month | Runs, CI, 3 monitors, 3 projects; more calls than 1.x Pro |
| Agency | $74.99/mo or $749/yr | 10,000 / month | New plan for agencies |
Features that were “Pro only” in 1.x (chaos scenarios, simulate_race, webhook delivery, resilience audits) are available on both Pro and Agency. Usage now also counts runs, “run now” and manual probes; scheduled monitor runs are free. Yearly billing is new.
One error format everywhere
Every endpoint now answers errors with { "error": { "code", "message" } }. Generate already did; a few audit codes were renamed (next section).
Removed
- The
/simulationpage andPOST /api/simulation/run,GET /api/simulation/polland/api/simulation/webhook. Chaos runs replace them, can be scripted, and are stored in your history.
Error code changes
| 1.x code | 2.0 code | HTTP | When |
|---|---|---|---|
invalid_json | invalid_request | 400 | Body isn't valid JSON (audit endpoints) |
validation_error | invalid_request | 422 | Invalid field (audit endpoints) |
invalid_webhook_url | invalid_request | 422 | Private, internal or unresolvable webhook URL |
auth_error | auth_required | 401 | Endpoint needs a key or a signed-in session |
New codes for new features (insufficient_scope, agency_required, project_limit_reached, domain_not_verified and others) are listed in the API reference. Unchanged: invalid_request, invalid_api_key, pro_required, rate_limit_exceeded, not_found, internal_error and all simulated gateway codes.
What stayed the same
POST /api/v1/generate: same fields, defaults, statuses and response shape.- Every scenario, card brand and BIN range.
- Stripe and Razorpay webhook payloads,
X-MockCard-Signature/X-Razorpay-Signaturewith the MockCard webhook secret, and the retry schedule (immediate, +2 s, +4 s). - The
X-Api-Keyheader, and the audit endpoint paths and response bodies. - Test-card pages, the Playground, the Chaos Simulator and the public health check.
Upgrade checklist
- Sign in to the dashboard again with your email.
- Make sure your API key is stored somewhere safe (secret manager, CI secrets). If not, create a new one and revoke the old one.
- If you parse audit error codes, replace
invalid_json,validation_error,invalid_webhook_urlandauth_error. - If you used
/api/simulation/*, follow the CI guide instead. - Optional, Pro or Agency: create a project, store your test-mode webhook secret on it, create a
cikey, and add the Action or an SDK test. - Optional: deploy the probe guard and add a production monitor.
Need a hand?
Tell us what you're migrating through the contact form.
FAQ
Will my 1.x integration break on upgrade day?
Not if it calls /api/v1/generate: requests, responses and webhooks are unchanged and your key keeps working. Only the four renamed audit error codes and the removed simulation endpoints need changes.
Do the SDKs work on the Free plan?
The probe guard works on any plan (it's local code). Runs need Pro or Agency, so the SDK chaos runner returns pro_required on Free.
Is it safe to point monitors at production?
Production monitors only send a signed probe, and only after your domain is verified and your handler has acknowledged one probe. A handler without the guard never gets scheduled traffic. See Production probes.
Why does MockCard want my gateway secret?
It doesn't need it. Without one, events are signed with MockCard's own key. With your test-modesecret, events are signed exactly as your gateway signs them, so the run also tests your signature check. Never store a live secret. Secrets are encrypted at rest and can't be read back.