daraja
Version:
A NodeJS library to simplify integration with Safaricom's Daraja M-Pesa API
2,566 lines (780 loc) • 33.9 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: Mpesa</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: Mpesa</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>Mpesa<span class="signature">(shortcode, consumerKey, consumerSecret, environment<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h2>
<div class="class-description">This class implements the M-Pesa Daraja API methods</div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="Mpesa"><span class="type-signature"></span>new Mpesa<span class="signature">(shortcode, consumerKey, consumerSecret, environment<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<div class="description">
Creates an instance of Mpesa
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>shortcode</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">organization shortcode</td>
</tr>
<tr>
<td class="name"><code>consumerKey</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">app's consumer key</td>
</tr>
<tr>
<td class="name"><code>consumerSecret</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last">app's consumer secret</td>
</tr>
<tr>
<td class="name"><code>environment</code></td>
<td class="type">
<span class="param-type">Environment</span>
</td>
<td class="attributes">
<optional><br>
</td>
<td class="default">
'sandbox'
</td>
<td class="description last">application environment</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="accountBalanceRequest"><span class="type-signature">(async) </span>accountBalanceRequest<span class="signature">(identifierType, initiatorName, initiatorPassword, remarks, resultUrl, timeoutUrl)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the Account Balance Request API. Use this method to enquire the
balance on an M-Pesa shortcode
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>identifierType</code></td>
<td class="type">
<span class="param-type">1</span>
|
<span class="param-type">2</span>
|
<span class="param-type">4</span>
</td>
<td class="description last">Type of organization receiving the
transaction. 1 - MSISDN, 2 - Till Number, 4 - Organization shortcode</td>
</tr>
<tr>
<td class="name"><code>initiatorName</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">name of Initiator to initiating the
request</td>
</tr>
<tr>
<td class="name"><code>initiatorPassword</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">password of Initiator to initiating
the request</td>
</tr>
<tr>
<td class="name"><code>remarks</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">comments that are sent along with the
transaction</td>
</tr>
<tr>
<td class="name"><code>resultUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">path that stores information of transaction</td>
</tr>
<tr>
<td class="name"><code>timeoutUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">path that stores information of time out
transaction</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<div class="param-desc">
<span class="param-type">DarajaError</span>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.accountBalanceRequest(
4,
'initiator',
'p455w0rd',
'Remarks',
'http://resulturl.com',
'http://timeouturl.com'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="b2cPaymentRequest"><span class="type-signature">(async) </span>b2cPaymentRequest<span class="signature">(amount, recipient, initiatorName, initiatorPassword, commandId, remarks, occassion, resultUrl, timeoutUrl)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the B2C Payment Request API. Use this method to transact between an
M-Pesa short code to a phone number registered on M-Pesa
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>amount</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">amount of money being sent to the customer</td>
</tr>
<tr>
<td class="name"><code>recipient</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">customer mobile number to receive the amount</td>
</tr>
<tr>
<td class="name"><code>initiatorName</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">username of the M-Pesa B2C account API
operator</td>
</tr>
<tr>
<td class="name"><code>initiatorPassword</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">password of the M-Pesa B2C account API
operator</td>
</tr>
<tr>
<td class="name"><code>commandId</code></td>
<td class="type">
<span class="param-type">'SalaryPayment'</span>
|
<span class="param-type">'BusinessPayment'</span>
|
<span class="param-type">'PromotionPayment'</span>
</td>
<td class="description last">unique command that specifies B2C transaction type</td>
</tr>
<tr>
<td class="name"><code>remarks</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">any additional information to be associated with
the transaction</td>
</tr>
<tr>
<td class="name"><code>occassion</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">any additional information to be associated
with the transaction</td>
</tr>
<tr>
<td class="name"><code>resultUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">URL that will be used by M-Pesa to send
notification upon processing of the payment
request</td>
</tr>
<tr>
<td class="name"><code>timeoutUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">URL that will be used by API Proxy to send
notification incase the payment request is timed out while awaiting
processing in the queue</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<div class="param-desc">
<span class="param-type">DarajaError</span>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.b2cPaymentRequest(
100,
254712345678,
'initiator',
'p455w0rd',
'BusinessPayment',
'Remarks',
'Occassion',
'http://resulturl.com',
'http://timeouturl.com'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="c2bRegisterUrl"><span class="type-signature">(async) </span>c2bRegisterUrl<span class="signature">(validationUrl, confirmationUrl, responseType)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the C2B Register URL API. Use this method to register validation
and confirmation URLs on M-Pesa
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>validationUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">URL that receives the validation request
from API upon payment submission</td>
</tr>
<tr>
<td class="name"><code>confirmationUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">URL that receives the confirmation
request from API upon payment completion</td>
</tr>
<tr>
<td class="name"><code>responseType</code></td>
<td class="type">
<span class="param-type">'Completed'</span>
|
<span class="param-type">'Canceled'</span>
</td>
<td class="description last">specifies what is to
happen if for any reason the validation URL is nor reachable</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.c2bRegisterUrl(
'http://validationurl.com',
'http://confirmationurl.com'
'Completed'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="c2bSimulateTransaction"><span class="type-signature">(async) </span>c2bSimulateTransaction<span class="signature">(amount, sender, billReference)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the C2B Simulate Transaction API. Use this method to simulate a
payment made from the client phone's STK/SIM Toolkit menu
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>amount</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">amount being transacted</td>
</tr>
<tr>
<td class="name"><code>sender</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">phone number initiating the C2B transaction</td>
</tr>
<tr>
<td class="name"><code>billReference</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">used on CustomerPayBillOnline option only
and is where a customer is expected to enter a unique bill identifier,
e.g an Account Number</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<div class="param-desc">
<span class="param-type">DarajaError</span>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.c2bSimulateTransaction(
100,
254712345678,
'13123421'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="mpesaExpressQuery"><span class="type-signature">(async) </span>mpesaExpressQuery<span class="signature">(passkey, checkoutRequestId)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the Lipa Na M-Pesa Query Request API. Use this method to check the
status of a Lipa Na M-Pesa Online Payment
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>passkey</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">Lipa na M-Pesa Online Passkey</td>
</tr>
<tr>
<td class="name"><code>checkoutRequestId</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">global unique identifier of the
processed checkout transaction request</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-see">See:</dt>
<dd class="tag-see">
<ul>
<li><a href="Mpesa.html#mpesaExpressRequest">Mpesa.mpesaExpressRequest()</a></li>
</ul>
</dd>
</dl>
<h5>Throws:</h5>
<div class="param-desc">
<span class="param-type">DarajaError</span>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.mpesaExpressQuery(
'bfb279f9aa9bdbcf15...',
'ws_CO_DMZ_123212312_2342347678234'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="mpesaExpressRequest"><span class="type-signature">(async) </span>mpesaExpressRequest<span class="signature">(amount, sender, recipient, passkey, transactionType, accountReference, transactionDescription, callbackUrl)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the Lipa na M-Pesa Online Payment API. Use this method to initiate
an online payment on behalf of a customer
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>amount</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">money that the customer pays to the shortcode</td>
</tr>
<tr>
<td class="name"><code>sender</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">phone number of the customer sending the money</td>
</tr>
<tr>
<td class="name"><code>recipient</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last">organization shortcode to receive the funds</td>
</tr>
<tr>
<td class="name"><code>passkey</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">Lipa na M-Pesa Online Passkey</td>
</tr>
<tr>
<td class="name"><code>transactionType</code></td>
<td class="type">
<span class="param-type">'CustomerPayBillOnline'</span>
|
<span class="param-type">'CustomerBuyGoodsOnline'</span>
</td>
<td class="description last">transaction type that is used to identify the transaction when sending the
request to M-Pesa</td>
</tr>
<tr>
<td class="name"><code>accountReference</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">alphanumeric parameter that is defined
by your system as an Identifier of the transaction for
CustomerPayBillOnline transaction type</td>
</tr>
<tr>
<td class="name"><code>transactionDescription</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">any additional
information/comment that can be sent along with the request from your
system</td>
</tr>
<tr>
<td class="name"><code>callbackUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">valid secure URL that is used to receive
notifications from M-Pesa API and is the endpoint to which the results
will be sent by M-Pesa API</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<div class="param-desc">
<span class="param-type">DarajaError</span>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.mpesaExpressRequest(
100,
254712345678,
123456,
'bfb279f9aa9bdbcf15...',
'CustomerPayBillOnline',
'INV001',
'Regular payment',
'http://callbackurl.com'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="reversalRequest"><span class="type-signature">(async) </span>reversalRequest<span class="signature">(transactionId, initiatorName, initiatorPassword, remarks, occassion, resultUrl, timeoutUrl)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the Reversal Request API. Use this method to reverse an M-Pesa
transaction
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>transactionId</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">unique identifier to identify a
transaction on M-Pesa</td>
</tr>
<tr>
<td class="name"><code>initiatorName</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">name of initiator initiating the request</td>
</tr>
<tr>
<td class="name"><code>initiatorPassword</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">password of the initiator initiating
the request</td>
</tr>
<tr>
<td class="name"><code>remarks</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">comments that are sent along with the
transaction</td>
</tr>
<tr>
<td class="name"><code>occassion</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">optional parameter</td>
</tr>
<tr>
<td class="name"><code>resultUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">path that stores information of the
transaction</td>
</tr>
<tr>
<td class="name"><code>timeoutUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">path that stores information of time out
transaction</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Throws:</h5>
<div class="param-desc">
<span class="param-type">DarajaError</span>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.reversalRequest(
'MX000000000',
'initiator',
'p455w0rd',
'Remarks',
'Occassion',
'http://resulturl.com',
'http://timeouturl.com'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
<h4 class="name" id="transactionStatusRequest"><span class="type-signature">(async) </span>transactionStatusRequest<span class="signature">(transactionId, identifierType, initiatorName, initiatorPassword, remarks, occassion, resultUrl, timeoutUrl)</span><span class="type-signature"></span></h4>
<div class="description">
Invoke the Transaction Status Request API. Use this method to check the
transaction status
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>transactionId</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">unique identifier to identify a
transaction on M-Pesa</td>
</tr>
<tr>
<td class="name"><code>identifierType</code></td>
<td class="type">
<span class="param-type">1</span>
|
<span class="param-type">2</span>
|
<span class="param-type">4</span>
</td>
<td class="description last">type of organization receiving the
transaction</td>
</tr>
<tr>
<td class="name"><code>initiatorName</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">name of Initiator initiating the request</td>
</tr>
<tr>
<td class="name"><code>initiatorPassword</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">password of Initiator initiating the
request</td>
</tr>
<tr>
<td class="name"><code>remarks</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">comments that are sent along with the
transaction</td>
</tr>
<tr>
<td class="name"><code>occassion</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">optional parameter</td>
</tr>
<tr>
<td class="name"><code>resultUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">path that stores information of transaction</td>
</tr>
<tr>
<td class="name"><code>timeoutUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last">path that stores information of time out
transaction</td>
</tr>
</tbody>
</table>
<dl class="details">
</dl>
<h5>Example</h5>
<pre class="prettyprint"><code>mpesa.transactionStatusRequest(
'MX000000000',
4,
'initiator',
'p455w0rd',
'Remarks',
'Occassion',
'http://resulturl.com',
'http://timeouturl.com'
).then(response => {
// SUCCESS
// do something with the response
}).catch(error => {
// FAILED
// handle the error
})</code></pre>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Mpesa.html">Mpesa</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a>
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>