Payment Sandbox is a payment systems simulator written in Go.
It helps backend developers test payment integrations against realistic business workflows, asynchronous events and distributed-system failures without depending on a real payment service provider.
Payment Sandbox is not a payment service provider and does not process real money.
Traditional HTTP mock servers can return predefined responses, inject latency or simulate network failures. Payment integrations require more than HTTP mocking.
A payment may succeed even when the client receives a timeout. A webhook may arrive multiple times, late, out of order or before a resource becomes visible through the API. Concurrent capture or refund requests may race against each other.
Payment Sandbox is designed to make these situations reproducible and testable.
Payment Sandbox aims to provide:
- a canonical payment API for integration testing;
- realistic payment lifecycle simulation;
- deterministic and reproducible scenarios;
- configurable API and network failures;
- asynchronous webhook delivery;
- idempotency and concurrency testing;
- observable execution timelines;
- a local-first and CI-friendly developer experience.
Payment Sandbox is designed as a deterministic payment simulation platform.
Its architecture is documented through a series of Architecture Decision Records (ADRs) covering:
- modular monolith architecture;
- domain modelling;
- targeted hexagonal architecture;
- durable asynchronous work;
- deterministic payment lifecycle;
- immutable business event history;
- observability;
- deterministic replay;
- virtual time;
- provider extensibility.
See docs/architecture.
The provider model is described in the provider guide. The replay workflow is described in the scenario guide. The complete HTTP API is described in the API guide, with an OpenAPI contract for tools and client generation.
Payment Sandbox can be used to test situations such as:
- a payment is authorized successfully;
- a payment is declined for a business reason;
- a payment is created but the HTTP response is lost;
- the same request is retried with an idempotency key;
- two capture requests are sent concurrently;
- a refund succeeds asynchronously;
- a webhook is delayed;
- a webhook is delivered more than once;
- webhooks are delivered out of order;
- a webhook contains an invalid signature;
- the API temporarily returns stale or inconsistent state.
Choose the path that matches your goal:
- Use Payment Sandbox: follow the user installation guide to download the latest release without cloning the repository or installing Go. This is the recommended path for trying the product.
- Explore or contribute to the code: follow the Getting Started guide to clone, configure and validate a source checkout.
Both paths lead to the same HTTP API and first-payment walkthrough.
See the Contributing guide for module boundaries, testing, commits and pull requests.
Maintainers can find the release procedure in the Releases guide.
Common development commands are exposed through the Makefile.
make helpTypical workflow:
make fmt
make test
make lint
make checkBuild and run the application:
make build
make run
The application loads configuration from environment variables during startup.
When running from a source checkout, make run loads .env by default if it
exists and automatically rebuilds the server when Go source, migration or
environment files change. Choose another file with make run ENV_FILE=.env.test.
Air must be installed for the source-checkout development loop. A published
binary can load a file explicitly with payment-sandbox --env-file .env.demo,
or run without a dotenv file when its variables are provided by the
environment.
If you have cloned the repository, start the sandbox from its root:
make runIn another terminal, check that it is ready, create a payment and authorize it:
curl http://127.0.0.1:8080/health/ready
curl -X POST http://127.0.0.1:8080/payments \
-H 'Content-Type: application/json' \
-d '{"id":"demo-payment","amount":1000,"currency":"EUR"}'
curl -X POST http://127.0.0.1:8080/payments/demo-payment/authorize
curl http://127.0.0.1:8080/payments/demo-paymentThis demonstrates the basic payment lifecycle without requiring a provider account or a separate application. Continue with the complete installation and first-payment walkthrough to explore webhooks and the local database.
If you are using a published binary, follow the same scenario from the release installation guide after downloading and starting the latest release.
Payment Sandbox is configured through environment variables.
Available variables:
| Variable | Default | Values |
|---|---|---|
PAYMENT_SANDBOX_LOG_LEVEL |
info |
debug, info, warn, error |
PAYMENT_SANDBOX_LOG_FORMAT |
text |
text, json |
PAYMENT_SANDBOX_HTTP_ADDRESS |
:8080 |
HTTP listen address |
PAYMENT_SANDBOX_ADMIN_TOKEN |
none | Bearer token required for /admin/* routes |
Example:
PAYMENT_SANDBOX_LOG_LEVEL=debug \
PAYMENT_SANDBOX_LOG_FORMAT=json \
make runSee .env.example for the currently supported configuration.
Payment Sandbox uses structured logging through Go's log/slog.
Default configuration:
PAYMENT_SANDBOX_LOG_LEVEL=info
PAYMENT_SANDBOX_LOG_FORMAT=textJSON output can be enabled with:
PAYMENT_SANDBOX_LOG_FORMAT=json make runRun the complete test suite:
go test ./...Run tests with the Go race detector:
go test -race ./...Generate a coverage report:
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out- Tests should be deterministic.
- Unit tests should live next to the code they exercise.
- Prefer table-driven tests when several inputs exercise the same behaviour.
- Tests should not depend on external services.
- Avoid real sleeps for time-dependent behaviour.
- Prefer observable behaviour over implementation-detail assertions.
golangci-lint runCheck formatting without modifying files:
golangci-lint fmt --diffFailures must be reproducible.
Randomized fault injection may be supported, but every randomized execution must be associated with a known seed and an inspectable decision log.
Payment Sandbox models payment concepts and invariants instead of serving only static HTTP fixtures.
The sandbox should be easy to run locally, in Docker and in automated test pipelines.
Every request, domain transition, generated event and webhook delivery attempt should be inspectable.
The project uses domain-driven design, hexagonal architecture and distributed-systems patterns only where they provide concrete value.
It deliberately avoids unnecessary microservices, framework-heavy abstractions and interfaces without meaningful substitution points.
The initial scope is intentionally limited to:
- payments;
- authorizations;
- captures;
- cancellations;
- refunds;
- payment events;
- webhook delivery attempts;
- idempotency.
Future versions may introduce additional payment methods, disputes and subscriptions.
Payment Sandbox is implemented as a modular monolith. The current runtime is organized around these modules:
- Payment and its state machine;
- Provider profiles and deterministic execution;
- Durable scheduling and asynchronous work;
- Saga orchestration;
- Webhook registration and delivery;
- Scenario replay and diagnostics;
- Administration and platform concerns.
External concerns such as persistence, clocks, random generation and outbound HTTP delivery are isolated behind explicit architectural boundaries when substitution provides real value.
The current deterministic scenario and replay model is documented in the scenario guide. The scenario format is not yet a stable, versioned standalone file format.
API
↓
Payment Domain
↓
Provider Plugin
↓
Business Events
↓
Durable Jobs
↓
Virtual Clock
↓
Replay / Diagnostics
Payment Sandbox is under active development. Published versions are listed on the GitHub Releases page. The latest release can always be found at /releases/latest.
The current release provides the following capabilities for local and integration testing:
- canonical payment lifecycle API;
- durable SQLite-backed scheduler and asynchronous jobs;
- virtual business time with wall-clock lease recovery;
- deterministic fake, Stripe and Adyen provider profiles;
- immutable payment event history and diagnostics;
- webhook endpoint registration and outbound delivery;
- deterministic scenario replay;
- Saga orchestration for provider-backed payment workflows.
- the HTTP API and its public compatibility guarantees;
- the provider profile and failure-injection model;
- the scenario model and replay ergonomics;
- operational documentation and observability details.
Compatibility guarantees are defined by the documentation for each published release rather than by the major version alone.
The following areas are intentionally outside the current stable contract:
- a versioned, standalone scenario file format;
- broader provider behaviour profiles and integration examples;
- additional public API capabilities built on the existing domain model.
Planned items are design directions, not promises for a specific release.
For a local build, run go run ./cmd/payment-sandbox --version; published
release binaries report the version injected from their release tag.
Payment Sandbox is not intended to:
- process real payments;
- store real cardholder data;
- replace official provider sandboxes;
- guarantee complete compatibility with any payment provider;
- simulate an entire banking or acquiring infrastructure;
- require a distributed deployment to model distributed-system behaviour.
Payment Sandbox must never be exposed publicly with unrestricted webhook destinations or administrative endpoints.
Webhook registration rejects local and private IP literals. Runtime outbound
delivery resolves DNS at connection time, rejects private, loopback, link-local
and unspecified addresses, does not use an HTTP proxy, and does not follow
redirects. Administrative endpoints require the configured
PAYMENT_SANDBOX_ADMIN_TOKEN as a bearer token, but should still be kept on a
trusted local or private network and protected by an upstream network policy.
Do not use real payment credentials, cardholder data or production secrets.
- Architecture overview
- Architecture diagrams
- Architecture principles
- Architectural Decision Records
- Getting Started guide
- Installation and first-payment walkthrough
- HTTP API guide
- OpenAPI contract
- Provider guide
- Scenario guide
See CONTRIBUTING.md and AGENTS.md for the current contribution and validation workflow.
Early discussions should focus on:
- payment-domain invariants;
- scenario reproducibility;
- failure semantics;
- webhook delivery guarantees;
- developer experience;
- explicit architectural trade-offs.
Payment Sandbox is licensed under the MIT License. See LICENSE for the complete license text.