🚀 Getting Started with MpesaJS
Welcome to MpesaJS! This guide will help you set up and configure the SDK for your project. Whether you’re using it for development or production, we’ve got you covered.
📦 Installation
Install MpesaJS using your preferred package manager:
npm
npm install mpesajs🛠️ Configuration Setup
MpesaJS provides a powerful CLI tool that automates your environment setup. You can initialize either a test environment with pre-configured credentials or a live environment with placeholders for your production credentials.
CLI Commands Overview
Basic Commands
# Initialize test environment
npx mpesajs init-test
# Initialize live environment
npx mpesajs init-live
# View help
npx mpesajs --help
# Check version
npx mpesajs --versionEnvironment File Management
By default, MpesaJS uses a dedicated .env.mpesajs file to keep your SDK configuration separate from other environment variables. This approach helps maintain a clean separation of concerns in your project.
Choose Environment File
.env.mpesajs(Recommended): Keeps SDK settings isolated.env(Alternative): Use with--default-envflag if you prefer consolidating all environment variables
Select Environment Type
- Test Environment: Pre-configured sandbox credentials
- Live Environment: Production-ready configuration template
Configure Settings
Update the generated environment variables based on your needs
🔐 Environment Variables Reference
Authentication Variables
These variables are crucial for establishing secure communication with the M-Pesa API:
Test Environment
# Core Authentication
MPESA_CONSUMER_KEY=your_live_consumer_key
MPESA_CONSUMER_SECRET=your_live_consumer_secret
MPESA_SANDBOX=true
# Business Configuration
MPESA_BUSINESS_SHORTCODE=your_live_shortcode
MPESA_PASSKEY=your_live_passkey
MPESA_PHONE_NUMBER=255712345678Callback URLs
Configure these endpoints to handle M-Pesa API responses:
# API Callback URLs
MPESA_CONFIRMATION_URL=https://your-domain.com/confirmation
MPESA_VALIDATION_URL=https://your-domain.com/validation
MPESA_QUEUE_TIMEOUT_URL=https://your-domain.com/timeout
MPESA_RESULT_URL=https://your-domain.com/resultCommand Settings
These settings control specific M-Pesa operations:
MPESA_PAYOUT_COMMAND_ID=BusinessPayment
MPESA_REGISTER_URL_COMMAND_ID=RegisterURL
MPESA_REGISTER_URL_RESPONSE_TYPE=CompletedPerformance Optimization
Fine-tune your SDK’s performance with these advanced settings:
# Rate Limiting Configuration
MPESAJS_MAX_RETRIES=3 # Maximum retry attempts for failed requests
MPESAJS_INITIAL_DELAY_MS=1000 # Initial retry delay in milliseconds
MPESAJS_MAX_DELAY_MS=10000 # Maximum delay between retries
MPESAJS_BACKOFF_FACTOR=2 # Exponential backoff multiplier
MPESAJS_MAX_CONCURRENT=1000 # Maximum concurrent API requests
MPESAJS_TIME_WINDOW_MS=60000 # Rate limiting time window📝 Best Practices
Environment Separation
Keep your SDK configuration isolated in .env.mpesajs for better maintainability and security.
Version Control Safety
Add both .env and .env.mpesajs to your .gitignore to prevent accidentally committing sensitive credentials.
Credential Management
- Never commit real credentials to version control
- Rotate your API keys periodically
- Use different credentials for test and production environments
Environment Management
Maintain separate configuration files for:
- Local Development
- Testing/Staging
- Production
🎯 Next Steps
Ready to start building? Follow these steps to get your integration up and running:
Verify Installation
Ensure MpesaJS is properly installed in your project
Configure Environment
Run the appropriate initialization command and update credentials:
npx mpesajs init-test # For development
npx mpesajs init-live # For productionTest Integration
Validate your setup using the sandbox environment:
- Test API authentication
- Verify callback URLs
- Monitor rate limiting behavior
Implementation
Start implementing M-Pesa features in your application:
- Payment processing
- Transaction status checks
- Callback handling
Need help? Check out our API Reference or join our Community for support!