What MPESA G2 API should have been in the 21st century.
PLEASE NOTE: Mediates only C2B portion for now.
Project Mulla is a MPESA API RESTful mediator. It lets you make familiar HTTP REST requests, transforming your requests to the fiddling dreaded SOAP/XML requests that the Safaricom MPESA G2 API only understands. It then communicates with the MPESA API gateway, transforming all SOAP responses from the SAG to RESTful JSON responses that you then consume effortlessly.
In short, it’ll deal with all of the SOAP shenanigans while you REST. Everybody wins!
The aim of Project Mulla is to create a REST API middleman that interfaces with the MPESA G2 API for you.
When one now pings the endpoint /payment/request
it initializes the payment and on response confirms the payment by also hitting the endpoint payment/confirm
automatically
This means you no longer have to make a second call to Project Mulla to confirm the payment thus hitting up the user's phone with the USSD prompt. One call to payment/request
should handle this automatically.
This initial step is to tell the SAG to initialise a payment transaction for you. After initialisation, you then make another request to the SAG as a confirmation signaling the SAG to process the payment request.
Assuming Project Mulla is now your mediator, you'd now make a POST request to Project Mulla. Not the Safaricom Access Gateway.
See below how you'd make this initial request:
POST
https://project-mulla-companyname.herokuapp.com/api/v1/payment/request
Body Parameters:
phoneNumber
- The phone number of your clienttotalAmount
- The total amount you are charging the clientreferenceID
[optional] - The reference ID of the order or servicemerchantTransactionID
[optional] - This specific order's or service's transaction ID
NOTE: If
merchantTransactionID
orreferenceID
are not provided a time-based and random UUID is generated for each respectively.
$ curl -i -X POST \
--url http://project-mulla-companyname.herokuapp.com/api/v1/payment/request \
--data 'phoneNumber=254723000000' \
--data 'totalAmount=45.00' \
--data 'clientName="Eugene Mutai"' \
--data 'clientLocation=Kilimani' \
If all goes well you get HTTP status code 200
accompanied with a similar structured JSON response:
{
"response": {
"return_code": "00",
"status_code": 200,
"message": "Transaction carried successfully",
"trx_id": "453c70c4b2434bd94bcbafb17518dc8e",
"description": "success",
"cust_msg": "to complete this transaction, enter your bonga pin on your handset. if you don't have one dial *126*5# for instructions",
"reference_id": "3e3beff0-fc05-417a-bbf2-190ee19a5e58",
"merchant_transaction_id": "95d64500-2514-11e6-bcb8-a7f8e1c786c4",
"amount_in_double_float": "45.00",
"client_phone_number": "254723001575",
"extra_payload": {},
"time_stamp": "20160528234142"
}
}
You are to use trx_id
or merchant_transaction_id
to make the confirmation payment
request. The confirmation request is to authorize the SAG to process the payment request. On confirmation, it
triggers a pop up on your client's mobile phone to complete the payment.
Find the complete documentation here
Installing Project Mulla is easy and straight-forward, but there are a few requirements you’ll need to make sure your system has before you start.
You will need to install some stuff, if they are not yet installed in your machine:
If you've already installed the above you may need to only update npm to the latest version:
$ sudo npm update -g npm
Best way to install Project Mulla is to clone it from Github
To clone/download the boilerplate
$ git clone https://github.com/kn9ts/project-mulla.git
After cloning, get into your cloned Project Mulla's directory/folder
$ cd project-mulla
Install all of the projects dependencies with:
$ npm install
Create app.yaml
configurations file
The last but not the least step is to create a app.yaml
file with your configurations in the root
directory of project-mulla
.
This is the same folder directory where index.js
can be found.
Your app.yaml
should look like the example below, only with your specific configuration values:
env_variables:
PAYBILL_NUMBER: '898998'
PASSKEY: 'a8eac82d7ac1461ba0348b0cb24d3f8140d3afb9be864e56a10d7e8026eaed66'
MERCHANT_ENDPOINT: 'http://merchant-endpoint.com/mpesa/payment/complete'
# Everything below is only relevant if you are looking
# to deploy Project Mulla to Google App Engine.
runtime: nodejs
vm: true
skip_files:
- ^(.*/)?.*/node_modules/.*$
NOTE: The PAYBILL_NUMBER
and PASSKEY
are provided by Safaricom once you have registered for the MPESA G2 API.
NOTE: The details above only serve as examples
First run the command npm test
on your terminal and see if everything is all good. Then run:
$ npm start
> project-mulla@0.1.1 start ../project-mulla
> node index.js
Your secret session key is: 5f06b1f1-1bff-470d-8198-9ca2f18919c5
Express server listening on 8080, in development mode
Now make a test run using CURL:
$ curl -i -X POST \
--url http://localhost:8080/api/v1/payment/request \
--data 'phoneNumber=254723000000' \
--data 'totalAmount=10.00' \
--data 'clientName="Eugene Mutai"' \
--data 'clientLocation=Kilimani' \
Or if you have httpie installed:
$ http POST localhost:8080/api/v1/payment/request \
phoneNumber=254723000000 \
totalAmount=10.00 \
clientName='Eugene Mutai' \
clientLocation='Kilimani'
Once the request is executed, your console should print a similar structured response as below:
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 534
Content-Type: application/json; charset=utf-8
Date: Sun, 22 May 2016 13:12:09 GMT
ETag: W/"216-NgmF2VWb0PIkUOKfya6WlA"
X-Powered-By: Express
set-cookie: connect.sid=s:iWfXH7rbAvXz7cYgmurhGTHDn0LNBmNt; Path=/; HttpOnly
{
"response": {
"return_code": "00",
"status_code": 200,
"message": "Transaction carried successfully",
"trx_id": "453c70c4b2434bd94bcbafb17518dc8e",
"description": "success",
"cust_msg": "to complete this transaction, enter your bonga pin on your handset. if you don't have one dial *126*5# for instructions",
"reference_id": "3e3beff0-fc05-417a-bbf2-190ee19a5e58",
"merchant_transaction_id": "95d64500-2514-11e6-bcb8-a7f8e1c786c4",
"amount_in_double_float": "10.00",
"client_phone_number": "254723001575",
"extra_payload": {},
"time_stamp": "20160528234142"
}
}
TL;DR Here's what the license entails:
1. Anyone can copy, modify and distribute this software.
2. You have to include the license and copyright notice with each and every distribution.
3. You can use this software privately.
4. You can use this software for commercial purposes.
5. If you dare build your business solely from this code, you risk open-sourcing the whole code base.
6. If you modify it, you have to indicate changes made to the code.
7. Any modifications of this code base MUST be distributed with the same license, GPLv3.
8. This software is provided without warranty.
9. The software author or license can not be held liable for any damages inflicted by the software.
More information on the LICENSE can be found here
DISCLAIMER: All opinions aired in this repo are ours and do not reflect any company or organisation any contributor is involved with.