🚀 Adams MPesa SDK for Node.js

Modern, Production-Ready MPesa API Integration for Node.js & TypeScript

Features • Installation • Quick Start • Documentation • Examples • Contributing

---

📖 Description

Adams MPesa SDK is a comprehensive, developer-friendly Node.js library for integrating Safaricom's MPesa Daraja API into your applications. Built with TypeScript and designed for production use, it provides a clean, intuitive interface for all MPesa payment operations.

Whether you're building an e-commerce platform, a SaaS application, or a mobile money service in Kenya, this SDK handles the complexity of MPesa integration so you can focus on building your product.

Why Choose This SDK?

• ✅ Type-Safe: Full TypeScript support with comprehensive type definitions
• ✅ Production-Ready: Robust error handling, automatic retries, and token caching
• ✅ Developer-Friendly: Clean API, extensive documentation, and working examples
• ✅ Well-Tested: 49 passing unit tests with comprehensive coverage
• ✅ Modern: Uses latest Node.js features and best practices
• ✅ Zero Config: Sensible defaults that work out of the box

---

✨ Features

Core Functionality

• 🔐 OAuth Token Management - Automatic generation, caching, and refresh
• 💳 STK Push (Lipa Na M-Pesa Online) - Initiate and query customer payments
• 💰 C2B Payments - URL registration and payment simulation
• 💸 B2C Payments - Send money to customers (salary, refunds, etc.)
• 📊 Transaction Status - Query any transaction status

Developer Experience

• ✨ Full TypeScript Support - Complete type definitions for all APIs
• 🔄 Automatic Retries - Exponential backoff for failed requests
• ✅ Input Validation - Phone numbers, amounts, URLs validated automatically
• 🎯 Custom Error Types - Detailed, actionable error messages
• 📱 Phone Number Formatting - Supports multiple formats (0712..., +254..., 254...)
• 🌍 Environment Support - Seamless switching between sandbox and production

Production Features

• ⚡ Token Caching - Minimizes unnecessary API calls
• 🔒 Secure - Follows security best practices
• 📝 Comprehensive Logging - Debug-friendly error messages
• 🧪 Fully Tested - 49 unit tests ensuring reliability
• 📦 Dual Module System - Supports both CommonJS and ES Modules

---

📦 Installation

npm install adams-mpesa-sdk

Or using yarn:

yarn add adams-mpesa-sdk

Requirements

• Node.js >= 16.0.0
• npm or yarn
• Safaricom Daraja API credentials (Get them here)

---

🚀 Quick Start

1. Get Your Credentials

Before you begin, sign up at Safaricom Developer Portal and create an app to get:

• Consumer Key
• Consumer Secret
• Business Shortcode
• Lipa Na M-Pesa Online Passkey

2. Set Up Environment Variables

Create a .env file in your project root:

MPESA_CONSUMER_KEY=your_consumer_key_here
MPESA_CONSUMER_SECRET=your_consumer_secret_here
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your_passkey_here
MPESA_ENVIRONMENT=sandbox

3. Initialize the SDK

TypeScript

import Mpesa from 'adams-mpesa-sdk';
import 'dotenv/config';

const mpesa = new Mpesa({
  consumerKey: process.env.MPESA_CONSUMER_KEY!,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET!,
  shortcode: process.env.MPESA_SHORTCODE!,
  passkey: process.env.MPESA_PASSKEY!,
  environment: 'sandbox', // or 'production'
});

JavaScript (CommonJS)

const Mpesa = require('adams-mpesa-sdk').default;
require('dotenv/config');

const mpesa = new Mpesa({
  consumerKey: process.env.MPESA_CONSUMER_KEY,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET,
  shortcode: process.env.MPESA_SHORTCODE,
  passkey: process.env.MPESA_PASSKEY,
  environment: 'sandbox',
});

---

💡 Usage Examples

STK Push (Lipa Na M-Pesa Online)

Prompt customers to pay via MPesa:

async function initiatePayment() {
  try {
    const response = await mpesa.stkPush({
      amount: 100,
      phone: '254712345678', // Supports multiple formats
      accountReference: 'ORDER-123',
      transactionDesc: 'Payment for Order #123',
      callbackUrl: 'https://yourdomain.com/api/mpesa/callback',
    });

    console.log('Payment initiated:', response.CheckoutRequestID);
    // Customer will receive MPesa prompt on their phone
  } catch (error) {
    console.error('Payment failed:', error.message);
  }
}

Query STK Push Status

Check the status of a payment request:

async function checkPaymentStatus(checkoutRequestId: string) {
  try {
    const response = await mpesa.stkQuery({
      checkoutRequestId: checkoutRequestId,
    });

    if (response.ResultCode === '0') {
      console.log('Payment successful!');
    } else {
      console.log('Payment failed:', response.ResultDesc);
    }
  } catch (error) {
    console.error('Query failed:', error.message);
  }
}

B2C Payment (Send Money to Customers)

Send money for salaries, refunds, or promotions:

async function sendMoney() {
  try {
    const response = await mpesa.b2c({
      amount: 500,
      phone: '254712345678',
      commandId: 'BusinessPayment', // or 'SalaryPayment', 'PromotionPayment'
      occasion: 'Salary Payment',
      remarks: 'Monthly salary',
      resultUrl: 'https://yourdomain.com/api/mpesa/b2c/result',
      timeoutUrl: 'https://yourdomain.com/api/mpesa/b2c/timeout',
    });

    console.log('Transfer initiated:', response.ConversationID);
  } catch (error) {
    console.error('Transfer failed:', error.message);
  }
}

C2B URL Registration

Register URLs for receiving customer payments:

async function registerC2BUrls() {
  try {
    const response = await mpesa.c2bRegister({
      validationUrl: 'https://yourdomain.com/api/mpesa/validation',
      confirmationUrl: 'https://yourdomain.com/api/mpesa/confirmation',
      responseType: 'Completed', // or 'Cancelled'
    });

    console.log('URLs registered successfully');
  } catch (error) {
    console.error('Registration failed:', error.message);
  }
}

For more examples, see the examples.ts file.

---

⚙️ Configuration

Required Configuration

Parameter	Type	Description
consumerKey	string	Consumer Key from Daraja Portal
consumerSecret	string	Consumer Secret from Daraja Portal
shortcode	string	Your business shortcode (Paybill or Till)
passkey	string	Lipa Na M-Pesa Online Passkey
environment	'sandbox' | 'production'	API environment

Optional Configuration

Parameter	Type	Default	Description
initiatorName	string	-	Required for B2C and Transaction Status
securityCredential	string	-	Required for B2C and Transaction Status
autoRefreshToken	boolean	true	Automatically refresh expired tokens
maxRetries	number	3	Maximum retry attempts for failed requests
timeout	number	30000	Request timeout in milliseconds

---

✅ Input Validation

The SDK provides comprehensive input validation to ensure data integrity before making API calls:

Phone Number Validation

import { validateKenyanPhoneNumber, formatPhoneNumber } from 'adams-mpesa-sdk';

const isValid = validateKenyanPhoneNumber('254712345678');

const formattedPhone = formatPhoneNumber('0712345678');

Supported Phone Formats:

• 254712345678 ✅
• 0712345678 ✅
• 712345678 ✅
• +254712345678 ✅
• 254-712-345-678 ✅

Amount Validation

import { validatePositiveAmount } from 'adams-mpesa-sdk';

validatePositiveAmount(100, 'payment amount');

Rules:

• Must be a positive number
• Must be a whole number (no decimals)
• Must be greater than 0

Shortcode Validation

import { validateShortcode, isValidShortcode } from 'adams-mpesa-sdk';

validateShortcode('174379');

const valid = isValidShortcode('174379');

Rules:

• Must be 5-7 digits
• Must contain only numbers

Required Fields Validation

import { validateRequiredFields } from 'adams-mpesa-sdk';

const paymentData = {
  amount: 100,
  phone: '254712345678',
  accountReference: 'ORDER-123',
};

validateRequiredFields(paymentData, ['amount', 'phone', 'accountReference']);

All validation errors throw descriptive ValidationError with clear messages about what went wrong.

---

🔄 Retry Logic Explained

The SDK includes intelligent retry logic for handling Safaricom API downtime and network issues:

How It Works

1. Automatic Retries: Failed requests are automatically retried up to 3 times (configurable)
2. Exponential Backoff: Delays between retries increase exponentially to avoid overwhelming the API
3. Smart Retry: Only retries on errors that might succeed on retry (network errors, 5xx errors, rate limits)

Retry Sequence

Request 1 → Fail → Wait 1000ms (1s)
Request 2 → Fail → Wait 2000ms (2s)
Request 3 → Fail → Wait 4000ms (4s)
Request 4 → Fail → Throw MaxRetriesExceededError

Configuration

const mpesa = new Mpesa({
  consumerKey: 'your-key',
  consumerSecret: 'your-secret',
  shortcode: '174379',
  passkey: 'your-passkey',
  environment: 'sandbox',
  maxRetries: 3,
  timeout: 30000,
});

Errors That Trigger Retries

• Network errors (ECONNREFUSED, ETIMEDOUT)
• HTTP 5xx errors (server errors)
• HTTP 429 (rate limiting)
• Timeout errors

Errors That Don't Trigger Retries

• HTTP 4xx errors (client errors like invalid credentials)
• Validation errors
• Authentication failures

---

🎯 Using the Callback Middleware

The SDK includes built-in Express middleware to handle MPesa callbacks easily:

Basic Usage

import express from 'express';
import { mpesaCallbackMiddleware, MpesaRequest } from 'adams-mpesa-sdk';

const app = express();
app.use(express.json());

app.post(
  '/api/mpesa/callback',
  mpesaCallbackMiddleware(),
  (req: MpesaRequest, res) => {
    const { mpesa } = req;
    
    if (mpesa?.ResultCode === 0) {
      console.log('✅ Payment successful!');
      console.log('Amount:', mpesa.metadata?.Amount);
      console.log('Receipt:', mpesa.metadata?.MpesaReceiptNumber);
      console.log('Phone:', mpesa.metadata?.PhoneNumber);
    } else {
      console.log('❌ Payment failed:', mpesa?.ResultDesc);
    }
    
    res.json({ ResultCode: 0, ResultDesc: 'Success' });
  }
);

app.listen(3000);

With Signature Verification (Recommended for Production)

app.post(
  '/api/mpesa/callback',
  mpesaCallbackMiddleware({
    verifySignature: true,
    secretKey: process.env.MPESA_SECRET_KEY!,
    signatureHeader: 'x-mpesa-signature',
  }),
  (req: MpesaRequest, res) => {
    res.json({ ResultCode: 0, ResultDesc: 'Success' });
  }
);

C2B Callback Middleware

import { c2bCallbackMiddleware, MpesaRequest } from 'adams-mpesa-sdk';

app.post(
  '/api/mpesa/c2b-confirmation',
  c2bCallbackMiddleware(),
  (req: MpesaRequest, res) => {
    const { metadata } = req.mpesa!;
    
    console.log('Transaction ID:', metadata?.TransID);
    console.log('Amount:', metadata?.TransAmount);
    console.log('Phone:', metadata?.MSISDN);
    
    res.json({ ResultCode: 0, ResultDesc: 'Success' });
  }
);

Available Callback Data

The middleware attaches req.mpesa with:

{
  MerchantRequestID: string;
  CheckoutRequestID: string;
  ResultCode: number;
  ResultDesc: string;
  CallbackMetadata?: {
    Item: Array<{ Name: string; Value: string | number }>;
  };
  metadata?: {
    Amount: number;
    MpesaReceiptNumber: string;
    PhoneNumber: string;
    TransactionDate: string;
  };
}

---

🔐 Security Best Practices

1. Callback Signature Verification

Always verify callbacks in production to prevent unauthorized requests:

import { verifyCallbackSignature } from 'adams-mpesa-sdk';

const payload = JSON.stringify(req.body);
const signature = req.headers['x-mpesa-signature'];
const secretKey = process.env.MPESA_SECRET_KEY!;

const isValid = verifyCallbackSignature(payload, signature, secretKey);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

2. Environment Variables

Never hardcode credentials. Always use environment variables:

// ❌ Bad
const mpesa = new Mpesa({
  consumerKey: 'abc123',
  consumerSecret: 'xyz789',
  ...
});

// ✅ Good
const mpesa = new Mpesa({
  consumerKey: process.env.MPESA_CONSUMER_KEY!,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET!,
  ...
});

3. HTTPS for Callbacks

MPesa requires HTTPS URLs for production callbacks:

const callbackUrl = process.env.NODE_ENV === 'production'
  ? 'https://yourdomain.com/callback'
  : 'https://your-ngrok-url.ngrok.io/callback';

4. Rate Limiting

Implement rate limiting on your callback endpoints:

import rateLimit from 'express-rate-limit';

const callbackLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100,
});

app.post('/api/mpesa/callback', callbackLimiter, ...);

5. Input Sanitization

Always validate and sanitize user inputs:

import { validateRequiredFields, validatePositiveAmount } from 'adams-mpesa-sdk';

validateRequiredFields(req.body, ['amount', 'phone', 'reference']);
validatePositiveAmount(req.body.amount);

6. Error Logging

Log errors securely without exposing sensitive data:

import { sanitizeForLogging } from 'adams-mpesa-sdk';

const safeData = sanitizeForLogging({
  consumerKey: 'secret-key',
  amount: 100,
  phone: '254712345678',
});

console.log(safeData);

7. Token Security

The SDK handles token caching securely in memory. Never store tokens in:

• Local storage (browser)
• Plain text files
• Version control (git)
• Database without encryption

---

🎯 Callback / Webhook Handling

MPesa sends callbacks to your server for async operations. Here's a complete Express.js example:

import express from 'express';
import Mpesa from 'adams-mpesa-sdk';

const app = express();
app.use(express.json());

// STK Push Callback
app.post('/api/mpesa/callback', (req, res) => {
  const { Body } = req.body;
  const { stkCallback } = Body;

  if (stkCallback.ResultCode === 0) {
    // Payment successful
    const { CallbackMetadata } = stkCallback;
    const amount = CallbackMetadata.Item.find((item: any) => item.Name === 'Amount')?.Value;
    const mpesaRef = CallbackMetadata.Item.find((item: any) => item.Name === 'MpesaReceiptNumber')?.Value;
    
    console.log(`Payment of ${amount}. Ref: ${mpesaRef}`);
  } else {
    console.log('Payment failed:', stkCallback.ResultDesc);
  }

  res.json({ ResultCode: 0, ResultDesc: 'Success' });
});

app.listen(3000, () => console.log('Server running'));

---

🚨 Error Handling

The SDK provides detailed error types:

import {
  MpesaError,
  MpesaAuthError,
  MpesaResponseError,
  ValidationError,
  InvalidPhoneNumberError,
} from 'adams-mpesa-sdk';

try {
  await mpesa.stkPush({...});
} catch (error) {
  if (error instanceof InvalidPhoneNumberError) {
    console.error('Invalid phone number format');
  } else if (error instanceof MpesaAuthError) {
    console.error('Authentication failed');
  } else if (error instanceof MpesaResponseError) {
    console.error('MPesa API error:', error.message);
  }
}

Common Errors and Solutions

Error	Cause	Solution
Invalid Access Token	App not subscribed to API	Subscribe to the API product in Daraja Portal
Invalid Shortcode	Wrong business shortcode	Verify your shortcode in Daraja Portal
Invalid Phone Number	Wrong phone format	Use format: 254XXXXXXXXX

---

📚 Documentation

For more detailed information:

• Quick Start Guide
• Project Summary
• Examples File
• Safaricom Developer Portal

---

🧪 Testing Guide

Testing With Safaricom Sandbox

The SDK works seamlessly with both sandbox and production environments. Here's how to test without a real phone:

1. Get Sandbox Credentials

1. Visit Safaricom Developer Portal
2. Create an account and log in
3. Create a new app
4. Subscribe to the following APIs:
   • Lipa Na M-Pesa Online (for STK Push)
   • M-Pesa C2B (for Customer to Business)
   • M-Pesa B2C (for Business to Customer)
5. Get your credentials from the app dashboard:
   • Consumer Key
   • Consumer Secret
   • Test Credentials (shortcode, passkey, etc.)

2. Sandbox Test Credentials

Safaricom provides these test credentials for sandbox:

MPESA_CONSUMER_KEY=your_app_consumer_key
MPESA_CONSUMER_SECRET=your_app_consumer_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
MPESA_ENVIRONMENT=sandbox

3. Testing STK Push

import Mpesa from 'adams-mpesa-sdk';

const mpesa = new Mpesa({
  consumerKey: process.env.MPESA_CONSUMER_KEY!,
  consumerSecret: process.env.MPESA_CONSUMER_SECRET!,
  shortcode: '174379', // Sandbox shortcode
  passkey: 'bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919',
  environment: 'sandbox',
});

// Test STK Push
const response = await mpesa.stkPush({
  amount: 1,
  phone: '254708374149', // Use any Kenyan number in sandbox
  accountReference: 'TEST-001',
  transactionDesc: 'Test Payment',
});

console.log('Checkout Request ID:', response.CheckoutRequestID);

4. Simulating Payment in Sandbox

In sandbox mode, you can simulate payment responses without a real phone:

Option A: Use the C2B Simulator

1. Go to Safaricom Developer Portal
2. Navigate to APIs → M-Pesa Sandbox
3. Use the "C2B Simulate Transaction" tool

Option B: Programmatically simulate

// Simulate C2B payment
await mpesa.c2bSimulate({
  amount: 100,
  phone: '254708374149',
  billRefNumber: 'TEST-REF',
  commandId: 'CustomerPayBillOnline',
});

5. Testing Callbacks Locally

Use ngrok to expose your local server for callback testing:

# Install ngrok
npm install -g ngrok

# Start your local server
npm start

# In another terminal, start ngrok
ngrok http 3000

Update your .env with the ngrok URL:

MPESA_CALLBACK_URL=https://your-ngrok-url.ngrok.io/api/mpesa/callback

6. Unit Testing Your Integration

Example test using Jest:

import Mpesa from 'adams-mpesa-sdk';

describe('MPesa Integration', () => {
  let mpesa: Mpesa;

  beforeAll(() => {
    mpesa = new Mpesa({
      consumerKey: process.env.MPESA_CONSUMER_KEY!,
      consumerSecret: process.env.MPESA_CONSUMER_SECRET!,
      shortcode: process.env.MPESA_SHORTCODE!,
      passkey: process.env.MPESA_PASSKEY!,
      environment: 'sandbox',
    });
  });

  it('should generate access token', async () => {
    const token = await mpesa.getAccessToken();
    expect(token).toBeDefined();
    expect(token.length).toBeGreaterThan(0);
  });

  it('should initiate STK push', async () => {
    const response = await mpesa.stkPush({
      amount: 1,
      phone: '254708374149',
      accountReference: 'TEST',
      transactionDesc: 'Test',
    });

    expect(response.ResponseCode).toBe('0');
    expect(response.CheckoutRequestID).toBeDefined();
  });

  it('should query STK push status', async () => {
    const stkResponse = await mpesa.stkPush({
      amount: 1,
      phone: '254708374149',
      accountReference: 'TEST',
      transactionDesc: 'Test',
    });

    const queryResponse = await mpesa.stkQuery({
      checkoutRequestId: stkResponse.CheckoutRequestID,
    });

    expect(queryResponse.ResultCode).toBeDefined();
  });
});

7. Moving to Production

When ready for production:

1. Update credentials:

   MPESA_ENVIRONMENT=production
   MPESA_SHORTCODE=your_production_shortcode
   MPESA_PASSKEY=your_production_passkey

2. Use HTTPS for callbacks:

   • Safaricom requires HTTPS URLs in production
   • Ensure your callback URLs are publicly accessible
   • Use a valid SSL certificate

3. Update callback URLs:

   MPESA_CALLBACK_URL=https://yourdomain.com/api/mpesa/callback
   MPESA_RESULT_URL=https://yourdomain.com/api/mpesa/result

4. Test with real transactions:

   • Start with small amounts (KES 1-10)
   • Test with your own phone number first
   • Verify callbacks are received correctly

8. Common Sandbox Issues

Issue	Solution
"Invalid Access Token"	Ensure you've subscribed to the API in the developer portal
"Invalid Shortcode"	Use 174379 for sandbox STK Push
"Request failed"	Check your consumer key and secret are correct
"Callback not received"	Ensure your callback URL is publicly accessible (use ngrok)

9. Testing Checklist

Before going live, test these scenarios:

• ✅ OAuth token generation
• ✅ STK Push initiation
• ✅ STK Push query
• ✅ Successful payment callback
• ✅ Failed payment callback
• ✅ Timeout handling
• ✅ Network error handling
• ✅ Invalid phone number handling
• ✅ Invalid amount handling
• ✅ C2B URL registration (if using C2B)
• ✅ B2C payment (if using B2C)

---

📚 Examples

The /examples folder contains complete working examples:

1. Express STK Push Server

File: examples/express-stk-push.ts

A complete Express.js server demonstrating:

• STK Push payment initiation
• Payment status queries
• Error handling
• RESTful API endpoints

npx ts-node examples/express-stk-push.ts

2. Callback Handling

File: examples/callback-handling.ts

Complete callback handling examples:

• STK Push callbacks with middleware
• Secure callbacks with signature verification
• C2B validation and confirmation
• Extracting payment metadata

npx ts-node examples/callback-handling.ts

3. Error Handling

File: examples/error-handling.ts

Comprehensive error handling strategies:

• Handling specific error types
• Graceful degradation
• User-friendly error messages
• Error logging for monitoring
• Retry logic demonstration

npx ts-node examples/error-handling.ts

---

🧪 Testing

# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run live API tests (requires credentials)
npm run test:live

Live Testing Scripts

# Test OAuth token generation
npx ts-node test-token-only.ts

# Test STK Push
npx ts-node test-stk-push.ts

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

• Use the GitHub Issues page
• Provide a clear description and steps to reproduce
• Include error messages and stack traces

Pull Requests

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow the existing code style
• Update documentation for API changes
• Ensure all tests pass before submitting

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💬 Support & Contact

• GitHub Issues: Report bugs or request features
• Email: mugweadams439@gmail.com
• GitHub: @ADAMSmugwe

---

🙏 Acknowledgments

• Safaricom Daraja API - Official MPesa API
• All contributors and users of this SDK
• The Node.js and TypeScript communities

---

🌟 Show Your Support

If this SDK helped you build something awesome, please:

• ⭐ Star this repository
• 🐛 Report issues
• 💡 Suggest new features
• 🤝 Contribute code
• 📢 Share with other developers

---

🎉 Happy Coding! 🎉

Built with ❤️ for the Kenyan developer community

Made by Adams Mugwe • Repository