skmwaura/mpesa-wrapper-api

# mpesa-wrapper-api Go REST API wrapper for Safaricom M-Pesa Daraja APIs. Provides a clean interface for STK Push (Lipa Na M-Pesa), C2B (Customer to Business), and Transaction Status queries — with PostgreSQL-backed persistence and AES-256-CBC field encryption. ## Stack - **Go 1.23** · **Gin** web framework · **GORM** ORM - **PostgreSQL** — database-first architecture (stored procedures & functions) - **AES-256-CBC** field-level encryption - **Docker** multi-stage build ## Architecture ``` routes/ → controllers/ → services/ → db/ ``` | Layer | Role | |---|---| | `routes/route.go` | All route registration | | `controllers/` | Thin Gin handlers — extract params, call service, return `APIResponse` | | `services/` | Business logic — Safaricom API calls + DB persistence | | `models/` | Request/response structs, DB result structs | | `db/` | GORM connection + stored procedure/function helpers | | `utils/` | HTTP client, CORS, logging, M-Pesa helpers | | `config/` | Environment configuration from `env.json` | All database reads go through PostgreSQL functions (`fnc_`), and all writes go through stored procedures (`spo_`). ## Getting Started ### Prerequisites - Go 1.23+ - PostgreSQL 14+ - M-Pesa Daraja API credentials (developer.safaricom.co.ke) ### 1. Clone & Install Dependencies ```bash git clone cd mpesa-wrapper-api go mod download ``` ### 2. Configure Environment Copy the example config and fill in your values: ```bash cp config/env.example.json config/env.json ``` Edit `config/env.json` with your database and M-Pesa credentials. The file has two blocks — `development` and `production` — selected by the `GO_ENV` environment variable (defaults to `production`). ### 3. Set Up Database Create the PostgreSQL database: ```sql CREATE DATABASE mpesa_pay_db; ``` Run the SQL schema files in order from `db/schema/public/mpesa/`: ```bash # Tables (3xx) psql -d mpesa_pay_db -f db/schema/public/mpesa/300-tbl_mpesa_token.sql psql -d mpesa_pay_db -f db/schema/publ …