Payment Service

A robust, atomic, and idempotent payment processing backend built with Django and Django REST Framework, focusing on financial correctness, concurrency safety, and auditability.

Table of Contents

• Features
• Tech Stack
• Prerequisites
• Installation & Local Setup
• Docker Deployment
• API Documentation
• Architecture & Design
• Running Tests
• Project Structure
• Future Roadmap

---

Features

• Account Management: Create and manage multi-currency accounts.
• Immutable Transactions: Ledger-style credit and debit operations that cannot be modified or deleted.
• Atomic Transfers: Safe money movement between accounts with full rollback on failure.
• Financial Correctness:
  • Strict overdraft prevention (balance never drops below zero).
  • Decimal arithmetic for precision (no floating-point errors).
• Concurrency Safety: Row-level locking (select_for_update) to prevent race conditions.
• Idempotency: Built-in protection against duplicate requests using unique idempotency keys.
• Audit Logging: Comprehensive event emission for all financial activities.

---

Tech Stack

• Language: Python 3.11+
• Framework: Django 4.x & Django REST Framework
• Database: SQLite (Default) / PostgreSQL (Ready)
• Documentation: OpenAPI 3.0 / Swagger UI
• Containerization: Docker & Docker Compose
• Utilities: python-dotenv, dj-database-url

---

Prerequisites

• Python: Version 3.11 or higher
• pip: Python package installer
• Docker (Optional, for containerized run)
• Git (for version control)

---

Installation & Local Setup

Follow these steps to set up the project locally for development.

1. Clone the Repository

git clone <repository-url>
cd Payment-Service

2. Create a Virtual Environment

Isolate dependencies by creating a virtual environment.

Windows:

python -m venv .venv
.\venv\Scripts\activate

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file in the project root to configure the application.

# Create .env file
touch .env

Add the following configuration to .env:

DEBUG=True
SECRET_KEY=your-secure-secret-key-development-only
DATABASE_URL=sqlite:///db.sqlite3
ALLOWED_HOSTS=localhost,127.0.0.1

5. Apply Database Migrations

Initialize the database schema.

python manage.py migrate

6. Create Superuser (Optional)

To access the Django Admin panel, you need a superuser account.

python manage.py createsuperuser

Follow the prompts to set a username, email, and password.

7. Start the Development Server

python manage.py runserver

The service will be available at http://localhost:8000/.

---

Docker Deployment

Run the complete application stack using Docker.

Build and Run

docker-compose up --build

This command builds the image and starts the service on port 8000.

Stop the Service

docker-compose down

---

API Documentation

The specificaiton is available in standard OpenAPI 3.0 format.

Type	URL / Path	Description
Swagger UI	http://localhost:8000/api/docs/	Interactive API explorer
OpenAPI Schema	http://localhost:8000/api/schema/	Dynamic JSON schema
Static File	openapi.yaml	Static YAML specification file included in repo

API Documentation Writing Options

• You can write the openapi.yaml file manually as it will be more organized and more readable having swagger schemas on a seperate organized folder.
• You can use python manage.py spectacular --file schema.yaml to generate the OpenAPI schema from the code automatically, which will generate a seperate schema file schema.yaml matching the code and representing openapi.yaml.

---

Running Tests

The project includes a comprehensive test suite covering standard flows, edge cases, and error conditions.

# Run all tests
python manage.py test accounts

# Run tests with verbosity
python manage.py test accounts -v 2

# Run tests with Coverage Report
coverage run --source='.' manage.py test
coverage report

Coverage includes:

• Account creation & retrieval
• Credit & Debit atomicity
• Overdraft prevention logic
• Idempotency (duplicate key handling)
• Transfer atomicity & rollback integrity

---

Project Structure

Payment-Service/
├── accounts/                 
│   ├── migrations/           # DB schema changes
│   ├── tests/                # Comprehensive tests
│   │   ├── __init__.py
│   │   ├── test_api.py       # Integration tests for APIs
│   │   └── test_services.py  # Unit tests for services
│   ├── exceptions.py         # Custom exceptions
│   ├── models.py             # Database models
│   ├── serializers.py        # Data serialization & validation
│   ├── services.py           # Core business logic (Atomic transactions)
│   ├── signals.py            # Event signals
│   ├── urls.py               # URL routing
│   └── views.py              # API Controllers
├── payment_service/          # Project configuration
│   ├── settings.py           # Django settings
│   ├── urls.py               # Main routing
│   └── wsgi.py               # WSGI entry point
├── swagger_schemas/          # Split API specifications
├── .env                      # Environment variables
├── boltfile.py               # Bolt task runner configuration
├── Dockerfile                # Docker build instructions
├── docker-compose.yml        # Container orchestration
├── manage.py                 # CLI entry point
├── openapi.yaml              # Swagger API Spec
├── requirements.txt          # Production dependencies
├── requirements-dev.txt      # Development dependencies
└── README.md                 # Project documentation

---

Features that will be added soon (WIP)

• Add Frontend for the service

Future Roadmap

Potential Technical enhancements for the next iteration:

1. Add Authorization/Authentication: Secure the APIs with jwt-token-based authentication.
2. PostgreSQL Migration: Switch to PostgreSQL for production to leverage better concurrent performance and JSONB support.
3. Async Event Processing: Move event logging to a background worker (Celery/Redis) to reduce request latency.
4. Rate Limiting: Add throttling to prevent API abuse.
5. Multi-Currency Support: Integrate an exchange rate service for cross-currency transfers.
6. Pagination: Add cursor-based pagination for large transaction history lists.
7. Load tests: Add load tests using Locust.

Potential Business enhancements for the next iteration:

1. Support Scheduled Transactions: Payroll, subscriptions, rent Cron-driven execution.
2. Support Feature Flags: Enable/disable transfers, credits, debits dynamically.
3. Support Multi-Currency & Money Realism: Integrate an exchange rate service for cross-currency transfers and Enforce valid ISO currencies.
4. Soft Account Lock: Temporarily freeze an account without deleting it.
5. Receive Monthly Report: Receive a monthly report on email as PDF/EXCEL files with all the transactions.
6. Balance Snapshots: Periodic snapshots to speed up reads, Rebuild balance from ledger if corruption is suspected.
7. Handle currency difference EGP VS USD when doing transfer