mpesa@1.0.2

buyGoods(data, options)

checkTransactionStatus(data, options)

registerUrl(data, options)

remitTax(data, options)

request(method, path, body, options)

stkPush(data, options)

Functions

buyGoods

buyGoods(data, options) ⇒ Operation

Pay for goods and services directly from your business account to a till number, merchant store number or Merchant HO

Param	Type	Description
data	BuyGoodsObject	The object that will be attached to the POST request body
options	RequestOptions	Optional request object. Includes headers, error mappings and query params

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

Example: Pay for goods

buyGoods({
    "Initiator": "testapi",
    "SecurityCredential": "sbMXpuhMX5LzieNiDrx9TgscfaBxxvie0WlBDdGli4MWu4s5gbhYVlBy+T89xHQdoYwcG202KNp403ln2dLFnytPqw==",
    "Amount": 1,
    "PartyA": 600999,
    "PartyB": 600000,
    "AccountReference": 353353,
    "Requester": 254708374149,
    "Remarks": "ok",
    "QueueTimeOutURL": "https://mydomain.com/b2b/queue/",
    "ResultURL": "https://mydomain.com/b2b/result/"
});

---

checkTransactionStatus

checkTransactionStatus(data, options) ⇒ Operation

Check the status of the transaction

Param	Type	Description
data	TransactionStatusObject	The object that will be attached to the POST request body
options	RequestOptions	Optional request object. Includes headers, error mappings and query params

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

Example: Check status of a transaction

checkTransactionStatus({
    "Initiator": "testapi",
    "SecurityCredential": "ctHDk+dN14A22B5GyQQvISSTY3K1tVnCTuQGoG7PsTCadzTkl5wz44Rhpkb0BZDvfRA==",
    "TransactionID": "OEI2AK4Q16",
    "PartyA": 600998,
    "IdentifierType": 4,
    "ResultURL": "https://mydomain.com/TransactionStatus/result/",
    "QueueTimeOutURL": "https://mydomain.com/TransactionStatus/queue/",
    "Remarks": "fdfdfdfdf",
    "Occassion": "null",
});

---

registerUrl

registerUrl(data, options) ⇒ Operation

Register a URL that allows receiving payment notifications to your paybill.

Param	Type	Description
data	RegisterUrlObject	The object that will be attached to the POST request body
options	RequestOptions	Optional request object. Includes headers, error mappings and query params

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

Example: Register a URL to receive payment notifications

registerUrl({
    "ShortCode": 600426,
    "ResponseType": "Completed",
    "ConfirmationURL": "https://mydomain.com/confirmation",
    "ValidationURL": "https://mydomain.com/validation"
});

---

remitTax

remitTax(data, options) ⇒ Operation

Remit tax to the Kenya Revenue Authority (KRA).

Param	Type	Description
data	RemitTaxObject	The object that will be attached to the POST request body
options	RequestOptions	Optional request object. Includes headers, error mappings and query params

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

Example: Pay tax to KRA

remitTax({
    "Initiator": "testapi",
    "SecurityCredential": "Uq1qluCjSYfMF3XEvlpfuatnWwWerwq42fB+mMd8nsKdAVO04DGHhG/s3xO3g7POki9B8i7cSoEkBux4bQrlDLDWJhaTrt1TdbE+ZQ==",
    "Amount": 1,
    "PartyA": 600995,
    "AccountReference": 353353,
    "Remarks": "ok",
    "QueueTimeOutURL": "https://mydomain.com/b2b/queue/",
    "ResultURL": "https://mydomain.com/b2b/result/"
})

---

request

request(method, path, body, options) ⇒ Operation

Make a general HTTP request

Param	Type	Description
method	string	HTTP method to use
path	string	Path to resource.
body	object	Object which will be attached to the POST body
options	RequestOptions	Optional request options

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

Example: Register a URL to receive payment notifications

request("POST", "/mpesa/c2b/v1/registerurl", 
 {
   "ShortCode": 600426,
   "ResponseType": "Completed",
   "ConfirmationURL": "https://mydomain.com/confirmation",
   "ValidationURL": "https://mydomain.com/validation"
 });

---

stkPush

stkPush(data, options) ⇒ Operation

Initiate a STK pin prompt to a Safaricom mobile number.

Param	Type	Description
data	STKPushObject	The object that will be attached to the POST request body
options	RequestOptions	Optional request object. Includes headers, error mappings and query params

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

Example: Initiate STK Push

stkPush({
    "Amount": 1,
    "PartyA": 254708374149,
    "PartyB": 174379,
    "PhoneNumber": 254708374149,
    "CallBackURL": "https://mydomain.com/path",
    "AccountReference": "CompanyXLTD",
    "TransactionDesc": "Payment of X"
});

---

Interfaces

BuyGoodsObject

Buy goods parameter definition

Properties

Name	Type	Description
Initiator	string	The M-Pesa API operator username. This user needs Org Business Pay Bill API initiator role on M-Pesa
SecurityCredential	string	The encrypted password of the M-Pesa API operator.
Amount	number	The transaction amount.
PartyA	number	Your shortcode. The shortcode from which money will be deducted.
AccountReference	string	The account number to be associated with the payment. Up to 13 characters
Remarks	string	Any additional information to be associated with the transaction.
QueueTimeOutURL	URL	A URL that will be used to notify your system in case the request times out before processing.
ResultURL	URL	A URL that will be used to send transaction results after processing.

---

HttpState

State object

Properties

Name	Description
data	the parsed response body
response	the response from the DARAJA API server (excluding the body)
references	an array of all previous data objects used in the Job

---

RegisterUrlObject

Register URL parameter definition

Properties

Name	Type	Description
ShortCode	numeric	Usually, a unique number is tagged to an M-PESA pay bill/till number of the organization.
ResponseType	string	This parameter specifies what is to happen if for any reason the validation URL is not reachable. Sample values: 'Canceled', 'Completed'
ConfirmationURL	URL	This is the URL that receives the confirmation request from API upon payment completion.
ValidationURL	URL	This is the URL that receives the validation request from the API upon payment submission.

---

RemitTaxObject

Remit tax parameter definition

Properties

Name	Type	Description
Initiator	string	The M-Pesa API operator username.
SecurityCredential	string	The encrypted password of the M-Pesa API operator.
Amount	number	The transaction amount.
PartyA	number	This is your own shortcode from which the money will be deducted.
AccountReference	string	The payment registration number (PRN) issued by KRA.
Remarks	string	Any additional information to be associated with the transaction.
QueueTimeOutURL	URL	A URL that will be used to notify your system in case the request times out before processing.
ResultURL	URL	A URL that will be used to send transaction results after processing.

---

RequestOptions

Options provided to the HTTP request

Properties

Name	Type	Description
errors	object	Map of errorCodes -> error messages, ie, { 404: 'Resource not found;' }. Pass false to suppress errors for this code.
query	object	An object of query parameters to be encoded into the URL.
headers	object	An object of headers to append to the request.

---

STKPushObject

STKPush request data object

Properties

Name	Type	Description
Amount	number	Amount charged.
PartyA	number	The phone number that receives the STK push prompt. Expected to be a valid Safaricom Number that is M-pesa registered in the format 2547XXXXXXXX
PartyB	number	The organization that receives the funds
PhoneNumber	number	The mobile number to receive the STK pin prompt
CallBackURL	URL	A valid secure URL that is used to receive notifications from M-Pesa API. It is the endpoint to which the results will be sent by M-Pesa API
AccountReference	string	Along with the business name, this value is also displayed to the customer in the STK pin prompt message. Maximum of 12 characters
TransactionDesc	string	Any additional information/comment that can be sent along with the request from you system.

---

TransactionStatusObject

Check transaction status data object.

Properties

Name	Type	Description
Initiator	string	The name of the initiator initiating the request.
SecurityCredential	string	Encrypted credential of the user getting transaction status.
TransactionID	string	Unique identifier to identify a transaction on Mpesa.
PartyA	number	Organization/MSISDN receiving the transaction.
IdentifierType	number	Type of organization receiving the transaction. Example: "4" Orgnaization shortcode.
ResultURL	URL	The path that stores information of a transaction.
QueueTimeOutURL	URL	The path that stores information of timeout transaction.
Remarks	string	Comments that are sent along with the transaction.
Occassion	string	Optional parameter.

---