stripe-mock: Fast Sanity Checks for Stripe API Integrations

Why stripe-mock Exists for Stripe Test Suites

stripe-mock addresses a narrow problem in tests that call Stripe through a server-side SDK. It lets a test suite exercise the SDK without making every request depend on Stripe testmode or network availability. The README specifically identifies stripe-ruby and stripe-go test suites as examples. In that setting, the main question is whether the client sends the expected request to the expected endpoint with parameters that have the expected names and types.

The project does not try to model Stripe as a business system. Its responses resemble the real API in data type, but the README explicitly says that stripe-mock does not reproduce the behavior of the real Stripe API. This boundary makes it useful for basic sanity checks and unsuitable for tests that depend on payments, balance changes, saved objects, authentication outcomes, specific decline reasons, or state carried between requests.

That division of responsibility is important for adoption. A passing stripe-mock request can establish useful information about request construction and response shape. It cannot establish that a Stripe integration behaves correctly in production-like scenarios. Stripe's own README says to test changes against testmode, and it points developers with more sophisticated needs toward their own mocks or a playback tool such as the VCR gem.

OpenAPI Validation and Hardcoded Response Generation

stripe-mock is powered by Stripe's OpenAPI specification. Based on the repository layout and README, the server has a catalog of API URLs and their signatures. It returns a response for a recognized URL and responds with 404 for a URL that does not exist. Incoming parameters are checked with JSON Schema, which allows the project to reject unrecognized parameters and parameters with incorrect types.

The response path is different from the request-validation path. Responses are generated from resource fixtures. The README states that those fixtures are generated within Stripe's API and resemble the sample data in Stripe's API reference, but they are hardcoded and may not be realistic for the parameters in a request. The project can reflect some values when the response has the same name and type. For example, a charge request with `amount=123` produces a charge response containing `"amount": 123`. This is a limited parameter reflection mechanism, not a general simulation of request-driven state.

The server can listen over HTTP, HTTPS, or HTTP/2 over HTTPS when the client supports it. It can also listen on Unix sockets. This gives test environments several transport choices without changing the central design: the service checks the shape of a request and returns a fixture-derived response. The architecture favors deterministic, low-overhead checks over realistic state transitions.

Installing stripe-mock with Go, Homebrew, or Docker

With Go installed, the README gives the following installation command. It installs the basic binary from the repository's Go module path.

go install github.com/stripe/stripe-mock@latest

After installation, running stripe-mock without arguments starts HTTP on port `12111` and HTTPS on port `12112`.

stripe-mock

You can select ports explicitly, or omit one port flag to activate only one protocol. Passing `0` asks stripe-mock to select a port automatically.

stripe-mock -http-port 12111 -https-port 12112

For a first request, start the server and call the documented sample endpoint. The README uses a test-style Bearer key, but stripe-mock does not document this key as a real credential or as a mechanism for simulating authentication decisions.

curl -i http://localhost:12111/v1/charges -H "Authorization: Bearer sk_test_123"

The response should come from the mock endpoint and have the data type associated with a charge. Homebrew provides a package and service commands, while Docker publishes a container with ports `12111` and `12112`.

brew install stripe/stripe-mock/stripe-mock

docker run --rm -it -p 12111-12112:12111-12112 stripe/stripe-mock:latest

The repository's Go module declares `go 1.22.1`. The README's dependencies section still describes Go 1.11+ and `GO111MODULE=on`, so the module file is the more specific version statement for current source metadata.

What the Stateless Mock Can and Cannot Model

The largest constraint is statefulness. Data sent in a `POST` request is validated, but it is ignored beyond validation. It is not stored, reflected into later requests, or used to create a persistent resource. A test cannot create a customer and then retrieve that same customer from stripe-mock. A charge request cannot cause a balance to change, and a refund request cannot refer to a prior charge created through the mock.

The response fixtures also have fixed content beyond limited value reflection. That means tests should not assert that every returned field is realistic or that a field changes according to related input. The README specifically warns that typed responses will not necessarily be realistic Stripe responses.

Polymorphic endpoints expose another limitation. If an endpoint can return either a card or a bank account, stripe-mock returns only one resource type and provides no documented way to select the other type. Error simulation is absent for the documented use case of testing specific responses and errors. The server returns a success response instead of the desired error response.

The version boundary is equally strict. stripe-mock is locked to the latest Stripe API version and does not support old versions. A suite that needs to verify version-specific behavior, realistic transitions, or controlled failure responses needs a different test design. The README names custom mocks and playback tools as alternatives, while directing integration validation back to Stripe testmode.

Development, Spec Updates, and Release Cost

The repository includes Go source under directories such as `server`, `param`, `spec`, `embedded`, and `generator`, plus a `Dockerfile`, `Makefile`, and `go.mod`. Its documented test command is ordinary Go package testing, and the Makefile disables the test cache when it invokes `go test`.

go test ./...

The Makefile's full default target runs tests, `go vet`, `staticcheck`, formatting checks, and a build. The build uses vendored dependencies, which means a repository checkout can be built with the checked-in `vendor` directory rather than requiring dependency resolution at build time.

The documented update task downloads the OpenAPI specification and fixtures from the `stripe/openapi` repository, then replaces the files under `embedded/openapi`. This is the main maintenance-facing workflow described for keeping the mock aligned with Stripe API changes.

make update-openapi-spec

The repository is not archived. Its last push was on 2026-10-01, and recent releases include v0.206.0 on 2026-10-01, v0.205.0 on 2026-09-25, and v0.204.0 on 2026-09-24. That release activity does not remove the project's explicit scope decision: the README says statefulness and more sophisticated testing features are not currently planned. Upgrade work may therefore require reviewing fixture and OpenAPI changes rather than waiting for behavioral simulation features.

The repository identifies its license as MIT. That indicates the stated license for using and modifying the code, but it does not change Stripe's terms, test-mode rules, or the obligations that apply to an integration separately.

Choosing stripe-mock Instead of Stateful or Playback Testing

A real alternative is Stripe testmode, which the README names as the required environment for validating changes to a Stripe integration. The approaches differ in purpose. Stripe testmode is the external Stripe test environment, so it can exercise behavior that stripe-mock does not model. stripe-mock is a local schema-oriented substitute for request and response sanity checks, so it can reduce network dependence and keep basic tests fast.

Another alternative is a custom mock or a playback tool such as the VCR gem. A custom mock can be written to return the exact card or bank-account representation needed for a polymorphic endpoint, or to return a chosen error. A playback tool records or replays interactions and is better suited to regression scenarios that depend on specific prior exchanges. stripe-mock instead derives its response from fixtures and a current OpenAPI catalog, so it offers less control over exact scenarios.

The choice follows from the assertion being tested. If the assertion is about a request path or parameter contract, stripe-mock is directly aligned with the project's stated purpose. If the assertion is about persistence, realistic business behavior, exact errors, or historical API versions, the README points away from stripe-mock. The mock can remain in a fast unit or integration-test layer while Stripe testmode covers the behavior that the mock intentionally omits.

Editorial conclusion

Adopt stripe-mock for fast checks that verify URL paths, parameter names, parameter types, and response decoding. Do not use it as a replacement for Stripe testmode, persistence tests, error-behavior tests, regression scenarios, or old API versions. Verify first that your test expectations match its stateless response model, then run integration changes against Stripe testmode.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. stripe/stripe-mock on GitHub