A stripe-mock alternative that's stateful, hosted, and fails on demand

stripe-mock is Stripe's official mock HTTP server, and it's genuinely good at its stated job: it knows every Stripe API URL, validates your request parameters against the real API's JSON Schema, and returns spec-generated sample responses — fast, offline, in your test suite. If that's all you need, install it and move on.

But its README is refreshingly blunt about what it doesn't do, by design:

It's stateless. Data you send on a POST is validated, then completely ignored — it isn't reflected in the response or on any future request.
Responses are hardcoded fixtures. They're sample data, not realistic reflections of what you sent.
You can't test errors. Requests that should produce a specific decline or error response return a success fixture instead.
No statefulness is coming. Stripe's stated plan is that stripe-mock stays a "basic sanity checks" tool — their own advice for more sophisticated needs is to define your own mocks.

This guide is exactly that: define your own payments mock — hosted on a public HTTPS URL (so CI, teammates, mobile builds, and deployed previews can all hit it), stateful (POST a payment, GET it back, PATCH it settled), with declines, timeouts, and exact retry sequences on demand, plus HMAC-signed webhooks. No account, no keys, no binary to run.

Testing your checkout flow, decline UX, retry logic, or webhook handler? That's this page. Testing the actual Stripe SDK integration itself? Use Stripe test mode — see the honest comparison below.

1. A Stripe-shaped mock in one paste

New — skip the paste: one click (or

curl -X POST https://mockbird.mockbird.workers.dev/api/projects -H 'content-type: application/json' -d '{"preset":"payments"}'

) creates a ready payments sandbox: charges/refunds/subscriptions/customers CRUD plus a Stripe-shaped POST /v1/payment_intents → /v1/payment_intents/:id/confirm flow and /v1/balance. The paste below builds a custom-shaped mock instead — use it when you want finer control over the Stripe shapes.

BASE=https://mockbird.mockbird.workers.dev
P=$(curl -s -X POST $BASE/api/projects -H 'content-type: application/json' \
     -d '{"name":"payments-mock","blank":true}')
PID=$(echo $P | sed 's/.*"id": *"\([^"]*\)".*/\1/')
KEY=$(echo $P | sed 's/.*"adminKey": *"\([^"]*\)".*/\1/')

curl -s -X POST $BASE/api/projects/$PID/resources -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{
  "name":"payment_intents",
  "fields":[
    {"name":"amount","type":"number"},
    {"name":"currency","type":"oneOf","values":["usd","eur","gbp"]},
    {"name":"status","type":"oneOf","values":["requires_payment_method","processing","succeeded","canceled"]},
    {"name":"customerEmail","type":"email"},
    {"name":"created","type":"pastDate"}
  ],
  "seed":5
}'

You now have GET/POST/PATCH/DELETE /m/<PID>/payment_intents with 5 seeded records:

curl "https://mockbird.mockbird.workers.dev/m/<PID>/payment_intents?limit=1"

[
  {
    "id": 1,
    "amount": 91,
    "currency": "gbp",
    "status": "canceled",
    "customerEmail": "ezra.nielsen37@example.com",
    "created": "2026-07-23T09:12:02.663Z"
  }
]

The field set is yours — add clientSecret (uuid), cardLast4, captureMethod (oneOf), whatever your app reads. Filters work out of the box: ?status=processing, ?amount_gte=1000.

2. The stateless contrast: POST it, then GET it back

This is the exact thing stripe-mock's README says it will never do — and it's usually the first thing a checkout test needs:

# your checkout creates an intent
curl -s -X POST $BASE/m/$PID/payment_intents -H 'content-type: application/json' \
  -d '{"amount":2000,"currency":"usd","status":"processing","customerEmail":"jo@example.com"}'
# → {"amount":2000,"currency":"usd","status":"processing","customerEmail":"jo@example.com","id":6}

# your UI polls — the record is really there
curl -s $BASE/m/$PID/payment_intents/6      # status: "processing"

# the test driver plays the gateway: settle it
curl -s -X PATCH $BASE/m/$PID/payment_intents/6 -H 'content-type: application/json' \
  -d '{"status":"succeeded"}'

Every write is visible to every later read, from any client — your browser, your CI job, a teammate's curl. That's a database under the mock, not a fixture file.

3. Declines on demand — the error responses stripe-mock can't return

stripe-mock returns a success fixture even for requests that should fail. Here, any request fails exactly when you tell it to:

curl -si -X POST "$BASE/m/$PID/payment_intents?mock_status=402" \
  -H 'content-type: application/json' -d '{"amount":100,"currency":"usd","status":"processing"}'
# HTTP/2 402
# {"error": "simulated 402 error (mock_status)"}
# and no phantom record is created — the write is not applied

Any status 400–599 works (mock_status=429 for rate-limit UX, 503 for gateway-down banners), and mock_delay=4000 composes with it for slow-failure paths. Full recipes in testing loading & error states.

4. Exact retry choreography: declined, declined, succeeded

Card-decline retry logic is miserable to test against anything real. mock_seq scripts the exact sequence of outcomes:

# first attempt 402, second 402, third succeeds — exactly
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  "$BASE/m/$PID/payment_intents?mock_seq=402,402,201&mock_seq_key=card-retry-9" \
  -H 'content-type: application/json' \
  -d '{"amount":20,"currency":"eur","status":"processing"}'
# run it 3x: 402, 402, 201

Each mock_seq_key tracks its own position, so parallel tests don't trample each other's sequences.

5. Signed webhooks — no `stripe listen`, no tunnel

Point the project's webhook at your handler and every create/update/delete fires a signed POST, with a familiar-looking secret:

curl -s -X PUT $BASE/api/projects/$PID/webhook -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{"url":"https://your-app.example.com/hooks/payments"}'
# → {"ok":true,"webhook":{"secret":"whsec_a60818b5d376…","events":["created","updated","deleted"]}}

Deliveries carry X-Mockbird-Signature: sha256=… (HMAC-SHA256 of the raw body) so your verification code path actually runs. Verify snippet and delivery-log details in sending test webhooks; a full payment-webhook walkthrough is in the mock payment API guide.

stripe-mock concern → Mockbird

You wanted	stripe-mock	Mockbird
POST data visible on later GETs	✗ stateless by design	✔ persisted (real CRUD)
Simulate declines / specific errors	✗ success fixtures only	`?mock_status=402` (any 400–599)
Scripted outcome sequences	✗	`?mock_seq=402,402,201`
Slow-gateway latency	✗	`?mock_delay=3000` (+ jitter, chaos)
Webhook deliveries	✗	✔ HMAC-signed, `whsec_` secret
Reachable by CI / teammates / previews	your machine or network	✔ public HTTPS URL
Setup	brew / Docker / Go binary	one curl, no install
Exact Stripe URLs + param validation	✔ generated from the real spec	✗ your own shapes

Honest comparison — where stripe-mock (and test mode) win

Spec accuracy. stripe-mock's URL catalogue and JSON-Schema parameter validation come from Stripe's real OpenAPI spec. If your test's job is "did I call the Stripe API with valid parameters?", it's the right tool and Mockbird isn't.
Offline and zero-latency. A local binary beats any hosted service for hermetic unit tests with no network.
It's official. Maintained by Stripe, tracks the latest API version automatically.
Stripe test mode is the real thing. Stripe's own warning applies to every mock, theirs and ours: mocks can differ from the live API in nuanced ways — always test your integration against test mode before shipping. Nothing on this page replaces that.

The clean split: stripe-mock for sanity-checking calls against Stripe's schema, Stripe test mode for integration truth, Mockbird when the thing under test is your flow — checkout states, decline UX, retry logic, webhook verification, order screens — and you want a stateful backend that any client can reach without a payments account. They compose; plenty of teams use all three.

Notes & limits

On PayPal instead? Same technique, PayPal-shaped — including why the sandbox's account/OAuth/approval-flow tax makes a mock worth it: PayPal sandbox alternative. On Braintree, where declines are magic amounts: Braintree sandbox alternative. On Square, where they're magic test values: Square sandbox alternative. On Adyen, where the cardholder is literally named DECLINED: Adyen test alternative. Mocking the bank-data side (Plaid-style accounts & transactions): Plaid sandbox alternative.
Want literal provider paths like /v1/payment_intents with templated bodies? Custom routes do that — same technique as the OpenAI mock guide. To replay a recorded real API instead, see mocking third-party APIs.
Pin the whole dataset per test scenario with snapshots — parallel workers can each pin their own.
This mock never sees card numbers — don't send real PANs anywhere near test config, including here.
Free tier: 10,000 requests/project/day, 1,000 records/resource. It's a mock — don't point production at it.

Create yours

The paste block in section 1 is the whole setup — or open the dashboard and click it together. The same project also serves GraphQL, exports OpenAPI + TypeScript types, and ejects to db.json anytime — no lock-in.