✅ Batch Management
- Create batches from CSV files or JSON API
- Real-time status tracking
- Automatic retry for failed transactions
- Webhook callbacks from providers
✅ Web Interface
- User authentication with JWT
- Dashboard with batch list
- CSV upload with drag-and-drop
- Transaction details view
✅ ERP Integration
- REST API for C# or other systems
- JSON-based batch creation
- Status polling
- Backend: Node.js, Express
- Database: PostgreSQL
- Authentication: JWT
- Frontend: HTML, CSS, JavaScript
- APIs: MTN MoMo, Airtel Money
- Node.js 14+ and npm
- PostgreSQL 12+
-
Clone or navigate to project directory
cd bulk-payment-system -
Install dependencies
npm install
-
Setup database
Create a PostgreSQL database:
createdb bulk_payments
Run the schema:
psql -U postgres -d bulk_payments -f sql/schema.sql
-
Configure environment
Copy
.env.exampleto.envand update values:cp .env.example .env
Update these critical values:
DATABASE_URL- Your PostgreSQL connection stringJWT_SECRET- Random secret key- MTN credentials (from MTN Developer Portal)
- Airtel credentials (from Airtel Developer Portal)
-
Start the server
Development mode:
npm run dev
Production mode:
npm start
-
Access the application
- Web UI: http://localhost:3000
- API: http://localhost:3000/api
- Email: admin@spacebera.com
- Password: admin123
bulk-payment-system/
├── sql/
│ └── schema.sql # Database schema
├── src/
│ ├── config/
│ │ └── db.js # Database connection
│ ├── models/
│ │ ├── userModel.js # User database operations
│ │ ├── batchModel.js # Batch database operations
│ │ └── itemModel.js # Item database operations
│ ├── providers/
│ │ ├── mtn.js # MTN MoMo API integration
│ │ ├── airtel.js # Airtel Money API integration
│ │ └── payout.js # Unified payout service
│ ├── services/
│ │ ├── csvService.js # CSV parsing
│ │ ├── batchService.js # Batch business logic
│ │ └── payoutService.js # Payout worker
│ ├── middlewares/
│ │ ├── authMiddleware.js # Authentication & authorization
│ │ └── errorMiddleware.js # Error handling
│ ├── routes/
│ │ ├── authRoutes.js # Auth endpoints
│ │ ├── batchRoutes.js # Batch endpoints
│ │ ├── webhookRoutes.js # Webhook endpoints
│ │ └── cronRoutes.js # Admin/cron endpoints
│ ├── utils/
│ │ ├── phoneUtils.js # Phone number utilities
│ │ └── validation.js # Validation functions
│ ├── app.js # Express app setup
│ └── server.js # HTTP server
├── public/
│ ├── css/
│ │ └── style.css # Styles
│ ├── js/
│ │ └── app.js # Frontend JavaScript
│ ├── index.html # Login page
│ ├── dashboard.html # Dashboard
│ ├── upload.html # CSV upload
│ └── batch-details.html # Batch details
├── .env.example # Environment template
├── .gitignore
├── package.json
└── README.md
POST /api/auth/login- User loginPOST /api/auth/logout- User logout
POST /api/batches- Create batch from JSONPOST /api/batches/upload-csv- Create batch from CSVGET /api/batches/:id- Get batch detailsGET /api/batches- List batchesGET /api/batches/template/csv- Download CSV template
POST /api/webhooks/mtn- MTN callbackPOST /api/webhooks/airtel- Airtel callback
POST /api/cron/run-payouts- Trigger payout processingGET /api/cron/status- System status
phone_number,amount,reference,description
0772123456,450000,DEC-2025-001,Site foreman salary
0783987654,1200000,DEC-2025-002,Engineer salary
0751234567,800000,DEC-2025-003,Store keeper salary- MTN: 077, 078, 076
- Airtel: 070, 075
- Go to https://momodeveloper.mtn.com/
- Sign up and create a subscription for Disbursements
- Generate API User and API Key
- Get your subscription key
- Go to https://developers.airtel.africa/
- Sign up and create an app
- Select Disbursements product
- Get Client ID and Client Secret
-
Environment
- Use production credentials from MTN & Airtel
- Set
NODE_ENV=production - Use strong
JWT_SECRET
-
Database
- Use managed PostgreSQL (AWS RDS, Digital Ocean, etc.)
- Enable SSL
- Regular backups
-
Server
- Use PM2 or systemd for process management
- Configure Nginx as reverse proxy
- Enable HTTPS with Let's Encrypt
-
Security
- IP whitelist for webhooks
- Rate limiting
- Regular security updates
The payout worker can be triggered:
- Manually via admin endpoint:
POST /api/cron/run-payouts - Automatically with a cron job (every minute):
* * * * * curl -X POST http://localhost:3000/api/cron/run-payouts -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
- Check
DATABASE_URLin.env - Ensure PostgreSQL is running
- Verify database exists
- Verify credentials in
.env - Check sandbox/production URL
- Review API logs in console
- Default password is
admin123 - Check database has user record
- Verify JWT_SECRET is set
ISC
For issues and questions, contact your system administrator or SMS Construction IT department.