danielmaina989/mpesa-payments-system

Production-grade M-Pesa STK Push payment system with async callbacks, idempotency, and reconciliation-ready architecture. # M-Pesa Payments & Reconciliation System A **production-grade M-Pesa STK Push payment system** built with Django, Django REST Framework, Celery, and Redis. This project demonstrates how to build **reliable, auditable, and scalable payment infrastructure** suitable for real businesses in Kenya and beyond. --- ## 🚀 Features ### Core Payment Flow - STK Push initiation - Secure webhook (callback) handling - Transaction lifecycle management: ``` INITIATED → PENDING → SUCCESS / FAILED ``` - Idempotent callback processing (safe against duplicate M-Pesa retries) ### Reliability & Scale - Asynchronous callback processing using Celery + Redis - Background task retries with exponential backoff - Graceful handling of malformed or unexpected webhook payloads ### Admin & Auditability - Django Admin dashboard for transactions - Transaction filtering by status, date, and phone number - Full audit trail of payment state changes ### Developer Experience - Environment-based configuration - Decimal-safe money handling - Clean separation of concerns (views, tasks, models) --- ## 🧠 Architecture Overview ``` ┌──────────────┐ │ Client UI │ └───────┬──────┘ │ ▼ Django REST API │ ▼ M-Pesa STK Push │ ▼ Callback Endpoint │ ▼ Celery Queue │ ▼ Redis Broker │ ▼ PostgreSQL / DB ``` --- ## 🔄 Payment Flow Explained 1. Client initiates payment via `/payments/stk-push/` 2. System sends STK Push request to M-Pesa 3. Transaction is saved as `PENDING` 4. M-Pesa sends callback to `/payments/callback/` 5. Callback is queued to Celery for async processing 6. Transaction is updated to `SUCCESS` or `FAILED` 7. Duplicate callbacks are safely ignored --- ## ⚠️ Failure Scenarios Handled - Duplicate callbacks from M-Pesa - Network retries and timeouts - Missing or malformed callback payloads - Worker restarts without data corruption --- ## 🔐 Security Considerations - Credentials loaded from environment variables - No secrets committed to version control - CSRF exempt webhook endpoint (re …