:zap: :bomb: :fire: :fire: :bomb: :zap:
An NPM Module built with NodeJs to help you with M-Pesa Daraja API calls.
Please note that this module is intended for use in a node environment on the backend and will raise a few issues if used on the client side/browser environment. This is mainly due to the file system.
Looking for contributors who can help write tests.
| Badge | |
|---|---|
| Travis |  |
| Latest | |
| Minified | |
| MinZip |
Ready Methods
Mpesa-Api uses Node Package Manager
npm i mpesa-api
Or Yarn
yarn add mpesa-api
You Will need a few things from Safaricom before development.
// import package
import { Mpesa } from "mpesa-api";
//OR
const Mpesa = require("mpesa-api").Mpesa;
// create a new instance of the api
const mpesa = new Mpesa(credentials, environment);
A moment to explain the above. credentials should be an object containing key,secret,initiator password, security credential and certificate path as the properties/keys.
//example
const credentials = {
clientKey: 'YOUR_CONSUMER_KEY_HERE',
clientSecret: 'YOUR_CONSUMER_SECRET_HERE',
initiatorPassword: 'YOUR_INITIATOR_PASSWORD_HERE',
securityCredential: 'YOUR_SECURITY_CREDENTIAL',
certificatePath: 'keys/example.cert'
};
// For the initiator_password, use the security credential from the test credentials page.link :https://developer.safaricom.co.ke/test_credentials
// security credential is optional. Set this if you're getting Initiator Name is invalid errors. You can generate your security credential on the test credentials page for sandbox environment or from your mpesa web portal for production environment.
// certificate path is otional. I've provided ceritificates for sandbox and production by default. If you choose not to include it Pass it as null. If you have passed `securityCredential` you should pass `certificatePath` as `null`
const credentials = {
...,
certificatePath: null
};
You can get initiator password from Your Portal(production) or from test credentials(Sandbox). It will be the
Security Credential (Shortcode 1). You can generate your security credential on the test credentials page for sandbox environment or from your mpesa web portal for production environment. See this guide for production environment(last step on the go live guide).
Environment should be a string. It can be either 'production' or 'sandbox'
const environment = "sandbox";
//or
const environment = "production";
This Has Been Disabled as of January 2019 and I have therefore removed it for now.
This API enables Business to Business (B2B) transactions between a business and another business. Use of this API requires a valid and verified B2B M-Pesa short code for the business initiating the transaction and the both businesses involved in the transaction.
mpesa
.b2b({
InitiatorName: "Initiator Name",
Amount: 1000 /* 1000 is an example amount */,
PartyA: "Party A",
PartyB: "Party B",
AccountReference: "Account Reference",
QueueTimeOutURL: "Queue Timeout URL",
ResultURL: "Result URL",
CommandID: "Command ID" /* OPTIONAL */,
SenderIdentifierType: 4 /* OPTIONAL */,
RecieverIdentifierType: 4 /* OPTIONAL */,
Remarks: "Remarks" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
MerchantToMerchantTransfer possible values are: BusinessPayBill, MerchantToMerchantTransfer, MerchantTransferFromMerchantToWorking, MerchantServicesMMFAccountTransfer, AgencyFloatAdvanceThis API enables Business to Customer (B2C) transactions between a company and customers who are the end-users of its products or services. Use of this API requires a valid and verified B2C M-Pesa Short code.
mpesa
.b2c({
Initiator: "Initiator Name",
Amount: 1000 /* 1000 is an example amount */,
PartyA: "Party A",
PartyB: "Party B",
QueueTimeOutURL: "Queue Timeout URL",
ResultURL: "Result URL",
CommandID: "Command ID" /* OPTIONAL */,
Occasion: "Occasion" /* OPTIONAL */,
Remarks: "Remarks" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
This API enables Paybill and Buy Goods merchants to integrate to M-Pesa and receive real time payments notifications.
The C2B Register URL API registers the 3rd party’s confirmation and validation URLs to M-Pesa ; which then maps these URLs to the 3rd party shortcode. Whenever M-Pesa receives a transaction on the shortcode, M-Pesa triggers a validation request against the validation URL and the 3rd party system responds to M-Pesa with a validation response (either a success or an error code). The response expected is the success code the 3rd party
M-Pesa completes or cancels the transaction depending on the validation response it receives from the 3rd party system. A confirmation request of the transaction is then sent by M-Pesa through the confirmation URL back to the 3rd party which then should respond with a success acknowledging the confirmation.
mpesa
.c2bregister({
ShortCode: "Short Code",
ConfirmationURL: "Confirmation URL",
ValidationURL: "Validation URL",
ResponseType: "Response Type",
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
mpesa
.c2bsimulate({
ShortCode: 123456,
Amount: 1000 /* 1000 is an example amount */,
Msisdn: 254792123456,
CommandID: "Command ID" /* OPTIONAL */,
BillRefNumber: "Bill Reference Number" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
CustomerPayBillOnlineThe Account Balance API requests for the account balance of a shortcode.
mpesa
.accountBalance({
Initiator: "Initiator Name",
PartyA: "Party A",
IdentifierType: "Identifier Type",
QueueTimeOutURL: "Queue Timeout URL",
ResultURL: "Result URL",
CommandID: "Command ID" /* OPTIONAL */,
Remarks: "Remarks" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
AccountBalanceTransaction Status API checks the status of a B2B, B2C and C2B APIs transactions.
mpesa
.transactionStatus({
Initiator: "Initiator",
TransactionID: "Transaction ID",
PartyA: "Party A",
IdentifierType: "Identifier Type",
ResultURL: "Result URL",
QueueTimeOutURL: "Queue Timeout URL",
CommandID: "Command ID" /* OPTIONAL */,
Remarks: "Remarks" /* OPTIONAL */,
Occasion: "Occasion" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
TransactionStatusQuery.Lipa na M-Pesa Online Payment API is used to initiate a M-Pesa transaction on behalf of a customer using STK Push. This is the same technique mySafaricom App uses whenever the app is used to make payments.
mpesa
.lipaNaMpesaOnline({
BusinessShortCode: 123456,
Amount: 1000 /* 1000 is an example amount */,
PartyA: "Party A",
PhoneNumber: "Phone Number",
CallBackURL: "CallBack URL",
AccountReference: "Account Reference",
passKey: "Lipa Na Mpesa Pass Key",
TransactionType: "Transaction Type" /* OPTIONAL */,
TransactionDesc: "Transaction Description" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
CustomerPayBillOnlinempesa
.lipaNaMpesaQuery({
BusinessShortCode: 123456,
CheckoutRequestID: "Checkout Request ID",
passKey: "Lipa Na Mpesa Pass Key",
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
Reverses a B2B, B2C or C2B M-Pesa transaction.
mpesa
.reversal({
Initiator: "Initiator",
TransactionID: "Transaction ID",
Amount: 1000 /* 1000 is an example amount */,
ReceiverParty: "Reciever Party",
ResultURL: "Result URL",
QueueTimeOutURL: "Queue Timeout URL",
CommandID: "Command ID" /* OPTIONAL */,
RecieverIdentifierType: 11 /* OPTIONAL */,
Remarks: "Remarks" /* OPTIONAL */,
Occasion: "Ocassion" /* OPTIONAL */,
})
.then((response) => {
//Do something with the response
//eg
console.log(response);
})
.catch((error) => {
//Do something with the error;
//eg
console.error(error);
});
11TransactionReversalYou might need to whitelist Mpesa IPs listed below on the server/firewall that receives the callbacks.
You can try it out on Runkit
If you Wish to build
npm install to install dependenciesnpm run build to buildnpm run start:dev to run package in development modegit checkout -b my-new-featuregit commit -m 'Add some feature'git push origin my-new-feature| Name | Role |
|---|---|
| Newton Munene | Contributor |
| Nelson Bwogora | Contributor |
MIT License
Copyright (c) 2018 Newton Munene
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
FAQs
An NPM Module built with NodeJs to help you with M-Pesa Daraja API calls.
The npm package mpesa-api receives a total of 167 weekly downloads. As such, mpesa-api popularity was classified as not popular.
We found that mpesa-api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Socket detected malicious node-ipc versions with obfuscated stealer/backdoor behavior in a developing npm supply chain attack.
Security News
TeamPCP and BreachForums are promoting a Shai-Hulud supply chain attack contest with a $1,000 prize for the biggest package compromise.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.