mpesa-kit

Daraja SDK is a flexible, dynamic Node.js library that provides seamless integration with Safaricom’s M-Pesa Daraja API. It acts as a bridge between developers and M-Pesa, allowing you to easily interact with common M-Pesa services such as STK Push, B2C, and C2B.

Features

• Easy-to-use API for M-Pesa’s Daraja services
• Supports STK Push, B2C Payments, C2B Registration
• Simple OAuth token management
• Flexible configuration — credentials fed through the constructor
• Designed for both sandbox and production environments
• Built-in error handling for developer-friendly debugging
• Fully open-source and extensible

Installation

npm install mpesa-kit

Usage

1. Import and Initialize

const Mpesa = require('mpesa-kit');

// Initialize with your credentials
const mpesa = new Mpesa({
  consumerKey: 'YOUR_CONSUMER_KEY',
  consumerSecret: 'YOUR_CONSUMER_SECRET',
  shortCode: 'YOUR_SHORTCODE',
  passKey: 'YOUR_PASSKEY',
  callbackURL: 'https://yourdomain.com/callback',
  baseURL: 'https://sandbox.safaricom.co.ke' // or 'https://api.safaricom.co.ke' for production
});

2. Authentication

You can authenticate explicitly if needed:

(async () => {
  const token = await mpesa.authenticate();
  console.log('OAuth Token:', token);
})();

Most methods handle this internally, so you rarely need to call authenticate() manually.

3. Initiate STK Push

(async () => {
  const response = await mpesa.initiateSTKPush({
    amount: 10,
    phoneNumber: '2547XXXXXXXX', // e.g. 254712345678
    accountReference: 'MyBusiness',
    transactionDesc: 'Payment for goods'
  });
  console.log('STK Push Response:', response);
})();

4. Register C2B URLs

(async () => {
  const response = await mpesa.registerC2BURL({
    confirmationURL: 'https://yourdomain.com/confirmation',
    validationURL: 'https://yourdomain.com/validation'
  });
  console.log('C2B Registration Response:', response);
})();

5. Make B2C Payments

(async () => {
  const response = await mpesa.makeB2CPayment({
    initiatorName: 'testapi',
    securityCredential: 'GENERATED_SECURITY_CREDENTIAL',
    amount: 1000,
    partyA: '600XXX',
    partyB: '2547XXXXXXXX',
    remarks: 'Salary Payment',
    queueTimeoutURL: 'https://yourdomain.com/timeout',
    resultURL: 'https://yourdomain.com/result'
  });
  console.log('B2C Payment Response:', response);
})();

Environment

You can pass sandbox or production URLs to the baseURL parameter in the constructor:

• Sandbox: https://sandbox.safaricom.co.ke
• Production: https://api.safaricom.co.ke

Error Handling

All methods throw errors on failure, including descriptive messages. Use try...catch to handle errors gracefully.

(async () => {
  try {
    const response = await mpesa.initiateSTKPush({
      amount: 10,
      phoneNumber: '2547XXXXXXXX',
      accountReference: 'MyBusiness',
      transactionDesc: 'Payment'
    });
    console.log(response);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Roadmap

• Add STK Push, B2C, and C2B support
• Authentication and token management
• Add transaction status query
• Add reversal support
• Add TypeScript support

Contributing

Pull requests are welcome! Please fork this repository and submit a pull request. For major changes, please open an issue first to discuss the changes.

License

This project is licensed under the ISC License. Feel free to use, modify, and share.

Contact

For bugs, questions, or suggestions, please open an issue on the GitHub Issues page.

Happy Coding!

Build awesome M-Pesa integrations with Daraja SDK!

If you’d like, I can also help with API documentation, code examples, or even a sample project using the SDK. Let me know!