https://github.com/matrixjnr/mpesa-node-api
Mpesa API library implemented in Nodejs
https://github.com/matrixjnr/mpesa-node-api
daraja-api mpesa mpesa-api mpesa-backend mpesa-node mpesa-sdk safaricom
Last synced: 5 months ago
JSON representation
Mpesa API library implemented in Nodejs
- Host: GitHub
- URL: https://github.com/matrixjnr/mpesa-node-api
- Owner: matrixjnr
- License: mit
- Created: 2018-12-19T12:29:07.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-09-13T15:39:43.000Z (9 months ago)
- Last Synced: 2025-10-23T02:51:35.353Z (8 months ago)
- Topics: daraja-api, mpesa, mpesa-api, mpesa-backend, mpesa-node, mpesa-sdk, safaricom
- Language: TypeScript
- Homepage:
- Size: 417 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# M-Pesa Daraja API - Node.js Library
[](https://badge.fury.io/js/mpesalib)
[](https://github.com/ellerbrock/typescript-badges/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/matrixjnr/mpesa-node-api/actions)
[](https://snyk.io/test/github/matrixjnr/mpesa-node-api?targetFile=package.json)
[](https://coveralls.io/github/matrixjnr/mpesa-node-api?branch=main)
A robust, modern Node.js library for integrating with Safaricom's M-Pesa Daraja API. Built with TypeScript, comprehensive error handling, and extensive testing.
## Features
- 🚀 **Modern TypeScript** - Full TypeScript support with comprehensive type definitions
- 🔒 **Secure** - Built-in security credential generation and token management
- 🛡️ **Error Handling** - Comprehensive error handling and validation
- 📝 **Well Documented** - Extensive documentation and examples
- 🧪 **Thoroughly Tested** - 95%+ test coverage
- 🔄 **Retry Logic** - Built-in retry mechanism for network failures
- 📱 **Phone Number Formatting** - Automatic phone number formatting and validation
- 🌍 **Environment Support** - Support for both sandbox and production environments
- 📊 **Callback Handling** - Built-in utilities for handling M-Pesa callbacks
## Supported APIs
- ✅ **STK Push** (Lipa Na M-Pesa Online)
- ✅ **STK Push Query** (Check payment status)
- ✅ **C2B Register URLs** (Customer to Business)
- ✅ **C2B Simulate** (Test C2B payments)
- ✅ **B2C Payment** (Business to Customer)
- ✅ **B2B Payment** (Business to Business)
- ✅ **Account Balance** (Check account balance)
- ✅ **Transaction Status** (Query transaction status)
- ✅ **Transaction Reversal** (Reverse transactions)
## Installation
```bash
npm install mpesalib
```
> **⚠️ Upgrading from v1.x?** This is a complete rewrite with breaking changes. See the [Migration Guide](./MIGRATION.md) for detailed upgrade instructions.
## Quick Start
### 1. Configuration
Create a `.env` file based on `.env.example`:
```env
MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_ENVIRONMENT=sandbox
MPESA_SHORT_CODE=174379
MPESA_PASSKEY=your_passkey
```
### 2. Basic Usage
```typescript
import { Mpesa } from 'mpesalib';
// Initialize from environment variables
const mpesa = Mpesa.fromEnv();
// Or initialize with config object
const mpesa = new Mpesa({
consumerKey: 'your_consumer_key',
consumerSecret: 'your_consumer_secret',
environment: 'sandbox',
shortCode: '174379',
passkey: 'your_passkey',
});
// STK Push (Customer Payment)
const response = await mpesa.paybillPayment(
1000, // Amount
'254712345678', // Phone number
'INV001', // Account reference
'Payment for services', // Description
'https://yourdomain.com/callback' // Callback URL
);
console.log(response);
```
## API Reference
### STK Push (Lipa Na M-Pesa Online)
Initiate a payment request to customer's phone:
```typescript
// Paybill payment
const response = await mpesa.paybillPayment(
amount,
phoneNumber,
accountReference,
description,
callbackURL
);
// Buy goods payment
const response = await mpesa.buyGoodsPayment(
amount,
phoneNumber,
accountReference,
description,
callbackURL
);
// Custom STK Push
const response = await mpesa.stkPush({
BusinessShortCode: '174379',
TransactionType: 'CustomerPayBillOnline',
Amount: 1000,
PartyA: '254712345678',
PartyB: '174379',
PhoneNumber: '254712345678',
CallBackURL: 'https://yourdomain.com/callback',
AccountReference: 'TEST001',
TransactionDesc: 'Test payment',
});
```
### STK Push Query
Check the status of an STK Push request:
```typescript
const status = await mpesa.stkPushQuery('ws_CO_12345678');
```
### C2B (Customer to Business)
Register callback URLs and simulate C2B transactions:
```typescript
// Register URLs
await mpesa.registerC2BUrls({
ShortCode: '600000',
ResponseType: 'Completed',
ConfirmationURL: 'https://yourdomain.com/confirmation',
ValidationURL: 'https://yourdomain.com/validation',
});
// Simulate C2B payment
await mpesa.simulateC2B({
ShortCode: '600000',
CommandID: 'CustomerPayBillOnline',
Amount: 1000,
Msisdn: '254712345678',
BillRefNumber: 'INV001',
});
```
### B2C (Business to Customer)
Send money to customers:
```typescript
// Business payment
await mpesa.businessPayment(
5000,
'254712345678',
'Business payment',
'https://yourdomain.com/timeout',
'https://yourdomain.com/result'
);
// Salary payment
await mpesa.salaryPayment(
50000,
'254712345678',
'Monthly salary',
'https://yourdomain.com/timeout',
'https://yourdomain.com/result'
);
// Custom B2C
await mpesa.b2cPayment({
InitiatorName: 'testapi',
SecurityCredential: 'credential',
CommandID: 'BusinessPayment',
Amount: 1000,
PartyA: '600000',
PartyB: '254712345678',
Remarks: 'Payment',
QueueTimeOutURL: 'https://yourdomain.com/timeout',
ResultURL: 'https://yourdomain.com/result',
});
```
### B2B (Business to Business)
Transfer money between businesses:
```typescript
await mpesa.b2bPayment({
InitiatorName: 'testapi',
SecurityCredential: 'credential',
CommandID: 'BusinessPayBill',
Amount: 1000,
PartyA: '600000',
PartyB: '600001',
RecieverIdentifierType: 4,
Remarks: 'B2B Payment',
QueueTimeOutURL: 'https://yourdomain.com/timeout',
ResultURL: 'https://yourdomain.com/result',
AccountReference: 'TEST001',
});
```
### Account Balance
Check account balance:
```typescript
await mpesa.getAccountBalance({
InitiatorName: 'testapi',
SecurityCredential: 'credential',
CommandID: 'AccountBalance',
PartyA: '600000',
IdentifierType: '4',
Remarks: 'Balance inquiry',
QueueTimeOutURL: 'https://yourdomain.com/timeout',
ResultURL: 'https://yourdomain.com/result',
});
```
### Transaction Status
Query transaction status:
```typescript
await mpesa.getTransactionStatus({
InitiatorName: 'testapi',
SecurityCredential: 'credential',
CommandID: 'TransactionStatusQuery',
TransactionID: 'OEI2AK4Q16',
PartyA: '600000',
IdentifierType: '4',
ResultURL: 'https://yourdomain.com/result',
QueueTimeOutURL: 'https://yourdomain.com/timeout',
Remarks: 'Status query',
});
```
### Transaction Reversal
Reverse a transaction:
```typescript
await mpesa.reverseTransaction({
InitiatorName: 'testapi',
SecurityCredential: 'credential',
CommandID: 'TransactionReversal',
TransactionID: 'OEI2AK4Q16',
Amount: 1000,
ReceiverParty: '600000',
RecieverIdentifierType: '4',
ResultURL: 'https://yourdomain.com/result',
QueueTimeOutURL: 'https://yourdomain.com/timeout',
Remarks: 'Reversal',
});
```
## Callback Handling
Handle M-Pesa callbacks in your Express.js application:
```typescript
import express from 'express';
const app = express();
app.use(express.json());
// STK Push callback
app.post('/mpesa/stkpush/callback', (req, res) => {
const callbackData = req.body;
if (callbackData.Body?.stkCallback?.ResultCode === 0) {
console.log('Payment successful!');
// Update your database
} else {
console.log('Payment failed:', callbackData.Body.stkCallback.ResultDesc);
}
res.status(200).json({ status: 'OK' });
});
// B2C result callback
app.post('/mpesa/b2c/result', (req, res) => {
const result = req.body.Result;
if (result.ResultCode === 0) {
console.log('B2C payment successful:', result.TransactionID);
} else {
console.log('B2C payment failed:', result.ResultDesc);
}
res.status(200).json({ status: 'OK' });
});
```
## Utilities
The library includes helpful utilities:
```typescript
import { MpesaUtils } from 'mpesalib';
// Format phone numbers
const formatted = MpesaUtils.formatPhoneNumber('0712345678');
// Returns: '254712345678'
// Generate timestamp
const timestamp = MpesaUtils.generateTimestamp();
// Returns: '20231201120000'
// Generate password for STK Push
const password = MpesaUtils.generatePassword(
shortCode,
passkey,
timestamp
);
// Generate security credential
const credential = MpesaUtils.generateSecurityCredential(
initiatorPassword,
certificatePath
);
// Retry failed operations
const result = await MpesaUtils.retry(
async () => mpesa.stkPush(request),
3, // max retries
1000 // delay in ms
);
```
## Error Handling
The library provides comprehensive error handling:
```typescript
try {
const response = await mpesa.stkPush(request);
console.log('Success:', response);
} catch (error) {
if (error.status === 401) {
console.error('Authentication failed');
} else if (error.status === 400) {
console.error('Bad request:', error.data);
} else {
console.error('Network error:', error.message);
}
}
```
## Environment Configuration
### Required Environment Variables
```env
MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_ENVIRONMENT=sandbox|production
MPESA_SHORT_CODE=your_shortcode
```
### Optional Environment Variables
```env
MPESA_INITIATOR_NAME=your_initiator_name
MPESA_SECURITY_CREDENTIAL=your_security_credential
MPESA_CERTIFICATE_PATH=./path/to/certificate.cer
MPESA_PASSKEY=your_passkey
```
## Getting Started with Daraja API
### 1. Create Daraja Account
1. Visit [Daraja Portal](https://developer.safaricom.co.ke/)
2. Create an account and verify your email
3. Login to the portal
### 2. Create an App
1. Go to "My Apps" section
2. Click "Add a new app"
3. Fill in app details:
- **App Name**: Your application name
- **Description**: Brief description of your app
- **Select APIs**: Choose the APIs you need (STK Push, C2B, B2C, etc.)
### 3. Get Credentials
After creating the app, you'll get:
- **Consumer Key**: Used for authentication
- **Consumer Secret**: Used for authentication
### 4. Test Credentials (Sandbox)
For sandbox testing, use these test credentials:
- **Short Code**: 174379
- **Test MSISDN**: 254708374149
- **Passkey**: Get from Daraja portal
### 5. Production Setup
For production:
1. Request production access from Safaricom
2. Get production credentials
3. Update your configuration to use production environment
## Testing
Run the test suite:
```bash
npm test
```
Run tests with coverage:
```bash
npm run test:coverage
```
Run tests in watch mode:
```bash
npm run test:watch
```
## Contributing
1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Ensure tests pass: `npm test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Submit a pull request
## Changelog
### v3.0.0 (Latest)
- ✨ Complete TypeScript rewrite
- ✨ Modern async/await API
- ✨ Comprehensive error handling
- ✨ Built-in retry mechanism
- ✨ Phone number formatting utilities
- ✨ 95%+ test coverage
- ✨ Updated Daraja API endpoints
- ✨ Environment variable support
- ✨ Callback handling utilities
### v0.0.2 (Legacy)
- Basic JavaScript implementation
- Limited error handling
- No TypeScript support
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📖 [Documentation](https://github.com/matrixjnr/mpesa-node-api/wiki)
- 🐛 [Report Issues](https://github.com/matrixjnr/mpesa-node-api/issues)
- 💬 [Discussions](https://github.com/matrixjnr/mpesa-node-api/discussions)
- 📧 [Email Support](mailto:johnsimiyu4@gmail.com)
## Acknowledgments
- [Safaricom](https://www.safaricom.co.ke/) for providing the Daraja API
- [M-Pesa](https://www.vodafone.com/what-we-do/services/m-pesa) for the mobile payment platform
- All contributors who have helped improve this library
## Related Projects
- [M-Pesa Express](https://www.npmjs.com/package/mpesa-express) - Express.js middleware
- [M-Pesa Laravel](https://github.com/SmoDav/mpesa) - Laravel package
- [M-Pesa PHP](https://github.com/SmoDav/mpesa-php) - PHP SDK
---
Made with ❤️ by [John Simiyu](https://github.com/matrixjnr)