mpesakit

mpesa-daraja-sdk

⚡ Effortless M-Pesa integration using Safaricom's Daraja API — built for developers, by developers.

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 with ❤️ — modernized, cleaned up, and restructured for today's developer needs.

Quick Start

Installation (coming soon)

pip install mpesa-daraja-sdk

📖 Complete Setup Guide

1. Get Safaricom Developer Account

• Visit developer.safaricom.co.ke
• Create account and verify your email
• Create a new app to get your credentials:
  • Consumer Key
  • Consumer Secret

2. Obtain Test Credentials (Sandbox)

• Navigate to Test Credentials Page
• 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:

• Get Paybill/Till Number from Safaricom
• Generate Security Credential using Safaricom's public certificate
• Switch environment to "production" in your client initialization
• Update callback URLs to your production domain

Security Best Practices

• Never commit credentials to version control
• Use environment variables for sensitive data
• Implement webhook validation for callbacks
• Log transactions for audit trails
• Monitor rate limits and implement backoff strategies
• 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

# 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
• 💬 Discussions: GitHub Discussions
• 📧 Email: [e-mail]

🙏 Attribution & Thanks

This project began as a fork of the fantastic Arlus/mpesa-py by @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 — free for commercial and private use.

Made with ❤️ for the Kenyan developer community

⭐ Star this repo | 🐛 Report Issue | 💡 Request Feature