{"id":26021100,"url":"https://github.com/isodevmate/nodejs-mpesa","last_synced_at":"2026-04-13T20:32:43.646Z","repository":{"id":277625465,"uuid":"639508029","full_name":"IsoDevMate/nodejs-mpesa","owner":"IsoDevMate","description":"NodeJS M-Pesa Integration This project demonstrates the integration with Safaricom's Daraja API for M-Pesa payment services, focusing on STK Push and QR code generation using the Daraja sandbox environment. It includes features like Firebase Cloud Messaging for push notifications, token management, transaction logging, and Docker containerization. ","archived":false,"fork":false,"pushed_at":"2025-02-15T01:08:46.000Z","size":4976,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-06T08:40:03.467Z","etag":null,"topics":["checkout","firebase","firebase-admin","javascript","mpesa","mpesa-payments","nodejs"],"latest_commit_sha":null,"homepage":"https://nodejs-mpesa.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IsoDevMate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-11T15:39:39.000Z","updated_at":"2025-02-21T11:23:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"01a14273-b404-4647-865e-7df8c24e9cb8","html_url":"https://github.com/IsoDevMate/nodejs-mpesa","commit_stats":null,"previous_names":["isodevmate/nodejs-mpesa"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/IsoDevMate/nodejs-mpesa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IsoDevMate%2Fnodejs-mpesa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IsoDevMate%2Fnodejs-mpesa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IsoDevMate%2Fnodejs-mpesa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IsoDevMate%2Fnodejs-mpesa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IsoDevMate","download_url":"https://codeload.github.com/IsoDevMate/nodejs-mpesa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IsoDevMate%2Fnodejs-mpesa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31770720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checkout","firebase","firebase-admin","javascript","mpesa","mpesa-payments","nodejs"],"created_at":"2025-03-06T08:33:29.689Z","updated_at":"2026-04-13T20:32:43.638Z","avatar_url":"https://github.com/IsoDevMate.png","language":"JavaScript","readme":"# NodeJS M-Pesa Integration\n\nThis project demonstrates integration with Safaricom's Daraja API for M-Pesa payment services, specifically focused on STK Push and QR code generation using the Daraja sandbox environment.\n\n## Features\n\n- M-Pesa STK Push initiation\n- QR Code generation for payments\n- Firebase Cloud Messaging for push notifications\n- Token storage and management\n- Transaction logging and retrieval\n- Callback URL handling\n- Docker containerization\n- Load tested and optimized for high traffic\n\n## Prerequisites\n\n- Node.js (v20 recommended)\n- MongoDB\n- Safaricom Daraja API credentials (consumer key, consumer secret, passkey)\n- Firebase Admin SDK setup for push notifications\n\n## Environment Variables\n\nCreate a `.env` file in the root directory with the following variables:\n\n```\nPORT=5050\nMPESA_PAYBILL=your_paybill_number\nMPESA_CONSUMER_KEY=your_consumer_key\nMPESA_CONSUMER_SECRET=your_consumer_secret\nMPESA_PASSKEY=your_passkey\nDATABASE_URI=your_mongodb_connection_string\nCALLBACK_URL=your_callback_url\n```\n\n## Installation and Setup\n\n1. Clone the repository\n2. Install dependencies:\n   ```\n   npm install\n   ```\n3. Place your Firebase Admin SDK JSON file in the root directory\n4. Start the application:\n   ```\n   npm start\n   ```\n\n## Docker Deployment\n\nA Dockerfile is included for containerization:\n\n```\ndocker build -t mpesa-node-app .\ndocker run -p 5050:5050 --env-file .env mpesa-node-app\n```\n\n## API Endpoints\n\n### STK Push\n```\nPOST /api/stk\nBody: {\n  \"amount\": \"1\",\n  \"phone\": \"254XXXXXXXXX\"\n}\n```\n\n### Generate QR Code\n```\nPOST /api/generateqr\nBody: {\n  \"amount\": 100,\n  \"AccountReference\": \"REF123\"\n}\n```\n\n### Save FCM Token\n```\nPOST /save-token\nBody: {\n  \"token\": \"firebase_token\",\n  \"userId\": \"user_id\"\n}\n```\n\n### Send Push Notification\n```\nPOST /send-notification\nBody: {\n  \"title\": \"Notification Title\",\n  \"body\": \"Notification Body\",\n  \"userId\": \"user_id\"\n}\n```\n\n### Other Endpoints\n- `POST /api/myCallBack` - Callback URL for M-Pesa\n- `GET /api/allTransactions` - Fetch all transactions\n- `GET /api/oneTransaction/:id` - Fetch specific transaction\n- `POST /api/stkpushquery` - Query STK push status\n- `POST /api/register` - Register URLs with M-Pesa\n- `POST /api/c2b/v1/confirm` - C2B confirmation URL\n- `POST /api/c2b/v1/validate` - C2B validation URL\n\n## Load Testing\n\nThe project includes K6 scripts for load testing different scenarios:\n- Basic STK push test\n- Combined STK push and query test with various load stages\n\nTo run the tests:\n```\nk6 run tests/load-test.js\n```\n\n### Performance Notes\n\nThe application has been spike and stress tested with excellent results under normal conditions. However, under extremely high load, the Daraja API may return 429 (Too Many Requests) errors. Key observations:\n\n- The application performs well under moderately high load\n- At peak stress levels, some requests may fail with 429 errors\n- No performance degradation was observed in the application itself\n- Database connections remained stable during high-load periods\n\n### Rate Limiting Considerations\n\nTo handle rate limiting (429 errors):\n\n1. Implement exponential backoff and retry logic\n2. Add request queuing for high-traffic periods\n3. Consider implementing a circuit breaker pattern\n4. Monitor API usage to stay within Safaricom's limits\n5. Add logging for failed requests to track patterns\n\n## Note on Push Notifications\n\nThe code includes a Firebase Cloud Messaging integration for sending push notifications to users. Tokens are stored in MongoDB and associated with user IDs.\n\n## Error Handling\n\nThe API includes proper error handling for:\n- Failed token generation\n- Invalid tokens (auto-deletion from database)\n- Failed notifications\n- Invalid M-Pesa responses\n- Rate limiting (429) errors\n\n## Security Considerations\n\n- Store sensitive credentials in environment variables\n- Use HTTPS in production\n- Validate all input data\n- Handle errors gracefully without exposing sensitive information\n- Implement proper rate limiting to prevent abuse\n\n## License\n\nThis project is intended for learning purposes. Please check Safaricom's terms of service before using in production.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisodevmate%2Fnodejs-mpesa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisodevmate%2Fnodejs-mpesa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisodevmate%2Fnodejs-mpesa/lists"}