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.

Important: Update 23-06-2017

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.

Instructions

Request Payment

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:

Initiate Payment Request:

POST https://project-mulla-companyname.herokuapp.com/api/v1/payment/request

Body Parameters:

phoneNumber - The phone number of your client
totalAmount - The total amount you are charging the client
referenceID [optional] - The reference ID of the order or service
merchantTransactionID [optional] - This specific order's or service's transaction ID

NOTE: If merchantTransactionID or referenceID are not provided a time-based and random UUID is generated for each respectively.

Sample request using CURL in the command line/terminal:

$ 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' \

Expected Response

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"
  }
}

Next step: confirmation

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

Installation

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.

Requirements

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

Install through Github

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

Testing

It's now ready to launch

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

Do a test run

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"
  }
}

This project uses GPLv3 LICENSE

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.

kn9ts / project-mulla

readme