RobertTRL/mpesa-app

A full-stack M-Pesa payment application built with Safaricom Daraja API, featuring STK Push payments, a QR code generator, real-time transaction status updates, callback handling, and seamless payment verification. # M-Pesa Prompting App A focused, production-ready web application for triggering M-Pesa STK Push (Lipa Na M-Pesa) payments and generating M-Pesa QR codes. Built with a React frontend and a Python serverless backend deployed on Vercel. The customer enters their phone number and an amount, receives a PIN prompt on their phone, and the UI updates in real time when Safaricom confirms the payment — no page refresh needed. Alternatively, customers can scan a dynamically generated QR code directly from the M-Pesa app. --- ## Table of Contents - Overview - Features - Tech Stack - Architecture - Project Structure - Installation - Environment Variables - Database Schema - Usage - API Reference - Deployment - Known Limitations - Contributing - License --- ## Overview **What it does:** Presents a payment form where a user enters a Safaricom phone number and an amount. On submission the backend calls Safaricom's Daraja STK Push API, which sends a PIN prompt to the customer's phone. The frontend subscribes to the `mpesa_payments` table via Supabase Realtime and navigates to a success or failure screen the moment Safaricom's callback updates the database record — with no polling required. Alongside the STK Push form, the app generates a live M-Pesa QR code for the entered amount. The QR is debounced — it regenerates 1.2 seconds after the user stops typing and clears immediately when the amount changes. Customers can scan the QR with their M-Pesa app as an alternative to the PIN prompt flow. QR payments are received via a registered C2B callback and saved to a dedicated `c2b_payments` table. **Problem it solves:** Wires together the three moving parts of a live STK Push flow — token management, payment initiation, and asynchronous callback handling — into a deployable, end-to-end web app. It also integrates the Daraja QR Code API and C2B callback registration for a complete dual-payment-method experience. **Intended users:** Developers and operators in Kenya who need a w …