A PayPal sandbox alternative for your dev loop — no account, no OAuth, fails on demand

Let's be precise about what the PayPal sandbox is: the real integration environment, and the only place to verify your actual PayPal integration before go-live. Nothing on this page replaces it.

But the everyday dev loop — building order screens, decline UX, retry logic, webhook handlers — pays a lot of sandbox tax that has nothing to do with what you're testing:

You can't send a single request without an account. An unauthenticated POST /v2/checkout/orders returns 401 AUTHENTICATION_FAILURE. Before your first mock payment you need a PayPal account, the developer dashboard, a REST app, and a client ID + secret.
Every call needs an OAuth Bearer token — and tokens expire. Your test suite grows token-fetching and 401-retry plumbing that exists only to talk to the sandbox.
Orders need a buyer to approve them. Moving an order past CREATED means a sandbox buyer account clicking through a real web approval flow — automating that in CI means scripting a login UI you don't control.
Error simulation is gated and enumerated. Sandbox negative testing (in beta) works by sending a PayPal-Mock-Response header with a mock_application_codes value from their documented error list — after you've done all the auth setup above. You can't script an arbitrary status or an exact fail-fail-succeed sequence.
It's a real shared environment — real network latency, and when it has a bad day, your test run does too.

This guide builds the mock version in one paste: a hosted, stateful, PayPal-shaped API on a public HTTPS URL. No account, no keys, no token dance — and it fails exactly when you tell it to.

Testing your checkout flow, decline UX, retry logic, or webhook handler? That's this page. Verifying the real integration — approval flow, capture truth, webhook signatures? Use the sandbox; see the honest comparison below.

1. A PayPal-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 PayPal-shaped responses specifically.

BASE=https://mockbird.mockbird.workers.dev
P=$(curl -s -X POST $BASE/api/projects -H 'content-type: application/json' \
     -d '{"name":"paypal-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":"orders",
  "fields":[
    {"name":"intent","type":"oneOf","values":["CAPTURE","AUTHORIZE"]},
    {"name":"status","type":"oneOf","values":["CREATED","APPROVED","PAYER_ACTION_REQUIRED","COMPLETED","VOIDED"]},
    {"name":"amountValue","type":"number"},
    {"name":"currencyCode","type":"oneOf","values":["USD","EUR","GBP"]},
    {"name":"payerEmail","type":"email"},
    {"name":"createTime","type":"pastDate"}
  ],
  "seed":5
}'

You now have GET/POST/PATCH/DELETE /m/<PID>/orders with 5 seeded, PayPal-shaped records:

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

[
  {
    "id": 1,
    "intent": "AUTHORIZE",
    "status": "PAYER_ACTION_REQUIRED",
    "amountValue": 103,
    "currencyCode": "GBP",
    "payerEmail": "omar.marin4@example.com",
    "createTime": "2026-04-07T00:12:30.590Z"
  }
]

The statuses are the real Orders API vocabulary, so your status-badge component and state machine exercise real branches. Filters work immediately: ?status=COMPLETED, ?amountValue_gte=40, ?currencyCode=EUR.

2. The approval flow you don't have to automate

In the sandbox, an order sits in CREATED until a sandbox buyer logs in and approves it. Here, your test driver plays the buyer — no web flow, no second account:

# your checkout creates an order
curl -s -X POST $BASE/m/$PID/orders -H 'content-type: application/json' \
  -d '{"intent":"CAPTURE","status":"CREATED","amountValue":49.99,"currencyCode":"USD","payerEmail":"jo@example.com"}'
# → {"intent":"CAPTURE","status":"CREATED","amountValue":49.99,…,"id":6}

# your UI polls — the record is really there (stateful, not a fixture)
curl -s $BASE/m/$PID/orders/6            # status: "CREATED"

# the test driver "approves" and settles it
curl -s -X PATCH $BASE/m/$PID/orders/6 -H 'content-type: application/json' \
  -d '{"status":"COMPLETED"}'

Every write is visible to every later read, from any client — browser, CI job, teammate's curl. Walk an order through CREATED → APPROVED → COMPLETED and watch your UI track it.

3. A literal `/orders/:id/capture` endpoint

If your client calls a capture-style path, don't change the client — add a custom route with a templated PayPal-shaped body:

curl -s -X POST $BASE/api/projects/$PID/routes -H "x-admin-key: $KEY" \
  -H 'content-type: application/json' -d '{
  "method":"POST","path":"/orders/:id/capture","status":201,
  "body":"{\"id\":\"{{params.id}}\",\"status\":\"COMPLETED\",\"purchase_units\":[{\"payments\":{\"captures\":[{\"id\":\"{{uuid}}\",\"status\":\"COMPLETED\"}]}}],\"update_time\":\"{{now}}\"}"
}'

curl -s -X POST $BASE/m/$PID/orders/6/capture

{
  "id": "6",
  "status": "COMPLETED",
  "purchase_units": [
    { "payments": { "captures": [ { "id": "a62791a0-ce78-4187-acfe-cddf17c4c9ae", "status": "COMPLETED" } ] } }
  ],
  "update_time": "2026-09-15T13:42:26.103Z"
}

Custom routes take precedence over the generated CRUD routes, so this coexists with the orders resource above — {{params.id}}, {{uuid}}, and {{now}} are filled per request.

4. Declines on demand — any status, no enablement, no header vocabulary

PayPal's Orders API signals business failures like INSTRUMENT_DECLINED as HTTP 422. Get one whenever you want it:

curl -si -X POST "$BASE/m/$PID/orders?mock_status=422" \
  -H 'content-type: application/json' \
  -d '{"intent":"CAPTURE","status":"CREATED","amountValue":10,"currencyCode":"USD"}'
# HTTP/2 422
# {"error": "simulated 422 error (mock_status)"}
# and no phantom record is created — the write is not applied

Any status 400–599 works: 429 for rate-limit UX, 500/503 for gateway-down banners, and mock_delay=4000 composes for slow-failure paths. No beta program, no auth, no enumerated code list — full recipes in testing loading & error states.

5. Exact retry choreography: declined, declined, captured

# first attempt 422, second 422, third succeeds — exactly
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  "$BASE/m/$PID/orders?mock_seq=422,422,201&mock_seq_key=pp-retry-1" \
  -H 'content-type: application/json' \
  -d '{"intent":"CAPTURE","status":"CREATED","amountValue":20,"currencyCode":"EUR"}'
# run it 3x: 422, 422, 201

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

6. Signed webhooks — no webhook simulator, no tunnel

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/paypal"}'
# → {"ok":true,"webhook":{"secret":"whsec_bebb10c56a11…","events":["created","updated","deleted"]}}

Every create/update/delete fires a signed POST (X-Mockbird-Signature: sha256=…, HMAC-SHA256 of the raw body) so your verification code path actually runs — including the PATCH-to-COMPLETED from section 2, which is exactly the "payment finished" event your handler cares about. Verify snippet and delivery log in sending test webhooks.

PayPal-sandbox concern → Mockbird

You wanted	PayPal sandbox	Mockbird
First request without an account	✗ 401 — dev account + REST app + client ID/secret first	✔ one anonymous curl
No OAuth token plumbing in tests	✗ Bearer token on every call, expires	✔ no auth (opt-in mock JWT if you want it)
Advance an order without a buyer login	✗ sandbox buyer approves via web flow	✔ PATCH the status
Arbitrary error statuses	△ negative testing (beta), documented codes via header	✔ `?mock_status=` any 400–599
Scripted outcome sequences	✗	✔ `?mock_seq=422,422,201`
Deterministic latency	✗ real shared environment	✔ `?mock_delay=`, jitter, chaos
Reset to a known dataset per test	✗	✔ snapshots
Real PayPal integration truth	✔ that's its job	✗ your own shapes

Honest comparison — where the sandbox wins

It's the real thing. Real order lifecycle, real approval flow, real capture semantics, real webhook payloads and signature verification. A mock — theirs or ours — can differ from the live API in nuanced ways.
Negative testing exists. If you need PayPal's specific error bodies for documented codes, sandbox negative testing returns the genuine article; Mockbird returns the status you asked for with a generic body (or a custom-route body you define).
You must pass through it anyway. Go-live review and end-to-end verification happen against the sandbox. Budget for it at the end; just don't pay its setup tax on every red-green-refactor cycle.

The clean split: Mockbird while you build — UI states, declines, retries, webhook handler logic, CI. PayPal sandbox before you ship — integration truth. They compose.

Notes & limits

Building for Stripe, Braintree, Square, or Adyen instead? Same technique: stripe-mock alternative · Braintree sandbox alternative · Square sandbox alternative · Adyen test alternative. Provider-agnostic walkthrough: mock payment API. Mocking the bank-data side (Plaid-style accounts & transactions)? Plaid sandbox alternative.
Want to mirror more of the real response shapes? Record a real sandbox session once and replay it — see mocking third-party APIs.
This mock never sees card numbers or real PayPal credentials — keep it that way.
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.