A production-style banking backend built with FastAPI, PostgreSQL, SQLAlchemy, and Redis, focused on the engineering problems that make financial systems reliable rather than treating banking as a CRUD exercise.
Engineering focus: financial correctness, concurrency control, idempotency, rate limiting, authentication, auditability, and failure-safe transaction processing.
Client
│
│ POST /transactions
│ Authorization + Idempotency-Key
▼
FastAPI API Layer
│
├── Authenticate request
├── Check Redis idempotency record
│ └── existing result → return cached response
│
▼
Transaction Service
│
├── Validate amount
├── Validate sender / receiver
├── Validate account state
├── Check sufficient balance
├── Reject self-transfer
│
├── PostgreSQL row-level locking
│ SELECT ... FOR UPDATE
│
├── Debit sender
├── Credit receiver
├── Create transaction record
├── Create debit ledger entry
├── Create credit ledger entry
├── Create audit record
│
├── COMMIT
│
└── Cache successful response in Redis
The project is deliberately presented from the hardest engineering concerns down to the supporting backend functionality.
A bank account is shared mutable state. Concurrent requests must not be allowed to update the same balance using stale state.
The transfer workflow uses PostgreSQL row-level locks with:
SELECT ... FOR UPDATEThe sender and receiver account rows are selected in a deterministic order and locked before balance mutation.
Goal:
Concurrent transfer requests
↓
PostgreSQL row locks
↓
Conflicting updates are serialized
↓
No stale balance update / double-spend
A transfer is treated as one database transaction.
These operations are coordinated together:
Sender balance update
+
Receiver balance update
+
Transaction record
+
Debit ledger entry
+
Credit ledger entry
+
Audit record
The service explicitly commits the operation only after the workflow succeeds. Expected application failures and unexpected exceptions trigger a database rollback.
Failure
↓
ROLLBACK
↓
No partially committed transfer state
For a successful transfer, the system creates two ledger entries:
Sender account → DEBIT
Receiver account → CREDIT
The current balance answers what the account contains now; the ledger provides the transaction trail behind that state.
The repository also contains reconciliation logic intended to compare total debit and credit amounts.
Transaction requests require an idempotency key.
First request
↓
Process transfer
↓
Commit
↓
Store successful response in Redis
Retry with same key
↓
Redis lookup
↓
Return previously stored response
This protects the transaction endpoint from duplicate processing caused by client retries, timeouts, or repeated submissions using the same key.
The project implements a Redis-backed sliding-window limiter.
The rate-limit state contains:
previous_count
current_count
window_start
The implementation uses Redis optimistic transactions:
WATCH
↓
Read current state
↓
Calculate effective request count
↓
MULTI
↓
Write new state
↓
EXEC
The current implementation uses a 60-second window and a configured request limit. It is applied to login requests and the repository also contains reusable user-scoped dependency support for endpoint rate limiting.
When the effective limit is exceeded:
429 Too Many RequestsImplemented authentication features:
- JWT access tokens
- JWT refresh tokens
- explicit access/refresh token type validation
- token expiration
- protected endpoints through FastAPI dependencies
- bcrypt password hashing
The access token carries the authenticated user identifier and token type, and the backend verifies both the JWT signature and token type before loading the user.
Refresh tokens are persisted as database sessions containing:
user_id
refresh_token
device_name
created_at
expires_at
The login flow also captures the request User-Agent, allowing the session to retain device information.
The refresh flow is:
Verify JWT refresh token
↓
Check Redis blacklist
↓
Find stored refresh session
↓
Create new access token
↓
Create new refresh token
↓
Blacklist old token
↓
Replace stored session token
↓
Commit
Logout performs:
Verify refresh token
↓
Check whether token is already invalidated
↓
Blacklist token in Redis
↓
Delete refresh session from PostgreSQL
↓
Commit
Redis acts as a fast lookup layer for invalidated refresh tokens.
Registration supports email verification using short-lived Redis tokens:
Register
↓
Generate verification token
↓
Store token in Redis with TTL
↓
Send verification email through SMTP
↓
User opens verification link
↓
Mark email as verified
↓
Delete token
The verification-token TTL is enforced by Redis.
Password recovery follows a similar short-lived-token workflow:
Forgot password
↓
Generate reset token
↓
Store token in Redis
↓
Send reset link
↓
Validate token
↓
Hash new password
↓
Update PostgreSQL
↓
Delete reset token
Implemented capabilities include:
- user registration
- email validation
- email uniqueness checks
- phone-number uniqueness checks
- bcrypt password hashing
- email verification state
- lookup by user ID
- lookup by email
- lookup by phone
- password reset
Authenticated users can create accounts.
The account model contains:
Account ID
Account Number
Owner User ID
Account Type
Status
Balance
Created At
Account numbers are generated using a PostgreSQL sequence-backed identifier plus configured prefixes.
Before modifying financial state, the transfer service validates:
- amount must be positive
- sender account must exist
- receiver account must exist
- sender account must not be frozen
- receiver account must not be frozen
- sender must have sufficient balance
- sender and receiver cannot be the same account
Each transfer creates a transaction record containing:
Transaction ID
Amount
Transaction Reference
Sender Account
Receiver Account
Status
Description
Created At
Transaction references are generated from a PostgreSQL sequence-backed identifier and application configuration.
Authenticated users can retrieve their transaction history with:
- transaction reference
- amount
- sender account number
- receiver account number
- transaction status
- description
- creation timestamp
Financial operations create an audit record containing:
User
Transaction
Action
Description
Timestamp
The audit record is created as part of the same database transaction as the transfer.
API / Controllers
↓
Service Layer
↓
Repository Layer
↓
PostgreSQL / Redis
Responsible for:
- HTTP routes
- request/response schemas
- dependency injection
- authentication dependencies
- rate-limit integration
Responsible for:
- business rules
- authentication workflows
- fund-transfer orchestration
- commit / rollback boundaries
- coordinating database and Redis operations
Responsible for:
- database queries
- inserts and updates
- row locking
- Redis persistence
- refresh-session persistence
- audit persistence
users
│
├────────► accounts
│ │
│ └────────► transactions
│ │
│ ├────────► ledger
│ └────────► audit_log
│
└────────► refresh_sessions
| Entity | Responsibility |
|---|---|
users |
Identity, credentials, verification state |
accounts |
Ownership, type, status, current balance |
transactions |
Transfer-level financial records |
ledger |
Debit / credit accounting entries |
Audit_log |
Financial activity traceability |
refresh_sessions |
Refresh-token session state |
Redis supports several independent pieces of application state:
| Redis capability | Purpose |
|---|---|
| Idempotency | Cache a successful transaction response by idempotency key |
| Rate limiting | Maintain sliding-window request state |
| Refresh blacklist | Reject invalidated refresh tokens quickly |
| Email verification | Store short-lived verification tokens |
| Password reset | Store short-lived password-reset tokens |
This keeps frequently accessed, short-lived state in Redis while PostgreSQL remains the primary source of persistent banking state.
Validation / business-rule failure
↓
db.rollback()
↓
HTTP error
Unexpected exception
↓
db.rollback()
↓
HTTP 500 response
↓
No partial financial state committed
This is particularly important for fund transfers because a transfer updates multiple related records.
The repository contains focused checks around the Redis and rate-limiting components, including:
- rate-limit behavior
- Redis optimistic transaction behavior using
WATCH - transaction-history test scaffolding
The Redis test demonstrates the conflict path where another client changes a watched key before EXEC, producing a Redis watch conflict.
POST /register
POST /login
POST /refresh
POST /logout
POST /forgot_password
GET /verify-email
POST /reset-passwordPOST /create_accountPOST /transactions
GET /transactions_history- Python
- FastAPI
- Uvicorn
- PostgreSQL
- SQLAlchemy
- Redis
- JWT
- bcrypt password hashing
- SMTP
- Pydantic
- Git
- GitHub
Banking-API/
│
├── app/
│ ├── api/
│ │ ├── AccountCreate.py
│ │ ├── Transactions.py
│ │ ├── User_login.py
│ │ └── User_register.py
│ │
│ ├── core/
│ │ ├── config.py
│ │ ├── redis_client.py
│ │ └── security.py
│ │
│ ├── db/
│ │
│ ├── dependencies/
│ │ └── rate_limit.py
│ │
│ ├── models/
│ │ ├── accounts.py
│ │ ├── audit.py
│ │ ├── ledger.py
│ │ ├── refresh_sessions.py
│ │ ├── transactions.py
│ │ └── user.py
│ │
│ ├── repositries/
│ │ ├── Transaction_repositries.py
│ │ ├── account_repositrie.py
│ │ ├── audit_repositry.py
│ │ ├── login_repositry.py
│ │ ├── redis_ratelimiter_service.py
│ │ ├── redis_repositries.py
│ │ └── user_repositries.py
│ │
│ ├── schemas/
│ │
│ ├── services/
│ │ ├── AccountCreation.py
│ │ ├── Transaction_services.py
│ │ ├── auth_services.py
│ │ ├── email_service.py
│ │ ├── hashing.py
│ │ ├── login_service.py
│ │ └── rate_limiter_service.py
│ │
│ └── tests/
│ ├── test_rate_limiter.py
│ ├── test_redis_transactions.py
│ └── test_transaction_history.py
│
└── requirements.txt
git clone https://github.com/GenZ-CODER-X/Banking-API.git
cd Banking-APIpython -m venv venv
source venv/bin/activateWindows:
venv\Scripts\activatepip install -r requirements.txtCreate a .env file matching the settings expected by app/core/config.py.
DATABASE_URL=<postgresql-connection-string>
SECRET_KEY=<strong-secret>
ACCESS_TOKEN_EXPIRE_MINUTES=<minutes>
REFRESH_TOKEN_EXPIRE_MINUTES=<minutes>
ALGORITHM=<jwt-algorithm>
SECRET_PREFIX_STR=<prefix>
SECRET_PREFIX_INT=<integer>
SECRET_PREFIX_TRANSACTION=<transaction-prefix>
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
SMTP_HOST=<smtp-host>
SMTP_PORT=<smtp-port>
SMTP_EMAIL=<sender-email>
SMTP_PASSWORD=<smtp-password>
BACKEND_URL=http://localhost:8000uvicorn app.main:app --reloadBecause a balance is shared mutable state.
Without locking, two concurrent requests can read the same balance before either update becomes visible to the other request.
With row-level locking:
Request A ──► lock account row ──► update ──► commit
Request B ──► waits for lock ─────► read latest state
The database therefore participates directly in maintaining financial consistency.
Clients can retry after a timeout even when the original transaction succeeded.
The idempotency key lets the backend distinguish:
New payment
from:
Retry of an already processed request
The balance represents current state.
The ledger represents the accounting trail behind that state.
Together they provide both:
Current balance
+
Historical financial activity
The current repository is the banking core. The following are planned extensions and are not claimed as implemented here.
- exponential backoff and retry handling
- payment state machine
- provider failure recovery
- webhooks
- reconciliation
- transaction events
- outbox pattern
- Kafka / event streaming
- asynchronous downstream consumers
- real-time fraud scoring
- behavioral and temporal features
- IP / device / session context
- ML-based transaction risk scoring
- rule + model decisioning
Banking API
↓
Reliable Payment Infrastructure
↓
Event-Driven Payments
↓
Real-Time Fraud Intelligence
This project treats banking primarily as a correctness and reliability problem rather than a collection of CRUD endpoints.
Authentication
+
Concurrency
+
ACID Transactions
+
Idempotency
+
Rate Limiting
+
Ledger Design
+
Auditability
+
Redis State Management
+
Failure Handling
=
Reliable Banking Backend
Repository: https://github.com/GenZ-CODER-X/Banking-API