How can I mock a payment API for development and testing?

Mocking a payment API is a great way to develop and test without hitting real gateways or risking real charges. The best approach depends on whether you want a local fake service, a record/replay setup, or a sandbox from the provider.

Common approaches

1. Use the payment provider’s sandbox/test mode

Most payment APIs offer:

• Test keys / sandbox accounts
• Test card numbers
• Simulated success/failure responses
• Webhook testing tools

Examples:

• Stripe: test mode + test cards + Stripe CLI for webhook forwarding
• PayPal: sandbox accounts
• Adyen / Braintree / Square: test environments

Best for: end-to-end testing with realistic behavior
Limitations: still depends on external service availability

---

2. Build a local mock server

Create a small service that imitates the payment API endpoints your app uses.

You can use:

• WireMock
• MockServer
• Prism (for OpenAPI-driven mocks)
• json-server (for simple REST-ish APIs)
• Custom Express/FastAPI/Django app

This mock can return:

• Successful payment creation
• Declined card errors
• Pending/processing states
• Webhook events
• Idempotency conflicts

Best for: fast local development and integration tests
Benefits: no external dependency, predictable, easy to force edge cases

---

3. Use contract-based mocks

If the payment API has an OpenAPI/Swagger spec, you can generate a mock from the spec and keep it aligned with expected request/response shapes.

Tools:

• Prism
• OpenAPI Generator (for stubs)
• MockServer with recorded expectations

Best for: teams needing API contract validation
Benefits: reduces drift between mock and real API

---

4. Record and replay traffic

Capture real requests/responses from the payment API in a safe environment, then replay them in tests.

Tools:

• VCR.py (Python)
• Betamax
• Polly.js
• Hoverfly
• Some proxy-based mock tools

Best for: stable integration tests
Limitations: can become brittle if API behavior changes

---

What to mock in a payment API

A realistic mock should cover more than just “payment succeeded”:

• Create payment intent / charge
• Capture / authorize / refund
• Customer creation
• Subscription lifecycle if applicable
• Webhook callbacks
• Declines and error codes
• Timeouts / rate limits
• Duplicate requests via idempotency keys
• Partial refunds / chargebacks if relevant

---

Suggested setup for development

A practical approach is:

1. Use sandbox/test mode for occasional full integration checks.
2. Use a local mock server for everyday development.
3. Use contract tests to ensure the mock matches the real API.
4. Use webhook simulation to test async flows.

---

Example: simple local mock behavior

If your app calls:

• POST /payments
• GET /payments/:id
• POST /refunds

Your mock could:

• Return a fake payment ID
• Store payment state in memory or a test DB
• Return status: succeeded, status: failed, or status: pending
• Fire a webhook event after a short delay

---

Good practices

• Never use real secrets in tests
• Separate test and production configs
• Make failures easy to simulate
• Keep mock responses close to real API schemas
• Log requests for debugging
• Reset state between tests
• Use deterministic IDs and timestamps where possible

---

Example tools by stack

• Node.js: Nock, MSW, WireMock, MockServer
• Python: responses, requests-mock, VCR.py, respx
• Java: WireMock, MockServer, Mockito for service layers
• Frontend: MSW (Mock Service Worker)
• API-first: Prism, Stoplight

---

Recommendation

If you want the most practical setup:

• For unit tests: mock the payment client/interface directly
• For integration tests: run a local mock server
• For end-to-end tests: use the payment provider’s sandbox

If you want, I can also show you:

1. a Node/Express mock payment API example,
2. a Python/FastAPI mock, or
3. a WireMock setup for testing.