← Back to Home

Building a Local Banking Sandbox: Why I Created DevBankSDK

fintech-developmentdeveloper-toolsopen-source
#banking-api#synthetic-data#fintech-testing#fastapi#docker#devbanksdk#payment-systems#local-development#api-sandbox

Three weeks ago, I was building a fintech prototype that needed to integrate with banking APIs. The problem? Every test required hitting external sandbox environments with rate limits, authentication headaches, and network latency. I wanted something simpler—a banking API running entirely on my laptop.

So I built DevBankSDK, an open-source developer sandbox for testing fintech applications locally.

GitHub: https://github.com/ranjankumar-gh/devbanksdk

The Problem with Current Banking Test Environments

Most banking API providers offer sandbox environments. Stripe has one, Plaid has one, virtually every payment processor has one. They're useful, but they come with friction:

  • Network dependency: You need internet connectivity to test basic features
  • Rate limits: Free tiers throttle requests, slowing down development
  • Authentication complexity: Managing API keys, tokens, and OAuth flows just to test locally
  • Data persistence issues: Sandbox data gets wiped periodically
  • Limited customization: You're constrained by whatever test scenarios they provide

For rapid prototyping or offline development, this doesn't work. You end up mocking APIs manually or writing elaborate test fixtures. Neither feels right.

What DevBankSDK Does

DevBankSDK provides a complete banking backend that runs locally via Docker. It generates realistic synthetic data (customers, accounts, transactions) and exposes REST APIs that mimic real banking operations.

The core features:

Synthetic Data Generation: Creates realistic but completely fake banking data—account numbers, routing numbers, customer profiles, transaction histories. All follow proper formats (valid Luhn checksums for cards, proper account number structures) but won't validate as real data.

Full Banking APIs: Endpoints for account management, money transfers, transaction history, card operations. Built with FastAPI, so you get automatic OpenAPI documentation.

Docker Deployment: Single docker-compose up command spins up PostgreSQL, Redis, and the API server. No manual configuration needed.

Developer CLI: Command-line tool for seeding data, resetting environments, and managing test scenarios.

Technical Architecture

I kept the stack deliberately simple:

code 
Backend:     FastAPI (Python 3.11+)Database:    PostgreSQL 15Cache:       Redis 7ORM:         SQLAlchemyCLI:         ClickContainer:   Docker + docker-compose

The data generator uses Faker for realistic names and addresses, with custom logic for banking-specific fields. Account numbers are 12-digit random sequences, routing numbers follow the 9-digit format, and credit cards use test number ranges that won't validate on real payment networks.

The transaction engine simulates realistic patterns:

  • Recurring bill payments (utility bills, subscriptions)
  • Salary deposits on specific days
  • Random merchant transactions with variable amounts
  • Inter-account transfers
  • ATM withdrawals with location data

All transactions maintain referential integrity—debits and credits balance, account balances update atomically, and transaction histories are fully auditable.

Why I Built This in Python

FastAPI made sense for several reasons. First, it generates OpenAPI specs automatically, which means developers get interactive documentation out of the box. Second, Python has excellent libraries for data generation (Faker) and financial calculations. Third, most ML/AI engineers working in fintech already know Python.

SQLAlchemy handles the ORM layer. Some people argue against ORMs for performance-critical applications, and they're right for high-scale production systems. But for a local development sandbox, the productivity gain from declarative models outweighs raw SQL performance.

Redis serves as both a cache and a session store. Account balance queries hit Redis first, falling back to PostgreSQL on cache misses. This mirrors how production banking systems work—hot data in memory, cold data in persistent storage.

The Data Model

The schema follows standard banking conventions:

Data Model
Data Model

Foreign keys enforce referential integrity. Transactions that reference non-existent accounts get rejected at the database level, not in application code.

API Design Decisions

The API follows RESTful conventions with a few opinionated choices:

Idempotency keys: All state-changing operations accept an optional X-Idempotency-Key header. Send the same key twice, get the same result without duplicate operations. This prevents double-charging scenarios during network retries.

Pagination: List endpoints return 50 items by default with cursor-based pagination. I chose cursor pagination over offset pagination because it handles concurrent writes gracefully—no duplicate or missing items when records are inserted during pagination.

Error responses: Standard HTTP status codes with structured error objects:

code 
{  "error": {    "code": "INSUFFICIENT_FUNDS",    "message": "Account balance too low for transaction",    "details": {      "available_balance": 450.00,      "requested_amount": 500.00    }  }}

Versioning: API endpoints are versioned (/api/v1/...) from day one. Breaking changes go in v2, allowing gradual migration.

The CLI Tool

The command-line interface handles common development tasks:

code 
# Seed database with 100 customers, each having 2 accountsdevbank seed --customers 100 --accounts-per-customer 2# Generate transaction history for last 30 daysdevbank generate-transactions --days 30# Reset everything to clean statedevbank reset --confirm# Create specific test scenariosdevbank scenario fraud-detectiondevbank scenario high-value-transfers

Scenarios are predefined test cases. The fraud-detection scenario creates suspicious transaction patterns (rapid sequential transfers, round-number amounts, cross-border transfers). The high-value-transfers scenario generates transactions above typical AML thresholds.

This beats manually crafting test data through Postman or writing custom scripts for each project.

Docker Setup

Getting started takes under 5 minutes:

code 
git clone https://github.com/ranjankumar-gh/devbanksdkcd devbanksdkdocker-compose up -d

The compose file orchestrates three containers:

  • PostgreSQL with initialized schema
  • Redis with persistence enabled
  • FastAPI server with auto-reload for development

Health checks ensure services start in the correct order. The API server waits for PostgreSQL to accept connections before running migrations.

Environment variables control configuration:

code 
DATABASE_URL: postgresql://devbank:devbank@postgres:5432/devbankREDIS_URL: redis://redis:6379/0API_HOST: 0.0.0.0API_PORT: 8000LOG_LEVEL: INFO

All defaults work out of the box. Override them by creating a .env file.

Security Considerations

This is a development tool, not a production system. It makes deliberate security tradeoffs:

No authentication by default: APIs are wide open. Anyone on localhost can create accounts and move money. This is intentional—authentication adds friction during development. You can enable JWT authentication via environment variable if needed.

Synthetic data only: All generated data is completely fake. SSNs use test ranges, credit card numbers use test prefixes (4000, 5100, etc.), account numbers are random sequences. None of it validates on real banking systems.

No encryption: Data isn't encrypted at rest or in transit. Again, fine for local development, unacceptable for production.

The README includes a prominent warning: "This tool is for development only. Never use it with real financial data or deploy it in production environments."

What's Next

I'm actively working on several enhancements:

Webhook simulation: Trigger callbacks for transaction events, just like real banking APIs do. This helps test asynchronous workflows.

GraphQL API: Some developers prefer GraphQL over REST. Adding a GraphQL layer alongside the REST API would broaden compatibility.

Fraud detection sandbox: Generate labeled fraud scenarios for training ML models. Realistic synthetic fraud data is surprisingly hard to find.

Multi-currency support: Right now everything is USD. Adding EUR, GBP, INR with realistic exchange rates would help test international payments.

Integration tests: Export Postman/Insomnia collections with pre-built test suites. Developers could import these and validate their integrations immediately.

Why Open Source

I considered keeping this private or building a SaaS product around it. But the fintech community benefits from shared tooling. Stripe's success partly came from excellent developer experience—easy testing, clear documentation, minimal friction.

Making DevBankSDK open source means:

  • Developers can inspect the code to understand exactly how it works
  • Contributions improve it faster than I could alone
  • No vendor lock-in or pricing concerns
  • Educational value for people learning fintech systems

I've benefited enormously from open-source tools throughout my career. This is one small way to contribute back.

Contributing

The project needs help in several areas:

  • Documentation: More examples, integration guides, architecture explanations
  • Testing: Unit tests, integration tests, load testing
  • Features: Additional API endpoints, data scenarios, language SDKs
  • Bug fixes: Error handling, edge cases, validation logic

If any of this sounds interesting, check out the contributing guide.

Getting Started

Clone the repository and follow the quickstart:

code 
git clone https://github.com/ranjankumar-gh/devbanksdkcd devbanksdkdocker-compose up -d# Wait for services to start (~30 seconds)# API docs available at http://localhost:8000/docs

The interactive docs let you test every endpoint through your browser. Create a customer, open an account, make a transfer—all without writing code.

For programmatic access:

code 
import requests# Create a customerresponse = requests.post('http://localhost:8000/api/v1/customers', json={    "first_name": "John",    "last_name": "Doe",    "email": "john@example.com",    "date_of_birth": "1990-01-01"})customer_id = response.json()['customer_id']# Open an accountresponse = requests.post('http://localhost:8000/api/v1/accounts', json={    "customer_id": customer_id,    "account_type": "checking",    "initial_deposit": 1000.00})account_id = response.json()['account_id']

Final Thoughts

Building DevBankSDK taught me that good developer tools don't need to be complex. The entire codebase is under 2,000 lines of Python. Docker handles deployment complexity. FastAPI generates documentation automatically. Faker creates realistic data.

What matters is reducing friction. Every minute spent configuring external sandboxes or mocking APIs is a minute not spent building your actual product. DevBankSDK eliminates that friction.

If you're building anything that touches banking APIs—payment processing, account aggregation, financial analytics—give it a try. Clone the repo, spin it up, and let me know what you think.

And if you find it useful, give it a star on GitHub ⭐. It helps others discover the project and motivates continued development.

Repository: https://github.com/ranjankumar-gh/devbanksdk

Issues/Feedback: https://github.com/ranjankumar-gh/devbanksdk/issues

Author: Ranjan Kumar | @ranjankumar-gh