IPG Sandbox
سندباکس درگاه پرداخت قابل میزبانی شخصی برای شبیهسازی زرینپال، آیدیپی و بهپرداخت.
Problem & solution scope
Testing payment workflows in Iranian software development has historically required live test credentials, manual card simulations, or unstable staging endpoints. IPG Sandbox is a zero-setup, self-hosted emulation suite that mirrors the REST and SOAP APIs of major payment gateways (Zarinpal, IDPay, Behpardakht Mellat), allowing developers to test approve, decline, timeout, refund, and verify-fail scenarios deterministically in local dev and CI/CD pipelines.
System architecture
Dual-Plane Simulation Engine with Deterministic State MachineArchitected into a high-performance Python FastAPI engine and a Next.js inspection dashboard. The engine intercepts standard gateway endpoints, models transactions through a persistent state machine, and evaluates header-driven scenario rules (X-Sandbox-Scenario) without modifying production code under test.
اجزای سیستم
Emulation Engine
Python 3.11+ / FastAPI / SQLModelExposes drop-in compatible REST and SOAP WSDL endpoints imitating real gateway network contracts and error codes.
Deterministic Scenario Evaluator
Header & Rule EngineEvaluates headers like X-Sandbox-Scenario: decline or timeout to inject predictable failure modes without mocking SDK internals.
Transaction State Machine
SQLModel / SQLite & PostgreSQLTracks lifecycle states: INITIATED -> PENDING -> PAID / FAILED -> VERIFIED, enforcing double-verification prevention.
Inspection Web Dashboard
Next.js / Tailwind CSS / PlaywrightReal-time UI for viewing live transactions, payload inspection, simulated user payment UI, and callback triggers.
جریان داده و اجرا
Base URL Redirection
Application under test points its gateway URL to http://localhost:8080/{gateway} with the test merchant ID.
Scenario Injection
Test suite or developer passes optional X-Sandbox-Scenario header (e.g. approve, decline, timeout, verify_fail).
Transaction Tracking
Engine persists transaction state, generates reference tokens, and logs the HTTP exchange.
Callback Execution
Engine simulates redirect or webhook to merchant's callback URL; merchant verifies transaction against sandbox verification endpoint.
Engineered capabilities
18-Cell Scenario Matrix: 6 realistic outcomes (approve, decline, timeout, refund, pending_settle, verify_fail) across 3 gateway adapters.
Zero External Dependencies: Runs fully offline via Docker Compose without external internet access or credit cards.
Fault-Injection via Headers: Non-invasive testing without changing application business logic.
Real-Time Inspection Dashboard: Live visual inspection of payloads, callbacks, and transaction states.
Dual SQL Engine: Lightweight SQLite for local dev and fast unit tests (199+ passed tests), PostgreSQL for concurrency testing.
Engineering trade-offs
Header-Based Scenario Selection
Using standard HTTP headers (X-Sandbox-Scenario) allows E2E test suites to force error branches without modifying application code or database records.
Documented-Subset SOAP Emulation
Emulated the precise WSDL operations used by mainstream Behpardakht payment SDKs, maintaining high fidelity without full banking mainframe overhead.
Local Docker Compose Launch
git clone https://github.com/amirmuha/ipg-sandbox.git
cd ipg-sandbox
cp .env.example .env
docker compose up -d
# Dashboard available on http://localhost:3000
# Gateway engine on http://localhost:8080/api/v1