MockCard API documentation
Overview
MockCard is a REST API for testing what your payment code does when payments go wrong, without a gateway sandbox. It has two layers:
- Checks: generate Luhn-valid test cards for Visa, MasterCard, RuPay and Amex with any outcome (approval, decline, 3DS, timeout, limbo, latency) in Stripe or Razorpay wire format, and run a 5-probe webhook health check. Works without an account.
- Runs and monitoring Pro · Agency: chaos runs that deliver signed duplicate, missing, late and abandoned-payment webhooks to your handler in CI or on staging, outcome assertions through the SDKs, safe signed probes for production, scheduled monitors with alerts, and client reports for agencies.
| Property | Value |
|---|---|
| Base URL | https://www.mockcard.io |
| Format | JSON request and response bodies (application/json) |
| Authentication | Optional for checks, required for everything else: X-Api-Key header (see below) |
| Errors | Always { "error": { "code", "message" } }, see Error codes |
| Webhook signing | MockCard's HMAC-SHA256 by default; your gateway's own scheme when a project has your test secret |
| Spec | OpenAPI 3.1 (/openapi.yaml) |
Want to see it before you code?
The Playground fires a real request, shows the JSON response and the webhook event, all in your browser.
Authentication & API keys
Send your key in the X-Api-Key header. Keys look like mc_ followed by 48 hex characters. Get one by verifying your email on the dashboard: your first key is shown once at sign-up, and you can create more there or with POST /api/keys.
| Scope | Can do | Use it for |
|---|---|---|
| ci | Generate cards, run health checks, create runs and report results, read projects, runs and monitors. | CI secrets, test suites, the GitHub Action. Safe to hand to a pipeline. |
| account | Everything a ci key can, plus create and change projects, monitors, keys and team settings. | Scripts that manage your setup. Keep it out of CI. |
- Keys are stored as SHA-256 hashes. MockCard can't show a key again after creating it: store it when it's shown, and revoke and replace it if you lose it.
- A request that sends an
X-Api-Keythat doesn't match an active key fails with401 invalid_api_key. It is never quietly treated as anonymous. - A
cikey used for an account action fails with403 insufficient_scope. - The website uses a session cookie (30 days) instead of a key. Sessions always have account scope.
- The SDKs read
MOCKCARD_API_KEYfrom the environment when you don't pass a key.
Plans & usage limits
| Anonymous | Free | Pro | Agency | |
|---|---|---|---|---|
| Price (USD) | Free | Free | $24.99/mo · $249/yr | $74.99/mo · $749/yr |
| Metered calls | 5 in total | 50 / month | 2,000 / month | 10,000 / month |
| Chaos scenarios, webhook delivery, runs | — | — | Yes | Yes |
| Projects | — | — | 3 | 25 |
| Monitors | — | — | 3 | 25 |
| Team seats | — | 1 | 1 | 5 |
| Client reports | — | — | — | Yes |
What counts as a call: a successful POST /api/v1/generate (declines and timeouts are successful simulations and count too), a health check (POST /api/v1/audit/quick), creating a run, “run now” on a monitor, and a manual probe. Scheduled monitor runs, reading results, and requests rejected for bad input or a missing plan don't count. Usage resets on the 1st of each month (UTC). When it runs out you get 429 rate_limit_exceeded (or anonymous_limit_reached without a key).
Quick start
One POST request. The key is optional here: without one you get 5 anonymous calls in total, enough to try it.
curl -X POST https://www.mockcard.io/api/v1/generate \
-H "Content-Type: application/json" \
-H "X-Api-Key: $MOCKCARD_API_KEY" \
-d '{
"brand": "visa",
"scenario": "success",
"amount": 1000,
"currency": "inr"
}'Testing a whole webhook handler rather than one call? The SDKs and GitHub Action run every scenario against your app and check what it did.
POST /api/v1/generate
Returns a mock card and simulates the payment outcome. For decline and timeout scenarios the HTTP status is the gateway's (402, 504) and there's no cardfield. That's a successful simulation, not an API failure. On paid plans, if you pass a webhook_url, the signed event is delivered there after the response.
Request body (all fields optional)
| Field | Type | Default | Description |
|---|---|---|---|
| brand | string | visa | visa · mastercard · rupay · amex |
| scenario | string | success | See Test scenarios |
| gateway | string | stripe | stripe or razorpay: the wire format of the error body and webhook event |
| amount | integer | 1000 | Smallest currency unit (cents, paise). 1 to 100,000,000. |
| currency | string | inr | ISO 4217 code, 3 characters |
| webhook_url Pro · Agency | string | null | Where to POST the signed event. https:// (or http://localhost for local testing). Ignored on Free and anonymous calls, which still get a response. |
| simulate_race Pro · Agency | boolean | false | Deliver the event a second time ~1 s later with the same event id. Needs webhook_url. 402 pro_required on Free. |
| return_url | string | null | Where the mock 3DS challenge page sends the customer afterwards (3ds_challenge). https:// or a relative path. |
Response: 201 Created (success, limbo, latency)
{
"status": "success",
"payment_intent_id": "pi_mock_x7y8z9a0b1c2",
"scenario": "success",
"card": {
"brand": "visa",
"card_number": "4539578763621486",
"masked_number": "••••••••••••1486",
"expiry_month": "07",
"expiry_year": "2028",
"cvv": "382",
"cardholder_name": "PRIYA PATEL",
"luhn_valid": true
},
"webhook_event": {
"id": "evt_mock_a1b2c3d4e5f6",
"object": "event",
"type": "payment_intent.succeeded",
"created": 1741708800,
"livemode": false,
"data": {
"object": {
"id": "pi_mock_x7y8z9a0b1c2",
"object": "payment_intent",
"amount": 1000,
"currency": "inr",
"status": "succeeded",
"payment_method_details": {
"type": "card",
"card": { "brand": "visa", "last4": "1486", "exp_month": "07", "exp_year": "2028" }
}
}
},
"delivery": null
},
"log_id": 18342
}Response: 402 / 504 (decline, 3DS and timeout scenarios)
{
"error": {
"code": "card_declined",
"message": "Your card has insufficient funds.",
"decline_code": "insufficient_funds"
},
"webhook_event": {
"id": "evt_mock_d4e5f6g7h8i9",
"object": "event",
"type": "payment_intent.payment_failed",
"created": 1741708800,
"livemode": false,
"data": {
"object": {
"id": "pi_mock_j0k1l2m3n4o5",
"object": "payment_intent",
"amount": 1000,
"currency": "inr",
"status": "requires_payment_method",
"last_payment_error": {
"code": "card_declined",
"decline_code": "insufficient_funds",
"message": "Your card has insufficient funds.",
"type": "card_error"
}
}
},
"delivery": null
},
"log_id": 18342
}Top-level response fields
| Field | Type | Description |
|---|---|---|
payment_intent_id | string | Your transaction reference. pi_mock_… for Stripe, pay_mock_… for Razorpay. Matches the id inside the webhook event. |
log_id | integer | null | MockCard's log row. Pass it to GET /api/v1/delivery-status?id= to see whether the webhook was delivered. |
card | object | absent | Present on 201 responses only. See below. |
error | object | absent | Present on 402/504 outcomes. Shape depends on gateway (see Gateway simulation). |
webhook_event | object | absent | The event payload. Only returned to the website and anonymous calls. With an X-Api-Key it is omitted: the event goes to your webhook_url instead, the way a real gateway works. |
Card object
| Field | Type | Description |
|---|---|---|
| brand | string | Card network (visa · mastercard · rupay · amex) |
| card_number | string | Full 15- or 16-digit PAN, Luhn-valid |
| masked_number | string | PAN with all but the last 4 digits replaced by • |
| expiry_month | string | Two-digit month (01–12) |
| expiry_year | string | Four-digit year (current year + 1 to + 5) |
| cvv | string | 3-digit CVV (4-digit CID for Amex) |
| cardholder_name | string | Uppercase cardholder name |
| luhn_valid | boolean | Always true |
Card brands
BIN prefixes follow the official IIN ranges, and the Luhn check digit is computed, so every number passes real gateway format validation.
| Brand | Enum value | BIN prefixes | Card length |
|---|---|---|---|
| Visa | visa | 4 | 16 |
| MasterCard | mastercard | 51–55, 2221–2720 | 16 |
| RuPay | rupay | 60, 65, 81, 82 | 16 |
| Amex | amex | 34, 37 | 15 |
Test scenarios
Pass one of these as scenario. Event types shown are for gateway: stripe; see Gateway simulation for Razorpay.
Standard scenarios (every plan)
| Scenario | Enum value | HTTP | Stripe event type | Description |
|---|---|---|---|---|
| Success | success | 201 | payment_intent.succeeded | Approved; card returned |
| Insufficient funds | insufficient_funds | 402 | payment_intent.payment_failed | Declined: no funds |
| Do not honor | do_not_honor | 402 | payment_intent.payment_failed | Generic issuer decline |
| Expired card | expired_card | 402 | payment_intent.payment_failed | Card past its expiry date |
| Incorrect CVV | incorrect_cvv | 402 | payment_intent.payment_failed | Security code mismatch |
| 3DS challenge | 3ds_challenge | 402 | payment_intent.requires_action | Bank challenge required. The mock challenge page accepts 123456 and then fires payment_intent.succeeded. |
| Network timeout | network_timeout | 504 | payment_intent.payment_failed | 10 s gateway lag, then 504 |
Chaos scenarios Pro · Agency
The edge cases production systems fail on, which gateway sandboxes don't produce. On Free and anonymous calls they return 402 pro_required.
| Scenario | Enum value | HTTP | Stripe event type | Description |
|---|---|---|---|---|
| 3DS abandoned | 3ds_abandoned | 402 | payment_intent.canceled | Customer closes the 3DS window; the intent is cancelled |
| Limbo | limbo | 201 | payment_intent.succeeded | Captured and 201 returned, but the webhook is never delivered. Tests reconciliation. |
| Latency | latency | 201 | payment_intent.succeeded | Succeeds now; the webhook arrives 9 s later. Exposes timeout-then-retry double processing. |
Runs add one more scenario, duplicate: the same success event delivered twice at the same moment. See Chaos runs.
Gateway simulation
Add "gateway": "razorpay"to get the response and webhook in Razorpay's wire format: their error envelope, payment entity and signature header. No Razorpay account needed. The card object is the same for every gateway; only the event and error shapes change.
Stripe vs Razorpay at a glance
| Property | Stripe (default) | Razorpay |
|---|---|---|
| payment_intent_id prefix | pi_mock_… | pay_mock_… |
| Success event | payment_intent.succeeded | payment.captured |
| Failure event | payment_intent.payment_failed | payment.failed |
| 3DS event | payment_intent.requires_action | payment.authorized |
| Error envelope | error.code + decline_code | error.code + reason + source + step + metadata.payment_id |
| Signature (MockCard key) | X-MockCard-Signature: sha256=… | X-Razorpay-Signature: <hex> |
| Signature (your test secret, runs) | Stripe-Signature: t=…,v1=… | X-Razorpay-Signature: <hex> |
| Event header | X-MockCard-Event | X-Razorpay-Event-Type |
Razorpay error codes
| Scenario | code | reason | source | step |
|---|---|---|---|---|
| insufficient_funds | BAD_REQUEST_ERROR | insufficient_balance | customer | payment_authorization |
| do_not_honor | BAD_REQUEST_ERROR | card_declined | customer | payment_authorization |
| expired_card | BAD_REQUEST_ERROR | card_expired | customer | payment_initiation |
| incorrect_cvv | BAD_REQUEST_ERROR | incorrect_cvc | customer | payment_initiation |
| network_timeout | GATEWAY_ERROR | gateway_timeout | internal | payment_authorization |
| 3ds_abandoned | BAD_REQUEST_ERROR | authentication_failed | customer | payment_authentication |
Verifying Razorpay signatures
Razorpay signatures are plain HMAC-SHA256 hex with no sha256= prefix, in X-Razorpay-Signature.
import { createHmac } from "crypto";
// Razorpay uses plain HMAC-SHA256 hex — no "sha256=" prefix
function verifyRazorpayWebhook(
rawBody: string, // req.body as raw string (express.text() middleware)
signature: string, // X-Razorpay-Signature header
secret: string // your WEBHOOK_SECRET env var
): boolean {
const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
return expected === signature;
}
app.post("/webhook", express.text({ type: "*/*" }), (req, res) => {
const sig = req.headers["x-razorpay-signature"] as string;
if (!verifyRazorpayWebhook(req.body, sig, process.env.WEBHOOK_SECRET!)) {
return res.status(400).send("Invalid signature");
}
const event = JSON.parse(req.body);
const payment = event.payload.payment.entity;
if (event.event === "payment.captured") {
// fulfil order — payment.id is your transaction reference
await db.orders.fulfill(payment.id);
}
res.status(200).send("ok");
});Webhook events & signing
With a webhook_url on a paid plan, the event is POSTed in the background after the API responds, so it never slows your request down. In runs, MockCard plans the same events and either the SDK (pull) or MockCard (push) delivers them.
Event types
| Scenario | Event type | PaymentIntent status | Notes |
|---|---|---|---|
| success | payment_intent.succeeded | succeeded | payment_method_details.card has brand and last4 |
| insufficient_funds | payment_intent.payment_failed | requires_payment_method | last_payment_error.decline_code = insufficient_funds |
| do_not_honor | payment_intent.payment_failed | requires_payment_method | last_payment_error.decline_code = do_not_honor |
| expired_card | payment_intent.payment_failed | requires_payment_method | last_payment_error.decline_code = expired_card |
| incorrect_cvv | payment_intent.payment_failed | requires_payment_method | last_payment_error.decline_code = incorrect_cvc |
| 3ds_challenge | payment_intent.requires_action | requires_action | Not a decline: next_action.redirect_to_url present, last_payment_error null |
| 3ds_abandoned | payment_intent.canceled | canceled | Release the order and any reserved stock |
| network_timeout | payment_intent.payment_failed | requires_payment_method | last_payment_error.code = gateway_timeout, type = api_error |
Events from the same payment share one payment id. In a 3ds_challenge run, for example, the requires_action and the succeeded events carry the same pi_mock_…, so your handler can match them up.
Sample payloads: Stripe
// Headers
// X-MockCard-Event: payment_intent.succeeded
// X-MockCard-Signature: sha256=a3f9c12b8e1d…
{
"id": "evt_mock_a3f9c12b8e1d",
"type": "payment_intent.succeeded",
"created": 1741843200,
"data": {
"object": {
"id": "pi_mock_7b2e4d9a1c3f",
"object": "payment_intent",
"amount": 1000,
"currency": "inr",
"status": "succeeded",
"payment_method_details": {
"card": {
"brand": "visa",
"last4": "1486",
"exp_month": "07",
"exp_year": "2028"
}
},
"last_payment_error": null,
"next_action": null
}
}
}Sample payloads: Razorpay
All decline scenarios share one shape; only error_reason differs.
// Headers
// X-Razorpay-Event-Type: payment.captured
// X-Razorpay-Signature: a3f9c12b8e1d… (plain HMAC-SHA256 hex — no "sha256=" prefix)
{
"entity": "event",
"account_id": "acc_mock_f9e8d7c6b5a4",
"event": "payment.captured",
"contains": ["payment"],
"payload": {
"payment": {
"entity": {
"id": "pay_mock_7b2e4d9a1c3f",
"entity": "payment",
"amount": 1000,
"currency": "INR",
"status": "captured",
"method": "card",
"card": {
"id": "card_mock_x1y2z3a4b5c6",
"entity": "card",
"name": "PRIYA PATEL",
"network": "Visa",
"last4": "1486",
"expiry_month": "07",
"expiry_year": "2028"
}
}
}
},
"created_at": 1741843200
}Which signature you receive
| When | Stripe format | Razorpay format | Verify with |
|---|---|---|---|
Generate with webhook_url; runs for a project without a signing secret | X-MockCard-Signature: sha256=<hex> X-MockCard-Event: <type> | X-Razorpay-Signature: <hex> X-Razorpay-Event-Type: <type> | MockCard's webhook secret (below) |
| Runs and monitors for a project with your test-mode signing secret | Stripe-Signature: t=<unix>,v1=<hex> | X-Razorpay-Signature: <hex> X-Razorpay-Event-Type: <type> | Your unchanged Stripe or Razorpay library and test secret |
| Production probes | MockCard-Probe: 1 MockCard-Signature: t=<unix>,v1=<hex> | Same | The project's probe secret (Production probes) |
The recommended setup is to store your gateway's test-mode webhook secret on the project (Projects). Then your real verification code runs unchanged during chaos runs, and a broken signature check shows up as a failed run.
Verifying MockCard's own signature
Compute HMAC-SHA256 over the raw request body bytes with the MockCard webhook secret and compare it with X-MockCard-Signature, using a constant-time comparison.
import { createHmac } from "crypto";
// Call this BEFORE json.parse() — sign the raw body string, not the object
function verifyWebhook(
rawBody: string, // req.body as raw string (use express.text() middleware)
signature: string, // X-MockCard-Signature header
secret: string // your WEBHOOK_SECRET env var
): boolean {
const expected =
"sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
return expected === signature;
}
// Express.js example
app.post("/webhook", express.text({ type: "*/*" }), (req, res) => {
const sig = req.headers["x-mockcard-signature"] as string;
if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET!)) {
return res.status(400).send("Invalid signature");
}
const event = JSON.parse(req.body);
if (event.type === "payment_intent.succeeded") {
// fulfil order…
}
res.status(200).send("ok");
});Delivery and retries (generate)
| Attempt | Delay | Behaviour |
|---|---|---|
| 1 | immediate | First delivery (5 s timeout) |
| 2 | +2 s | On any 4xx/5xx, timeout or connection error |
| 3 | +4 s | Final attempt; the outcome is visible through delivery-status |
Deliveries never follow redirects and only go to public addresses. Private and internal hosts are refused. simulate_race: true sends an identical second delivery (same event id) about one second later. Your handler must deduplicate on the event id, for example with a unique constraint.
Chaos runs
A run sends a set of scenarios to your webhook handler and scores how it coped. Pro · Agency
| Mode | Who delivers | Use it for |
|---|---|---|
| pull | Your SDK or the GitHub Action, inside your CI job | CI. Your app runs on localhost, which MockCard can't reach, so MockCard returns signed deliveries and the SDK sends them, then reports results. The SDK can also check outcomes in your database. |
| push | MockCard | A public staging URL (target_url). MockCard delivers and scores the run itself; poll the run for the result. |
| probe | MockCard | Production. One signed probe that a guarded handler skips (Production probes). Created by monitors and the probe endpoint. |
| Endpoint | Access | Description |
|---|---|---|
POST/api/v1/runs | ci · account | Create a run. 201 with deliveries for pull, 202 for push. |
POST/api/v1/runs/{runId}/results | ci · account | Pull only. Report delivery results and assertions, once per run. Returns the scored run. |
GET/api/v1/runs/{runId} | ci · account | One run with score and every check. |
GET/api/v1/runs?project_id=&limit= | ci · account | Recent runs, newest first (limit 1–100, default 50). |
Create a run
| Field | Type | Description |
|---|---|---|
project_id | string, required | One of your projects. Its gateway and signing secret shape the events. |
mode | pull | push | Default pull. |
scenarios | string[] | Any of success, insufficient_funds, do_not_honor, expired_card, incorrect_cvv, 3ds_challenge, network_timeout, 3ds_abandoned, limbo, latency, duplicate. Default: success, insufficient_funds, 3ds_challenge, 3ds_abandoned, duplicate, latency, limbo. |
target_url | string | Push only, required there. A public https:// URL. |
time_scale | 0–1 | Pull only, default 0.2. Shrinks the waits (latency, 3DS) so CI stays fast. Push always uses real timings. |
trigger | ci | api | Shown in run history. The SDKs set ci when the CI environment variable is present. |
commit_sha | string | Up to 64 characters. Shown in run history. |
branch | string | Up to 200 characters. Shown in run history. |
curl -X POST https://www.mockcard.io/api/v1/runs \
-H "Content-Type: application/json" \
-H "X-Api-Key: $MOCKCARD_CI_KEY" \
-d '{
"project_id": "prj_3f9a1c2b7d4e5f60",
"mode": "pull",
"scenarios": ["success", "duplicate", "3ds_abandoned", "limbo"],
"time_scale": 0.2,
"trigger": "ci",
"commit_sha": "9c1d2e3",
"branch": "feature/refactor-webhooks"
}'{
"run": {
"id": "run_8b2f4c1d9e0a7b36",
"project_id": "prj_3f9a1c2b7d4e5f60",
"mode": "pull",
"status": "running",
"scenarios": ["success", "duplicate", "3ds_abandoned", "limbo"]
},
"deliveries": [
{
"id": "dlv_1",
"scenario": "success",
"at_ms": 0,
"group": null,
"event_type": "payment_intent.succeeded",
"probe": false,
"body": "{\"id\":\"evt_mock_…\",\"type\":\"payment_intent.succeeded\",…}",
"headers": { "Stripe-Signature": "t=1762300800,v1=5f0c…" }
},
{
"id": "dlv_2",
"scenario": "duplicate",
"at_ms": 0,
"group": "duplicate",
"event_type": "payment_intent.succeeded",
"probe": false,
"body": "…",
"headers": { "Stripe-Signature": "t=1762300800,v1=91ab…" }
}
],
"expectations": [
{ "scenario": "duplicate", "expectation": "Acknowledge both concurrent copies with 2xx and fulfil exactly once (idempotency)." }
]
}For each delivery, wait until at_ms after the start (deliveries with the same group go at the same moment, concurrently), then POST the exact body string with the given headers plus Content-Type: application/jsonto your handler. Don't re-serialise the body, or the signature won't match. Then report what happened:
curl -X POST https://www.mockcard.io/api/v1/runs/run_8b2f4c1d9e0a7b36/results \
-H "Content-Type: application/json" \
-H "X-Api-Key: $MOCKCARD_CI_KEY" \
-d '{
"deliveries": [
{ "delivery_id": "dlv_1", "status_code": 200, "duration_ms": 41 },
{ "delivery_id": "dlv_2", "status_code": 200, "duration_ms": 37 },
{ "delivery_id": "dlv_3", "status_code": 200, "duration_ms": 52 }
],
"assertions": [
{ "scenario": "duplicate", "name": "order fulfilled once", "passed": false,
"message": "fulfilled 2 times for one payment" }
]
}'Scoring
Every delivery is one check: it passes on a 2xx (and, for probes, the acknowledgement header). Every assertion your SDK reports is one more check. All checks weigh the same: the score is the percentage that passed, and the run is passed only when every check passed. A delivery with no reported result counts as failed. A handler can answer 200 to both copies of a duplicate and still fulfil the order twice, which is why the SDK assertions matter.
What each scenario expects
| Scenario | A correct handler… |
|---|---|
| success | Acknowledge with 2xx and fulfil the order once. |
| insufficient_funds | Acknowledge with 2xx and mark the payment failed; never fulfil. |
| do_not_honor | Acknowledge with 2xx and mark the payment failed; never fulfil. |
| expired_card | Acknowledge with 2xx and mark the payment failed; never fulfil. |
| incorrect_cvv | Acknowledge with 2xx and mark the payment failed; never fulfil. |
| 3ds_challenge | Acknowledge both events; keep the order pending on requires_action, fulfil on success. |
| network_timeout | Acknowledge with 2xx and mark the payment failed so the customer can retry. |
| 3ds_abandoned | Acknowledge both events; release the order and stock when the payment is canceled. |
| limbo | No webhook arrives. Never fulfil without confirmation; reconcile with the gateway instead. |
| latency | Acknowledge the late webhook without creating a second order for the client's retry. |
| duplicate | Acknowledge both concurrent copies with 2xx and fulfil exactly once (idempotency). |
Projects
A project is one app, or one client store for agencies. It holds the event format (Stripe or Razorpay), an optional test-mode signing secret, and the probe secret. Runs, monitors and reports belong to a project. Projects come with Pro (3) and Agency (25).
| Endpoint | Access | Description |
|---|---|---|
GET/api/v1/projects | ci · account | List projects. |
POST/api/v1/projects | account | Create: { name, gateway? }. The probe_secret is in this response only. |
GET/api/v1/projects/{projectId} | ci · account | One project. has_signing_secret says whether a secret is stored; the secret itself is never returned. |
PATCH/api/v1/projects/{projectId} | account | name, gateway, signing_secret (write-only; null removes it). |
DELETE/api/v1/projects/{projectId} | account | Delete the project with its runs and monitors. |
POST/api/v1/projects/{projectId}/probe-secret | account | Rotate the probe secret. The new one is shown once; update your production handler before the next probe. |
Only ever store a test-mode secret
signing_secret must be your gateway's test-mode webhook secret (Stripe whsec_…from a test-mode endpoint, or a Razorpay test webhook secret), never a live one. Secrets are encrypted at rest (AES-256-GCM) and can't be read back, by you or through the API.
Production probes
Real chaos events would create real orders in production, so MockCard never sends them there. Production monitoring sends one probe: a normal-looking success event with two extra headers.
| Header | Value |
|---|---|
MockCard-Probe | 1 |
MockCard-Signature | t=<unix seconds>,v1=<hex> where v1 = HMAC-SHA256(probe secret, "<t>.<raw body>") |
Your handler checks the signature before anything else, skips all processing, and answers 2xx with MockCard-Probe-Ack: skipped. A probe passes only when that header comes back, which proves the request reached your code and was skipped. Reject signatures older than 5 minutes. A forged probe header can only make your handler skip a request, never process one. Every SDK includes this guard (list); without an SDK it's a few lines:
import { createHmac, timingSafeEqual } from "crypto";
// Returns true for a genuine, recent MockCard production probe.
function isVerifiedProbe(headers: Headers, rawBody: string, secret: string): boolean {
if (headers.get("mockcard-probe") !== "1" || !secret) return false;
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers.get("mockcard-signature") ?? "");
if (!m) return false;
const [, t, v1] = m;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
export async function POST(req: Request) {
const raw = await req.text();
if (isVerifiedProbe(req.headers, raw, process.env.MOCKCARD_PROBE_SECRET ?? "")) {
// Skip ALL processing: no DB writes, no emails, no fulfilment.
return new Response("ok", { status: 200, headers: { "MockCard-Probe-Ack": "skipped" } });
}
// …normal Stripe / Razorpay signature check and handling
}| Endpoint | Access | Description |
|---|---|---|
POST/api/v1/projects/{projectId}/probe | ci · account | Send one probe to { url } now. Returns the run and acked: true|false. Counts as one call. |
Monitors
A monitor checks one URL on a schedule (every hour, 6 hours or day) and alerts you when it starts failing and when it recovers. Pro · Agency
| Environment | What it sends | Before it starts |
|---|---|---|
| staging | A push run with the monitor's scenarios (default: the standard run set) | Domain verified |
| production | One signed probe, nothing else | Domain verified and one acknowledged probe (POST …/run) |
curl -X POST https://www.mockcard.io/api/v1/monitors \
-H "Content-Type: application/json" \
-H "X-Api-Key: $MOCKCARD_ACCOUNT_KEY" \
-d '{
"project_id": "prj_3f9a1c2b7d4e5f60",
"url": "https://shop.example.com/api/webhooks/stripe",
"environment": "production",
"interval_minutes": 60,
"alert_email": true,
"slack_webhook_url": "https://hooks.slack.com/services/…"
}'
# 201 → { "monitor": { "id": "mon_…", "verified_at": null, … },
# "verification": {
# "dns": { "name": "_mockcard.shop.example.com", "type": "TXT", "value": "mockcard-verify=…" },
# "file": { "url": "https://shop.example.com/.well-known/mockcard-verify.txt", "content": "…" } } }Domain verification
MockCard only sends scheduled traffic to hosts you control. Add either the TXT record _mockcard.<host> with value mockcard-verify=<token>, or serve the token as plain text at https://<host>/.well-known/mockcard-verify.txt. Then call verify (or click Verify in the dashboard).
| Endpoint | Access | Description |
|---|---|---|
GET/api/v1/monitors | ci · account | List monitors. |
POST/api/v1/monitors | account | project_id, url, environment, interval_minutes (60 · 360 · 1440, default 1440), scenarios, alert_email, slack_webhook_url. Returns the verification instructions. |
GET/api/v1/monitors/{monitorId} | ci · account | One monitor with its verification instructions and last status. |
PATCH/api/v1/monitors/{monitorId} | account | Change interval_minutes, scenarios, alert_email, slack_webhook_url or paused. |
DELETE/api/v1/monitors/{monitorId} | account | Delete the monitor. |
POST/api/v1/monitors/{monitorId}/verify | account | Check the DNS record or file. Returns { verified, method }. |
POST/api/v1/monitors/{monitorId}/run | account | Run now. For production monitors, the first acknowledged probe enables the schedule. Counts as one call. |
Alertsgo by email (to the account's address) and to Slack when a monitor goes from passing to failing, and again when it recovers. You don't get one for every failed run. A weekly digest summarises every monitor. Scheduled runs don't use your monthly calls.
Health check & audits
| Endpoint | Access | Description |
|---|---|---|
POST/api/v1/audit/quick | anyone | The webhook health check: 5 probes at { webhook_url, gateway? }, scored out of 100, with a grade and a shareable share_token. One call. The URL is neither logged nor stored. |
POST/api/v1/audit/run | Pro · Agency | A 12-probe resilience audit. Returns 202 with a run_id; poll the next endpoint. |
GET/api/v1/audit/{runId} | Pro · Agency | One audit run with full probe results. |
GET/api/v1/audit/history | Pro · Agency | Your 20 most recent audits. |
GET/api/v1/delivery-status?id={log_id} | signed in | { pending: true } until a generate call's webhook delivery finishes, then delivered, status_code and delivered_at. |
POST/api/v1/webhook/retry | signed in | Re-deliver a stored event payload to a URL, signed with MockCard's key (one attempt). |
For continuous testing of a real handler, use runs. Audits test a URL from the outside; runs also check what your app did.
Keys, team & reports
| Endpoint | Access | Description |
|---|---|---|
GET/api/keys | account | Your keys: id, name, prefix, scope, created and last used. Never the full key. |
POST/api/keys | account | { name?, scope? }, scope ci by default. The full key is in this response only. |
DELETE/api/keys/{keyId} | account | Revoke a key. Requests using it fail immediately. |
GET/api/team | Agency owner | Members and seats: { used, limit } (5 seats including the owner). |
POST/api/team | Agency owner | Invite { email }. They sign in with their own email and share the account's plan, projects and usage. |
DELETE/api/team/{email} | Agency owner | Remove a teammate and sign them out. |
PATCH/api/account | owner | brand_name (1–80 characters) and brand_url (https://) for client reports; null clears them. |
GET/api/v1/projects/{projectId}/report | Agency | The white-label client report for a project, plus a signed share link (/r/…, valid 90 days) your client can open without an account. |
Error codes
Every error uses one envelope. code is stable and machine-readable. message is for humans and may change. Some errors add fields (for example plan and limit).
{
"error": {
"code": "rate_limit_exceeded",
"message": "Monthly limit of 2,000 calls reached. Upgrade at mockcard.io/pricing.",
"plan": "pro",
"limit": 2000
}
}Simulated gateway outcomes (generate)
These are the scenario you asked for, not failures of the API.
| code | decline_code | HTTP | Scenario |
|---|---|---|---|
| card_declined | insufficient_funds | 402 | insufficient_funds |
| card_declined | do_not_honor | 402 | do_not_honor |
| expired_card | expired_card | 402 | expired_card |
| incorrect_cvc | incorrect_cvc | 402 | incorrect_cvv |
| authentication_required | — | 402 | 3ds_challenge |
| payment_intent_authentication_failure | — | 402 | 3ds_abandoned |
| gateway_timeout | — | 504 | network_timeout |
API errors
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request | The body isn't valid JSON. |
| 422 | invalid_request | A field is missing or invalid; the message names it. |
| 401 | invalid_api_key | The X-Api-Key matches no active key (revoked, mistyped). |
| 401 | auth_required | This endpoint needs a key or a signed-in session. |
| 403 | insufficient_scope | A ci key was used for an account action. |
| 403 | owner_only | Only the account owner can do this (team members can't). |
| 402 | pro_required | Needs Pro or Agency (chaos scenarios, simulate_race, runs, monitors, audits). |
| 402 | agency_required | Needs Agency (client reports, team seats). |
| 404 | not_found | No such project, run, monitor or key in your account. |
| 409 | project_limit_reached | Your plan's project limit is used up. |
| 409 | monitor_limit_reached | Your plan's monitor limit is used up. |
| 409 | domain_not_verified | Verify the monitor's domain first. |
| 409 | not_a_pull_run | Results can only be reported for pull runs. |
| 409 | run_finished | Results for this run were already recorded. |
| 409 | too_many_keys | Revoke a key before creating another. |
| 409 | no_seats | All team seats are in use. |
| 409 | already_member | That email is already on the team. |
| 429 | rate_limit_exceeded | Monthly calls used up. Includes plan and limit. |
| 429 | anonymous_limit_reached | The anonymous allowance is used up. Get a free key. |
| 5xx | internal_error | Something failed on our side. Safe to retry. |
Failure scenarios
Real payment flows break in ways happy-path tests miss. Watch them live in the Chaos Simulator, then put them in CI with a run. Pro · Agency
1 · Duplicate webhook (race condition)
A gateway delivers the same event twice when its first attempt times out, or two workers pick it up at once. Both copies carry the same event id. Without deduplication, the customer is fulfilled or credited twice.
| How to trigger | What to fix |
|---|---|
Run scenario duplicate (both copies at the same moment), or generate with simulate_race: true (second copy ~1 s later). | Reject an event whose id was already processed, atomically: a UNIQUE constraint on event_id, or Redis SET NX. A check-then-insert without a lock fails the concurrent case. |
2 · 3DS abandonment
The customer closes the 3DS window. payment_intent.canceled follows the requires_action event. Your app must release the order and stock instead of leaving them pending.
| How to trigger | What to fix |
|---|---|
Scenario 3ds_abandoned. Runs send both events for the same payment. | Handle payment_intent.canceled (Stripe) or payment.failed with reason authentication_failed (Razorpay): mark the order cancelled and release stock. |
3 · Limbo
The payment is captured, but the webhook never arrives. The order stays pending with no automatic way out.
| How to trigger | What to fix |
|---|---|
Scenario limbo: 201 success, and no webhook at all. | Never fulfil without confirmation, and run a reconciliation job that asks the gateway about payments stuck pending. |
4 · Latency
The payment succeeds immediately, but the webhook arrives 9 s later. Meanwhile your client retried, or your proxy timed out and the gateway resent it. If both paths create an order, the customer pays once and gets two.
| How to trigger | What to fix |
|---|---|
Scenario latency. In runs, time_scale shortens the wait in CI. | Make order creation idempotent per payment id, and deduplicate on the event id, so a late event is a no-op. |