The first rule of a sandbox is that it must be more available than the thing it imitates. The payment API has a sandbox, and it is more available than our own production build, which is a sentence nobody should be able to write about a payment API.
This is the situation across much of African FinTech: a payment product where the integration surface is a set of third-party gateways — Interswitch, Paystack, Flutterwave, and a long tail of regional acquirers — each with its own authentication scheme, its own webhook envelope, and its own definition of what a successful transaction looks like. And each with a sandbox that requires network access, a credential request, and often a conversation with the provider's support desk.
The result is a testing regime that I can only describe as inverted: the code most likely to lose money is the code least likely to be exercised automatically.
The inversion
Here is what a normal engineering org looks like. The payment path has unit tests, integration tests, a mocked gateway, and a staging environment that mirrors production. The team ships with confidence.
Here is what an org with a hard external dependency looks like. The payment path is excluded from CI because the CI environment has no credentials. A staging environment exists, but it is a shared box that people log into to poke at manually, which means it is a bottleneck, and bottlenecks get skipped. New engineers take three weeks to write their first payment test, because getting to that point requires a person who knows which internal wiki page explains the sandbox credential rotation.
The testing of the riskiest code is manual, senior-only, and late. I have seen this pattern in three companies now, and the reason it survives is that the risk is invisible in every dashboard. The dashboard shows green builds, because the payment tests are not in the build.
The arrangement we had
The workspace's answer was a docker compose file with four services: the mock service, an OpenAPI proxy that served the provider specs, and two supporting services.
Measured on one machine with every mock running:
| the four containers | |
|---|---|
| processes | 4 |
| memory | 250 MB |
| of which the OpenAPI proxy | 214 MB, and it does not settle |
| idle CPU | 7.9%, almost all of it the proxy |
| time to first request answered | 20 s and rising |
| things to start, stop and clean up | 4 |
Two things in that table deserve attention. First, 214 MB of the 250 MB was the proxy — the component whose only job was translating a specification, and which never finished doing it. Second, 7.9% idle CPU. The arrangement was not idle. It was translating specs that were already translated, forever, at a rate that made the laptop warm.
And the arithmetic was brutal. On a developer laptop, where memory is the scarcest resource, a test setup that permanently occupies a quarter of a gigabyte and burns eight percent of a core is not a tool that gets used often. It is a tool people queue for, postpone, and eventually bypass — which puts the test back to manual, and the manual version back to one senior person who knows how to run it.
The requirement that changes the design
Most mocking tools are built on the assumption that a network is available. You spin up a container, it reaches out, you point your service at it. This is fine for mocking an internal service. It is close to useless for the case we care about, because:
- A developer on a poor connection, or on a train, or behind a corporate proxy cannot start the environment.
- CI needs the environment to be reproducible, which means the mock needs to be reproducible, which a container that pulls from a registry does not guarantee.
- A developer in a different timezone cannot debug against a shared environment, because the shared environment is a single point of contention for people who are asleep.
The requirement that changes everything is this: the sandbox must work with the network unplugged. Not degrade. Work. Fully. Including the parts that reach out — webhooks, callbacks, settlement notifications.
That single constraint pushes you towards a native runtime with no external dependencies, and towards modelling behaviour rather than serving static fixtures.
Model behaviour, not endpoints
The most common way to build a mock is a set of URL handlers. You write POST /api/charge and return a canned success. It is fast to build and it teaches you almost nothing.
The failure of endpoint-shaped mocks is that they model the interface of a provider and not its behaviour. A real gateway's behaviour is mostly about what happens when things go wrong:
- It declines with a taxonomy of decline codes, not a boolean.
- It times out on a particular operation, and the timeout means the transaction may still have succeeded.
- It delivers webhooks more than once, and out of order, and sometimes days later.
- It settles on a different day than the transaction, sometimes partially.
- It rejects a signature that is correct but uses an old timestamp.
None of that is in the happy-path fixture. All of it is what breaks production. So each provider is modelled as a unit with a behaviour contract — authentication, validation, decline taxonomy, webhook emission, retry policy, settlement timing — and the HTTP surface is generated from the model.
The rules, and why they are rules
The rewrite did not add features. It removed everything removable, and then made the result a rule rather than a preference. The rules are published at the top of the README, because a contributor who breaks one of them breaks the promise in the first line of the file:
No dependencies. Not 'few' — none. The engine runs on Node's own HTTP server. A dependency is a package to install, audit and keep out of the advisories.
No runtime that costs memory to start. A JVM, a compiled Go binary or a Python environment all add to the footprint before a single request is served. Node is already on the machine, because the project under test runs on it.
One process for every mock. Nine mocks in one process cost 50 MB. Nine containers cost nine runtimes.
In the test, not beside it. A test that needs a mock starts it in the test process, with startMock(). Nothing listens on a port, no container starts, and the mock stops when the test ends. This is the cheapest way to mock anything, and it is why the engine is a library first and a service second.
Idle means idle. A mock answers a request and then stops computing. Polling, watching and retrying are how a mock turns into a battery drain.
That last rule is the one most engines get wrong, and it is the reason this one measures 0.0% idle CPU while the stack it replaces sits at 7.9%.
The result
| the engine | four containers | |
|---|---|---|
| processes | 1 | 4 |
| memory | 50 MB | 250 MB |
| idle CPU | 0.0% | 7.9%, almost all of it the proxy |
| time to first request answered | 1.4 s | 20 s and rising |
| things to start, stop and clean up | 1 | 4 |
One process. 50 MB. Nothing at rest. And the first request answered in 1.4 seconds instead of twenty.
The measurement was taken by sampling with ps for resident size and two ps -o time= samples five seconds apart for CPU. The containers were sampled with docker stats --no-stream, once immediately and once after they had settled.
The promise is a build gate
Here is the part I would point at if I could only keep one thing.
The footprint is now a build gate. The footprint test fails the build if the engine exceeds 100 MB, 5 seconds of startup, or 1% idle CPU. A promise nobody checks erodes; this one is checked on every build.
That is why the numbers on this page can be stated without hedging. They are not a claim in a README that will quietly stop being true — they are a constraint that breaks the build when it stops being true. The gap between a number in a README and a number in a test is the gap between a claim and an enforced property.
The providers
Eighteen, and they are the ones that actually matter in the markets I work in:
| Payments | Stripe, Paystack, Interswitch, Flutterwave, Monnify |
| Identity | YouVerify, Smile ID, IdentityPass |
| Messaging | Twilio, Termii, OneSignal, WhatsApp, FCM |
| Everything else | Resend, Xero, Cloudflare, OpenAI, S3 |
Every mock answers /health, so a container can be checked without knowing which mock it is. Provider contracts are held as OpenAPI documents, with a download script that keeps them current, so the mock and the published contract cannot quietly diverge.
What I would do differently
Two things, both learned late.
Model the state machine before the endpoints. I built the HTTP surface first and it showed. When settlement semantics forced a refactor, it was invasive. If I were starting again I would write the state machine — authorize, capture, settle, reverse — and derive the endpoints from it.
Ship the decline taxonomy early. Every provider's decline codes are public and boring, and they are the vocabulary your business logic has to speak. Making that vocabulary available in the first week would have saved us from a quarter of confusion in the integration layer.
Why this matters beyond payments
The pattern generalises. Any team whose product depends on a third-party API they do not control, cannot test against, or cannot get credentials for, has this problem: the dependency is the reason the code is untested.
The fix is not to mock harder. It is to move the environment onto the developer's machine, make it deterministic, and make the failure paths a first-class part of the model. Then a network outage stops being a reason not to test — and you get your integration suite back.
The implementation is open source: api-mock-services. The discipline — pin it, make it loud, keep it local, fail deterministically — is in CI Kit. Both exist because a team I worked with had a payment path that only one person could test, and we decided that was not acceptable.