eliezerke/flask-mpesa-stk

Flask app for M-Pesa STK Push payments via Safaricom Daraja API - initiate, callback, status polling & dashboard. # Flask M-Pesa STK Push A lightweight Flask application that integrates **Safaricom Daraja API** for M-Pesa STK Push (Lipa Na M-Pesa Online) payments. It supports payment initiation, callback handling, real-time status polling, transaction storage in SQLite, and a simple dashboard with analytics. ## Features - Initiate M-Pesa STK Push requests - Handle Safaricom payment callbacks - Store transactions in SQLite with status tracking (`pending` / `success` / `failed`) - Real-time payment status polling endpoint - Clean checkout UI with form validation and loading states - Dashboard with payment history, status breakdown (pie chart), and successful volume by reference (bar chart) - Environment-based configuration via `.env` ## Project Structure ``` flask-mpesa-stk/ ├── app/ │ ├── __init__.py # Flask app & SQLAlchemy setup │ ├── config.py # App configuration │ ├── payload_stk.py # Access token + STK Push logic │ ├── routes.py # API & page routes │ └── templates/ │ ├── index.html # Main checkout page │ ├── donate.html # Donation-style UI (demo) │ └── dash.html # Transactions dashboard ├── models.py # Payment SQLAlchemy model ├── push.py # Entry point (creates tables + runs app) └── .gitignore ``` ## Prerequisites - Python 3.8+ - A Safaricom Developer Portal account - Consumer Key & Consumer Secret - Lipa Na M-Pesa Online Passkey - Business Shortcode (sandbox: `174379`) - A publicly reachable callback URL (use ngrok, Cloudflare Tunnel, etc. for local testing) ## Installation 1. **Clone the repository** ```bash git clone github.com cd flask-mpesa-stk ``` 2. **Create and activate a virtual environment** ```bash python -m venv venv source venv/bin/activate # Linux / macOS # or venv\Scripts\activate # Windows ``` 3. **Install dependencies** ```bash pip install flask flask-sqlalchemy python-d …