mpesa-kit/README.md

A flexible and dynamic Node.js SDK for Safaricom M-Pesa API (Daraja API).

# 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

```bash
npm install mpesa-kit
```

---


## Usage

### 1. Import and Initialize

```javascript
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:

```javascript
(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

```javascript
(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

```javascript
(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

```javascript
(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.

```javascript
(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](https://github.com/nv-ms/mpesa-kit/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!