# mpesa-daraja-sdk
> ⚡ **Effortless M-Pesa integration** using Safaricom's Daraja API — built for developers, by developers.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
<!-- []() -->
---
## The Problem
Integrating Safaricom's **M-Pesa Daraja API** directly is **notoriously complex**:
- Confusing and inconsistent documentation
- Manual handling of OAuth2 tokens and security credentials
- Complex encryption and certificate management
- Different endpoints for sandbox vs production environments
- STK Push, C2B, B2C, balance — all feel like separate APIs
- Time-consuming setup that delays your time-to-market
For many developers and startups, this becomes a **huge barrier** to adopting M-Pesa payments in Kenya and beyond.
---
## The Solution
**`mpesa-daraja-sdk`** eliminates the complexity with a **clean, developer-friendly Python SDK** that:
- **Zero-config setup** — just add your credentials and go
- **Handles authentication automatically** — OAuth2, tokens, and security
- **Seamless environment switching** — sandbox ↔ production with one parameter
- **Pythonic interface** — clean methods that feel natural to Python developers
- **Batteries included** — everything you need for M-Pesa integration
- **Production-ready** — end goal is to be used by startups and enterprises across Kenya
### Supported Features
| Feature | Status | Description |
|---------|--------|-------------|
| **STK Push** | Ready | Lipa na M-Pesa Online payments |
| **C2B Payments** | Ready | Customer to Business transactions |
| **B2C Payments** | Ready | Business to Customer payouts |
| **Token Management** | Ready | Automatic OAuth2 handling |
| **Account Balance** | Coming Soon | Check account balances |
| **Transaction Reversal** | Coming Soon | Reverse transactions |
| 🎣 **Webhook Validation** | Coming Soon | Secure callback handling |
> Built on top of [Arlus/mpesa-py](https://github.com/Arlus/mpesa-py) with ❤️ — modernized, cleaned up, and restructured for today's developer needs.
---
## Quick Start
### Installation (coming soon)
```bash
pip install mpesa-daraja-sdk
```
---
## 📖 Complete Setup Guide
### 1. Get Safaricom Developer Account
1. Visit [developer.safaricom.co.ke](https://developer.safaricom.co.ke)
2. **Create account** and verify your email
3. **Create a new app** to get your credentials:
- Consumer Key
- Consumer Secret
### 2. Obtain Test Credentials (Sandbox)
1. Navigate to [Test Credentials Page](https://developer.safaricom.co.ke/test_credentials)
2. Copy the following credentials:
- **Shortcode** (Business number)
- **Initiator Name** (API operator username)
- **Initiator Password** (API operator password)
- **Security Credential** (Encrypted password)
### 3. Production Setup
For production deployment:
1. **Get Paybill/Till Number** from Safaricom
2. **Generate Security Credential** using Safaricom's public certificate
3. **Switch environment** to `"production"` in your client initialization
4. **Update callback URLs** to your production domain
---
### Security Best Practices
1. **Never commit credentials** to version control
2. **Use environment variables** for sensitive data
3. **Implement webhook validation** for callbacks
4. **Log transactions** for audit trails
5. **Monitor rate limits** and implement backoff strategies
6. **Use HTTPS** for all callback URLs
---
## 🤝 Contributing
We welcome contributions from the community! Here's how you can help:
### Ways to Contribute
- 🐛 **Report bugs** via GitHub Issues
- 💡 **Suggest features** for the roadmap
- 📖 **Improve documentation** and examples
- 🔧 **Submit pull requests** with fixes/features
- ⭐ **Star the repo** to show support
### Development Setup
```bash
# Clone the repository
git clone https://github.com/rafaeljohn9/mpesa-daraja-sdk.git
cd mpesa-daraja-sdk
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest tests/
```
### Code Standards
- Follow PEP 8 style guidelines
- Include type hints where appropriate
- Write comprehensive tests for new features
- Update documentation for any API changes
---
## 📞 Support & Community
- 📖 **Documentation**: [Full API docs coming soon]
- 🐛 **Issues**: [GitHub Issues](https://github.com/rafaeljohn9/mpesa-daraja-sdk/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/rafaeljohn9/mpesa-daraja-sdk/discussions)
- 📧 **Email**: <johnmkagunda@gmail.com>
---
## 🙏 Attribution & Thanks
This project began as a fork of the fantastic [`Arlus/mpesa-py`](https://github.com/Arlus/mpesa-py) by [@Arlus](https://github.com/Arlus).
**What we've added:**
- 🏗️ **Modular architecture** for better maintainability
- 🎯 **Developer-first design** with intuitive APIs
- 🧪 **Comprehensive testing** suite
- 📚 **Better documentation** and examples
- 🚀 **Production-ready** features and error handling
Special thanks to the original contributors and the broader Python community in Kenya.
---
## 📄 License
Licensed under the [Apache 2.0 License](LICENSE) — free for commercial and private use.
---
<div align="center">
**Made with ❤️ for the Kenyan developer community**
[⭐ Star this repo](https://github.com/rafaeljohn9/mpesa-daraja-sdk) | [🐛 Report Issue](https://github.com/rafaeljohn9/mpesa-daraja-sdk/issues) | [💡 Request Feature](https://github.com/rafaeljohn9/mpesa-daraja-sdk/issues/new)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "mpesakit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "John Kagunda <johnmkagunda@gmail.com>",
"keywords": "africa, api, django, fastapi, flask, mobile money, mpesa, payment, payments, rest, sdk",
"author": null,
"author_email": "John Kagunda <johnmkagunda@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1e/7a/0d94239c6325e612fffc2ed3b4e79173b7c037f30bae8150688815ce0555/mpesakit-1.2.0.tar.gz",
"platform": null,
"description": "# mpesa-daraja-sdk\n\n> \u26a1 **Effortless M-Pesa integration** using Safaricom's Daraja API \u2014 built for developers, by developers.\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/Apache-2.0)\n<!-- []() -->\n\n---\n\n## The Problem\n\nIntegrating Safaricom's **M-Pesa Daraja API** directly is **notoriously complex**:\n\n- Confusing and inconsistent documentation\n- Manual handling of OAuth2 tokens and security credentials\n- Complex encryption and certificate management\n- Different endpoints for sandbox vs production environments\n- STK Push, C2B, B2C, balance \u2014 all feel like separate APIs\n- Time-consuming setup that delays your time-to-market\n\nFor many developers and startups, this becomes a **huge barrier** to adopting M-Pesa payments in Kenya and beyond.\n\n---\n\n## The Solution\n\n**`mpesa-daraja-sdk`** eliminates the complexity with a **clean, developer-friendly Python SDK** that:\n\n- **Zero-config setup** \u2014 just add your credentials and go\n- **Handles authentication automatically** \u2014 OAuth2, tokens, and security\n- **Seamless environment switching** \u2014 sandbox \u2194 production with one parameter\n- **Pythonic interface** \u2014 clean methods that feel natural to Python developers\n- **Batteries included** \u2014 everything you need for M-Pesa integration\n- **Production-ready** \u2014 end goal is to be used by startups and enterprises across Kenya\n\n### Supported Features\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| **STK Push** | Ready | Lipa na M-Pesa Online payments |\n| **C2B Payments** | Ready | Customer to Business transactions |\n| **B2C Payments** | Ready | Business to Customer payouts |\n| **Token Management** | Ready | Automatic OAuth2 handling |\n| **Account Balance** | Coming Soon | Check account balances |\n| **Transaction Reversal** | Coming Soon | Reverse transactions |\n| \ud83c\udfa3 **Webhook Validation** | Coming Soon | Secure callback handling |\n\n> Built on top of [Arlus/mpesa-py](https://github.com/Arlus/mpesa-py) with \u2764\ufe0f \u2014 modernized, cleaned up, and restructured for today's developer needs.\n\n---\n\n## Quick Start\n\n### Installation (coming soon)\n\n```bash\npip install mpesa-daraja-sdk\n```\n\n---\n\n## \ud83d\udcd6 Complete Setup Guide\n\n### 1. Get Safaricom Developer Account\n\n1. Visit [developer.safaricom.co.ke](https://developer.safaricom.co.ke)\n2. **Create account** and verify your email\n3. **Create a new app** to get your credentials:\n - Consumer Key\n - Consumer Secret\n\n### 2. Obtain Test Credentials (Sandbox)\n\n1. Navigate to [Test Credentials Page](https://developer.safaricom.co.ke/test_credentials)\n2. Copy the following credentials:\n - **Shortcode** (Business number)\n - **Initiator Name** (API operator username)\n - **Initiator Password** (API operator password)\n - **Security Credential** (Encrypted password)\n\n### 3. Production Setup\n\nFor production deployment:\n\n1. **Get Paybill/Till Number** from Safaricom\n2. **Generate Security Credential** using Safaricom's public certificate\n3. **Switch environment** to `\"production\"` in your client initialization\n4. **Update callback URLs** to your production domain\n\n---\n\n### Security Best Practices\n\n1. **Never commit credentials** to version control\n2. **Use environment variables** for sensitive data\n3. **Implement webhook validation** for callbacks\n4. **Log transactions** for audit trails\n5. **Monitor rate limits** and implement backoff strategies\n6. **Use HTTPS** for all callback URLs\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions from the community! Here's how you can help:\n\n### Ways to Contribute\n\n- \ud83d\udc1b **Report bugs** via GitHub Issues\n- \ud83d\udca1 **Suggest features** for the roadmap\n- \ud83d\udcd6 **Improve documentation** and examples\n- \ud83d\udd27 **Submit pull requests** with fixes/features\n- \u2b50 **Star the repo** to show support\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/rafaeljohn9/mpesa-daraja-sdk.git\ncd mpesa-daraja-sdk\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n```\n\n### Code Standards\n\n- Follow PEP 8 style guidelines\n- Include type hints where appropriate\n- Write comprehensive tests for new features\n- Update documentation for any API changes\n\n---\n\n## \ud83d\udcde Support & Community\n\n- \ud83d\udcd6 **Documentation**: [Full API docs coming soon]\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/rafaeljohn9/mpesa-daraja-sdk/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/rafaeljohn9/mpesa-daraja-sdk/discussions)\n- \ud83d\udce7 **Email**: <johnmkagunda@gmail.com>\n\n---\n\n## \ud83d\ude4f Attribution & Thanks\n\nThis project began as a fork of the fantastic [`Arlus/mpesa-py`](https://github.com/Arlus/mpesa-py) by [@Arlus](https://github.com/Arlus).\n\n**What we've added:**\n\n- \ud83c\udfd7\ufe0f **Modular architecture** for better maintainability\n- \ud83c\udfaf **Developer-first design** with intuitive APIs\n- \ud83e\uddea **Comprehensive testing** suite\n- \ud83d\udcda **Better documentation** and examples\n- \ud83d\ude80 **Production-ready** features and error handling\n\nSpecial thanks to the original contributors and the broader Python community in Kenya.\n\n---\n\n## \ud83d\udcc4 License\n\nLicensed under the [Apache 2.0 License](LICENSE) \u2014 free for commercial and private use.\n\n---\n\n<div align=\"center\">\n\n**Made with \u2764\ufe0f for the Kenyan developer community**\n\n[\u2b50 Star this repo](https://github.com/rafaeljohn9/mpesa-daraja-sdk) | [\ud83d\udc1b Report Issue](https://github.com/rafaeljohn9/mpesa-daraja-sdk/issues) | [\ud83d\udca1 Request Feature](https://github.com/rafaeljohn9/mpesa-daraja-sdk/issues/new)\n\n</div>\n",
"bugtrack_url": null,
"license": "APACHE-2.0",
"summary": "A Python SDK for integrating with M-Pesa APIs",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/rafaeljohn9/mpesakit",
"Issues": "https://github.com/rafaeljohn9/mpesakit/issues",
"Repository": "https://github.com/rafaeljohn9/mpesakit"
},
"split_keywords": [
"africa",
" api",
" django",
" fastapi",
" flask",
" mobile money",
" mpesa",
" payment",
" payments",
" rest",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b8a2e6f35875554029473397790bdc978cc28f7cf6e122ed11d5cbeb2a61945",
"md5": "fec8a9ca10480535e70761327e8c0ebd",
"sha256": "25323accdc0aec0c8039bc5be0c80551a6068aab7fe9582db9d706ef61f265a8"
},
"downloads": -1,
"filename": "mpesakit-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fec8a9ca10480535e70761327e8c0ebd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 81969,
"upload_time": "2025-08-27T07:33:40",
"upload_time_iso_8601": "2025-08-27T07:33:40.117612Z",
"url": "https://files.pythonhosted.org/packages/4b/8a/2e6f35875554029473397790bdc978cc28f7cf6e122ed11d5cbeb2a61945/mpesakit-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1e7a0d94239c6325e612fffc2ed3b4e79173b7c037f30bae8150688815ce0555",
"md5": "59f471c9be03d9ded521b0bdc79ce7bd",
"sha256": "d8745ff1be7bce4d3bdcdfbba768b6f24d23ea83340916a79efea801aed9c31a"
},
"downloads": -1,
"filename": "mpesakit-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "59f471c9be03d9ded521b0bdc79ce7bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 49413,
"upload_time": "2025-08-27T07:33:39",
"upload_time_iso_8601": "2025-08-27T07:33:39.286508Z",
"url": "https://files.pythonhosted.org/packages/1e/7a/0d94239c6325e612fffc2ed3b4e79173b7c037f30bae8150688815ce0555/mpesakit-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 07:33:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rafaeljohn9",
"github_project": "mpesakit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mpesakit"
}
JSON
