M-Pesa Library for Node.js using REST API
- Node v6+, 8+ recommended.
- Yarn* (optional) You can still use npm
- ES6 knowledge
Use npm/yarn:
npm i mpesa-node Please make sure you have read the documentation on Daraja before continuing.
You need the following before getting to use this library:
- Consumer Key and Consume Secret
- Test Credentials (Optional only for sandbox)
This library is extremely modular, meaning you can create more than one Mpesa instance
const Mpesa = require('mpesa-node') const mpesaApi = new Mpesa({ consumerKey: '<your consumer key>', consumerSecret: '<your consumer secret>' }) // another instance // const instance = new Mpesa({ consumerKey: 'test', consumerSecret: 'test', environment: 'production' }) mpesaApi .c2bSimulate( 254708374149, 500, 'h6dk0Ue2' ) .then((result) => { //do something }) .catch((err) => { // retry? })While working with the Mpesa Class, you only need two key-value items, ie: consumerKey and consumerSecret. Nonetheless, prefilling some things means you dont have to re-enter them again. A complete config object looks like this
new Mpesa({ consumerKey: '<your consumer key>', consumerSecret: '<your consumer secret>', environment: 'sandbox', shortCode: '600111', initiatorName: 'Test Initiator', lipaNaMpesaShortCode: 123456, lipaNaMpesaShortPass: '<some key here>', securityCredential: '<credential here>', certPath: path.resolve('keys/myKey.cert') })Please note that this library is in active development, use in production with caution.
Current API:
const mpesaApi = new Mpesa({ consumerKey: '<your consumer key>', consumerSecret: '<your consumer secret>' }) const { accountBalance, b2b, b2c, c2bRegister, c2bSimulate, lipaNaMpesaOnline, lipaNaMpesaQuery, reversal, transactionStatus } = mpesaApiOfcourse you dont need to import all methods, you can import the only ones you need.
All methods return a <Promise>, hence you can use .then or await. All calls are done by Axios, so for the response structure check Axios documentation.
This initiates a business to customer transactions from a company (shortcode) to end users (mobile numbers) of their services.
/* * b2c(senderParty, receiverParty, amount, queueUrl, resultUrl, commandId = 'BusinessPayment', initiatorName = null, remarks = 'B2C Payment', occasion = null) * Example: */ const { shortCode } = mpesaApi.configs const testMSISDN = 254708374149 await mpesaApi.b2c(shortCode, testMSISDN, 100, URL + '/b2c/timeout', URL + '/b2c/success')This initiates a business to business transaction between one company to another.
/* * b2c(senderParty, receiverParty, amount, queueUrl, resultUrl, senderType = 4, receiverType = 4, initiator = null, commandId = 'BusinessToBusinessTransfer', accountRef = null, remarks = 'B2B Request') * Example: */ const { shortCode } = mpesaApi.configs const testShortcode2 = 600000 await mpesaApi.b2b(shortCode, testShortcode2, 100, URL + '/b2b/timeout', URL + '/b2b/success')This initiates a C2B confirmation and validation registration for a company's URLs
/* * c2bRegister(confirmationUrl, validationUrl, shortCode = null, responseType = 'Completed') * Example: */ await mpesaApi.c2bRegister(URL + '/c2b/validation', URL + '/c2b/success')This initiates a C2B transaction between an end-user and a company (paybill or till number)
/* * c2bSimulate(msisdn, amount, billRefNumber, commandId = 'CustomerPayBillOnline', shortCode = null) * Example: */ const testMSISDN = 254708374149 await mPesa.c2bSimulate(testMSISDN, 100, Math.random().toString(35).substr(2, 7))• M-Pesa Express Request - Lipa Na M-Pesa Online Payment API
This initiates a Lipa Na M-Pesa Online Payment transaction using STK Push.
/* * lipaNaMpesaOnline(senderMsisdn, amount, callbackUrl, accountRef, transactionDesc = 'Lipa na mpesa online', transactionType = 'CustomerPayBillOnline', shortCode = null, passKey = null) * Example: */ const testMSISDN = 254708374149 const amount = 100 const accountRef = Math.random().toString(35).substr(2, 7) await mpesaApi.lipaNaMpesaOnline(testMSISDN, amount, URL + '/lipanampesa/success', accountRef)• M-Pesa Express Query Request - Lipa Na M-Pesa Query Request API
This API checks the status of a Lipa Na M-Pesa Online Payment transaction
/* * lipaNaMpesaQuery(checkoutRequestId, shortCode = null, passKey = null) * Example: */ const checkoutRequestId ='ws_co_123456789' await mpesaApi.lipaNaMpesaQuery(checkoutRequestId)This initiates an M-Pesa transaction reversal on B2B, B2C or C2B API
/* * reversal(transactionId, amount, queueUrl, resultUrl, shortCode = null, remarks = 'Reversal', occasion = 'Reversal', initiator = null, receiverIdType = '11', commandId = 'TransactionReversal') * Example: */ await mpesaApi.reversal('LKXXXX1234', 100, URL + '/reversal/timeout', URL + '/reversal/success')This API is used to check the status of B2B, B2C and C2B transactions
/* * transactionStatus(transactionId, receiverParty, idType, queueUrl, resultUrl, remarks = 'TransactionReversal', occasion = 'TransactionReversal', initiator = null, commandId = 'TransactionStatusQuery') * Example: */ await mpesaApi.transactionStatus('LKXXXX1234', shortCode, 4, URL + '/transactionstatus/timeout', URL + '/transactionstatus/success')This initiates a request for the account balance of a shortcode
/* * accountBalance(shortCode, idType, queueUrl, resultUrl, remarks = 'Checking account balance', initiator = null, commandId = 'AccountBalance') * Example: */ const { shortCode } = mpesaApi.configs await mpesaApi.accountBalance(shortCode, 4, URL + '/accountbalance/timeout', URL + '/accountbalance/success')Testing needs you to clone this repo.
The command below runs both integration and unit test.
Integration tests launch a ngrok instance and await callbacks (you will need an active internet connection for this).
To run each separately, check package.json for the commands.
npm test You will need to first click on "Going Live" on Daraja
The only thing you need to tweek in this Libs config is environment:
new Mpesa({ consumerKey: '<your consumer key>', consumerSecret: '<your consumer secret>', environment: 'production', //<------ ..... })- E2E Integration Tests
- Deploy to Npm
- Reduce number of args
- Detailed Documentation
- Enumify
- Validators for MSISDN and other expected inputs
- More detailed Unit tests
- Handle all Promises
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -m 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request :D
| Contributor |
| DGatere |
| geofmureithi |
MIT