mwaiseghegift/python-mpesa-telegram-checkout

# M-Pesa Telegram Checkout A Telegram bot that sells products/services and collects payment via Safaricom's M-Pesa Daraja STK Push. Orders are tracked server-side and only marked paid after a verified Daraja callback — see `docs/python_mpesa_telegram_checkout_guide.md` for the full design and `docs/overview.md` for a project summary. ## Stack - FastAPI (M-Pesa callback endpoint + health check) - python-telegram-bot (bot commands and conversation flow) - SQLAlchemy (async) with SQLite by default, Postgres optional - httpx (Daraja OAuth, STK Push, STK Query) ## Quick start 1. Create a virtual environment and install dependencies: ```powershell python -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` 2. Copy the example environment file and fill in your credentials: ```powershell cp .env.example .env ``` At minimum you need a `TELEGRAM_BOT_TOKEN` (from BotFather) and Daraja sandbox credentials (`MPESA_CONSUMER_KEY`, `MPESA_CONSUMER_SECRET`, `MPESA_SHORTCODE`, `MPESA_PASSKEY`). By default the app uses a local SQLite file (`checkout.db`), so no database setup is required to start. 3. Run the app: ```powershell uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload ``` 4. Check it's up: ```powershell curl 127.0.0.1 ``` 5. Open your bot in Telegram and run `/start`. The M-Pesa callback (`/webhooks/mpesa/ `) must be reachable over public HTTPS for Daraja to reach it — use a tunnel during sandbox testing (see the guide, section 10). ## Configuration All configuration is read from `.env` (see `.env.example`): | Variable | Purpose | | --- | --- | | `TELEGRAM_BOT_TOKEN` | Bot token from BotFather | | `DB_BACKEND` | `sqlite` (default) or `postgres` | | `SQLITE_PATH` | SQLite file path, used when `DB_BACKEND=sqlite` | | `DATABASE_URL` | Postgres connection string, required when `DB_BACKEND=postgres` | | `MPESA_ENV` | `sandbox` or `production` | | `MPESA_CONSUMER_KEY` / `MPESA_CONSUMER_SECRET` | Daraja app credentia …