Class: Mpesa

Mpesa(shortcode, consumerKey, consumerSecret, environmentopt)

This class implements the M-Pesa Daraja API methods

Constructor

new Mpesa(shortcode, consumerKey, consumerSecret, environmentopt)

Creates an instance of Mpesa
Parameters:
Name Type Attributes Default Description
shortcode number organization shortcode
consumerKey string app's consumer key
consumerSecret string app's consumer secret
environment Environment <optional>
 'sandbox' application environment

Methods

(async) accountBalanceRequest(identifierType, initiatorName, initiatorPassword, remarks, resultUrl, timeoutUrl)

Invoke the Account Balance Request API. Use this method to enquire the balance on an M-Pesa shortcode
Parameters:
Name Type Description
identifierType 1 | 2 | 4 Type of organization receiving the transaction. 1 - MSISDN, 2 - Till Number, 4 - Organization shortcode
initiatorName string name of Initiator to initiating the request
initiatorPassword string password of Initiator to initiating the request
remarks string comments that are sent along with the transaction
resultUrl string path that stores information of transaction
timeoutUrl string path that stores information of time out transaction
Throws:
DarajaError
Example
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
})

(async) b2cPaymentRequest(amount, recipient, initiatorName, initiatorPassword, commandId, remarks, occassion, resultUrl, timeoutUrl)

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
Parameters:
Name Type Description
amount number amount of money being sent to the customer
recipient number customer mobile number to receive the amount
initiatorName string username of the M-Pesa B2C account API operator
initiatorPassword string password of the M-Pesa B2C account API operator
commandId 'SalaryPayment' | 'BusinessPayment' | 'PromotionPayment' unique command that specifies B2C transaction type
remarks string any additional information to be associated with the transaction
occassion string any additional information to be associated with the transaction
resultUrl string URL that will be used by M-Pesa to send notification upon processing of the payment request
timeoutUrl string URL that will be used by API Proxy to send notification incase the payment request is timed out while awaiting processing in the queue
Throws:
DarajaError
Example
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
})

(async) c2bRegisterUrl(validationUrl, confirmationUrl, responseType)

Invoke the C2B Register URL API. Use this method to register validation and confirmation URLs on M-Pesa
Parameters:
Name Type Description
validationUrl string URL that receives the validation request from API upon payment submission
confirmationUrl string URL that receives the confirmation request from API upon payment completion
responseType 'Completed' | 'Canceled' specifies what is to happen if for any reason the validation URL is nor reachable
Example
mpesa.c2bRegisterUrl(
  'http://validationurl.com',
  'http://confirmationurl.com'
  'Completed'
).then(response => {
  // SUCCESS
  // do something with the response
}).catch(error => {
  // FAILED
  // handle the error
})

(async) c2bSimulateTransaction(amount, sender, billReference)

Invoke the C2B Simulate Transaction API. Use this method to simulate a payment made from the client phone's STK/SIM Toolkit menu
Parameters:
Name Type Description
amount number amount being transacted
sender number phone number initiating the C2B transaction
billReference string used on CustomerPayBillOnline option only and is where a customer is expected to enter a unique bill identifier, e.g an Account Number
Throws:
DarajaError
Example
mpesa.c2bSimulateTransaction(
  100,
  254712345678,
  '13123421'
).then(response => {
  // SUCCESS
  // do something with the response
}).catch(error => {
  // FAILED
  // handle the error
})

(async) mpesaExpressQuery(passkey, checkoutRequestId)

Invoke the Lipa Na M-Pesa Query Request API. Use this method to check the status of a Lipa Na M-Pesa Online Payment
Parameters:
Name Type Description
passkey string Lipa na M-Pesa Online Passkey
checkoutRequestId string global unique identifier of the processed checkout transaction request
See:
Throws:
DarajaError
Example
mpesa.mpesaExpressQuery(
  'bfb279f9aa9bdbcf15...',
  'ws_CO_DMZ_123212312_2342347678234'
).then(response => {
  // SUCCESS
  // do something with the response
}).catch(error => {
  // FAILED
  // handle the error
})

(async) mpesaExpressRequest(amount, sender, recipient, passkey, transactionType, accountReference, transactionDescription, callbackUrl)

Invoke the Lipa na M-Pesa Online Payment API. Use this method to initiate an online payment on behalf of a customer
Parameters:
Name Type Description
amount number money that the customer pays to the shortcode
sender number phone number of the customer sending the money
recipient number organization shortcode to receive the funds
passkey string Lipa na M-Pesa Online Passkey
transactionType 'CustomerPayBillOnline' | 'CustomerBuyGoodsOnline' transaction type that is used to identify the transaction when sending the request to M-Pesa
accountReference string alphanumeric parameter that is defined by your system as an Identifier of the transaction for CustomerPayBillOnline transaction type
transactionDescription string any additional information/comment that can be sent along with the request from your system
callbackUrl string 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
Throws:
DarajaError
Example
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
})

(async) reversalRequest(transactionId, initiatorName, initiatorPassword, remarks, occassion, resultUrl, timeoutUrl)

Invoke the Reversal Request API. Use this method to reverse an M-Pesa transaction
Parameters:
Name Type Description
transactionId string unique identifier to identify a transaction on M-Pesa
initiatorName string name of initiator initiating the request
initiatorPassword string password of the initiator initiating the request
remarks string comments that are sent along with the transaction
occassion string optional parameter
resultUrl string path that stores information of the transaction
timeoutUrl string path that stores information of time out transaction
Throws:
DarajaError
Example
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
})

(async) transactionStatusRequest(transactionId, identifierType, initiatorName, initiatorPassword, remarks, occassion, resultUrl, timeoutUrl)

Invoke the Transaction Status Request API. Use this method to check the transaction status
Parameters:
Name Type Description
transactionId string unique identifier to identify a transaction on M-Pesa
identifierType 1 | 2 | 4 type of organization receiving the transaction
initiatorName string name of Initiator initiating the request
initiatorPassword string password of Initiator initiating the request
remarks string comments that are sent along with the transaction
occassion string optional parameter
resultUrl string path that stores information of transaction
timeoutUrl string path that stores information of time out transaction
Example
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
})