CipherRax/mpesa-commerce-api

E-Commerce APi with Mpesa as a payment method # E-commerce + M-Pesa API A production-grade, Amazon-style e-commerce backend built for the Kenyan market — full product catalog, cart, checkout, **M-Pesa Daraja STK Push payments**, PDF receipts, inventory/supplier management, and admin analytics. TypeScript, Express, PostgreSQL, Prisma. ``` Products → Inventory → Purchases → Sales/Orders → Customers → M-Pesa Payments → Receipts → Reports ``` --- ## Table of contents - Features - Tech stack - Architecture - Data model - Getting started - Environment variables - M-Pesa integration - API reference - Project structure - Design decisions - Testing the API - Deployment - Roadmap - License --- ## Features - 🛍️ **Amazon-style catalog** — search, filter by category/price, sort, pagination - 🛒 **Persistent cart** — server-side, survives across sessions/devices - 📦 **Order lifecycle** — `PENDING_PAYMENT → PAID → PROCESSING → SHIPPED → DELIVERED`, with automatic stock reservation and rollback on payment failure - 💰 **M-Pesa Daraja integration** — STK Push, async callback handling, active status polling fallback, and a built-in **mock mode** that simulates the entire payment flow with zero code changes needed to go live - 🧾 **Auto-generated PDF receipts** on successful payment - 📊 **Inventory management** — real-time stock, low-stock alerts, full movement audit trail (every stock change is logged with type + reference) - 🚚 **Purchases module** — suppliers, purchase orders, receive-to-restock workflow (separate from sales, mirrors real warehousing) - 👥 **Customer management** — profiles, addresses, admin directory with spend history - 📈 **Admin reports** — sales summary, revenue-by-day, top-selling products, inventory valuation, purchase spend - 🔐 **JWT auth** with role-based access (`CUSTOMER` / `STAFF` / `ADMIN`) - 📚 **Swagger/OpenAPI docs** generated from route annotations, live at `/api/docs` - 🔒 Strict TypeScript throughout — no implicit `any`, Prisma-generated types used end-to-end ## Tech stack | Layer | …