{"id":13941713,"url":"https://github.com/kn9ts/project-mulla","last_synced_at":"2025-07-20T05:30:51.786Z","repository":{"id":45643135,"uuid":"43205959","full_name":"kn9ts/project-mulla","owner":"kn9ts","description":"Talk to MPESA API via a REST API. Bringing the MPESA G2 API to the 21st century. --","archived":false,"fork":false,"pushed_at":"2024-10-13T05:59:46.000Z","size":1338,"stargazers_count":301,"open_issues_count":16,"forks_count":117,"subscribers_count":46,"default_branch":"master","last_synced_at":"2024-11-27T10:36:17.079Z","etag":null,"topics":["mediator","mobile-money","mpesa","mpesa-api","online-payments","payments","safaricom","sag","soap","xml"],"latest_commit_sha":null,"homepage":"http://kn9ts.github.io/project-mulla/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kn9ts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-26T13:16:52.000Z","updated_at":"2024-07-07T19:33:43.000Z","dependencies_parsed_at":"2023-11-28T15:27:02.400Z","dependency_job_id":"57207844-19ba-4e4c-91e9-da57b26914bb","html_url":"https://github.com/kn9ts/project-mulla","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kn9ts/project-mulla","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kn9ts%2Fproject-mulla","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kn9ts%2Fproject-mulla/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kn9ts%2Fproject-mulla/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kn9ts%2Fproject-mulla/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kn9ts","download_url":"https://codeload.github.com/kn9ts/project-mulla/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kn9ts%2Fproject-mulla/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266071519,"owners_count":23871940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mediator","mobile-money","mpesa","mpesa-api","online-payments","payments","safaricom","sag","soap","xml"],"created_at":"2024-08-08T02:01:25.815Z","updated_at":"2025-07-20T05:30:50.828Z","avatar_url":"https://github.com/kn9ts.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Coverage Status](https://coveralls.io/repos/github/kn9ts/project-mulla/badge.svg?branch=master)](https://coveralls.io/github/kn9ts/project-mulla?branch=master)\n[![Build Status](https://semaphoreci.com/api/v1/kn9ts/project-mulla/branches/master/badge.svg)](https://semaphoreci.com/kn9ts/project-mulla)\n\n![](http://res.cloudinary.com/dpmk2cnpi/image/upload/v1463934821/banner_vj7z5u.png)\n\n\u003e __What MPESA G2 API should have been in the 21st century.__\n\n\u003e __PLEASE NOTE: Mediates only C2B portion for now.__\n\n\u003cp class=\"lead\"\u003e\u003cstrong\u003eProject Mulla is a MPESA API RESTful mediator\u003c/strong\u003e. It lets you make familiar HTTP REST requests, \u003cstrong\u003etransforming your requests\u003c/strong\u003e 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 \u003cstrong\u003eRESTful JSON responses\u003c/strong\u003e that you then consume effortlessly.\u003c/p\u003e\n\u003cblockquote\u003eIn short, it’ll deal with all of the SOAP shenanigans while you REST. Everybody wins!\u003c/blockquote\u003e\n\nThe aim of **Project Mulla** is to create a REST API middleman that interfaces with the **MPESA G2 API** for you.\n\n# Important: Update 23-06-2017\n\nWhen 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\n\nThis 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.\n\n\n# Instructions\n\n## Request Payment\n\nThis initial step is to tell the SAG to initialise a payment transaction for you. After\ninitialisation, you then make another request to the SAG as a confirmation signaling the SAG to\nprocess the payment request.\n\nAssuming __Project Mulla__ is now your mediator, you'd now make a __POST__ request to\n__Project Mulla__. _Not the Safaricom Access Gateway_.\n\nSee below how you'd make this initial request:\n\n### Initiate Payment Request:\n\n__`POST`__ __`https://project-mulla-companyname.herokuapp.com/api/v1/payment/request`__\n\n_Body Parameters_:\n\n- `phoneNumber` - The phone number of your client\n- `totalAmount` - The total amount you are charging the client\n- `referenceID` [optional] - The reference ID of the order or service\n- `merchantTransactionID` [optional] - This specific order's or service's transaction ID\n\n\u003e __NOTE:__ If `merchantTransactionID` or `referenceID` are not provided a time-based and random\nUUID is generated for each respectively.\n\n### Sample request using CURL in the command line/terminal:\n\n```bash\n$ curl -i -X POST \\\n--url http://project-mulla-companyname.herokuapp.com/api/v1/payment/request \\\n--data 'phoneNumber=254723000000' \\\n--data 'totalAmount=45.00' \\\n--data 'clientName=\"Eugene Mutai\"' \\\n--data 'clientLocation=Kilimani' \\\n```\n\n### Expected Response\n\nIf all goes well you get HTTP status code __`200`__ accompanied with a similar structured JSON response:\n\n```json\n{\n  \"response\": {\n    \"return_code\": \"00\",\n    \"status_code\": 200,\n    \"message\": \"Transaction carried successfully\",\n    \"trx_id\": \"453c70c4b2434bd94bcbafb17518dc8e\",\n    \"description\": \"success\",\n    \"cust_msg\": \"to complete this transaction, enter your bonga pin on your handset. if you don't have one dial *126*5# for instructions\",\n    \"reference_id\": \"3e3beff0-fc05-417a-bbf2-190ee19a5e58\",\n    \"merchant_transaction_id\": \"95d64500-2514-11e6-bcb8-a7f8e1c786c4\",\n    \"amount_in_double_float\": \"45.00\",\n    \"client_phone_number\": \"254723001575\",\n    \"extra_payload\": {},\n    \"time_stamp\": \"20160528234142\"\n  }\n}\n```\n\n## Next step: confirmation\n\nYou are to use `trx_id` or `merchant_transaction_id` to make the confirmation payment\nrequest. The confirmation request is to authorize the SAG to process the payment request. On confirmation, it\ntriggers a pop up on your client's mobile phone to complete the payment.\n\n[Find the complete documentation here](http://kn9ts.github.io/project-mulla/docs)\n\n\n# Installation\n\nInstalling Project Mulla is easy and straight-forward, but there are a few requirements you’ll need\nto make sure your system has before you start.\n\n## Requirements\n\nYou will need to install some stuff, if they are not yet installed in your machine:\n\n* [Node.js (v4.3.2 or higher; LTS)](http://nodejs.org)\n* [NPM (v3.5+; bundled with node.js installation package)](https://docs.npmjs.com/getting-started/installing-node#updating-npm)\n\nIf you've already installed the above you may need to only update **npm** to the latest version:\n\n```bash\n$ sudo npm update -g npm\n```\n\n---\n\n## Install through Github\n\nBest way to install Project Mulla is to clone it from Github\n\n**To clone/download the boilerplate**\n\n```bash\n$ git clone https://github.com/kn9ts/project-mulla.git\n```\n\n**After cloning, get into your cloned Project Mulla's directory/folder**\n\n```bash\n$ cd project-mulla\n```\n\n**Install all of the projects dependencies with:**\n\n```bash\n$ npm install\n```\n\n__Create `app.yaml` configurations file__\n\nThe last but not the least step is to create a `app.yaml` file with your configurations in the root\ndirectory of `project-mulla`.\n\nThis is the same folder directory where `index.js` can be found.\n\nYour `app.yaml` should look like the example below, only with your specific configuration values:\n\n```yaml\nenv_variables:\n  PAYBILL_NUMBER: '898998'\n  PASSKEY: 'a8eac82d7ac1461ba0348b0cb24d3f8140d3afb9be864e56a10d7e8026eaed66'\n  MERCHANT_ENDPOINT: 'http://merchant-endpoint.com/mpesa/payment/complete'\n\n# Everything below is only relevant if you are looking\n# to deploy Project Mulla to Google App Engine.\nruntime: nodejs\nvm: true\n\nskip_files:\n  - ^(.*/)?.*/node_modules/.*$\n```\n\n*__NOTE:__ The `PAYBILL_NUMBER` and `PASSKEY` are provided by Safaricom once you have registered for the MPESA G2 API.*\n\n*__NOTE:__ The details above only serve as examples*\n\n# Testing\n\n## It's now ready to launch\n\nFirst run the command `npm test` on your terminal and see if everything is all good. Then run:\n\n```bash\n$ npm start\n\n\u003e project-mulla@0.1.1 start ../project-mulla\n\u003e node index.js\n\nYour secret session key is: 5f06b1f1-1bff-470d-8198-9ca2f18919c5\nExpress server listening on 8080, in development mode\n```\n\n## Do a test run\n\nNow make a test run using **CURL**:\n\n```bash\n$ curl -i -X POST \\\n  --url http://localhost:8080/api/v1/payment/request \\\n  --data 'phoneNumber=254723000000' \\\n  --data 'totalAmount=10.00' \\\n  --data 'clientName=\"Eugene Mutai\"' \\\n  --data 'clientLocation=Kilimani' \\\n```\n\nOr if you have [httpie](https://github.com/jkbrzt/httpie) installed:\n\n```bash\n$ http POST localhost:8080/api/v1/payment/request \\\n  phoneNumber=254723000000 \\\n  totalAmount=10.00 \\\n  clientName='Eugene Mutai' \\\n  clientLocation='Kilimani'\n```\n\nOnce the request is executed, your console should print a similar structured **response** as below:\n\n```http\nHTTP/1.1 200 OK\nConnection: keep-alive\nContent-Length: 534\nContent-Type: application/json; charset=utf-8\nDate: Sun, 22 May 2016 13:12:09 GMT\nETag: W/\"216-NgmF2VWb0PIkUOKfya6WlA\"\nX-Powered-By: Express\nset-cookie: connect.sid=s:iWfXH7rbAvXz7cYgmurhGTHDn0LNBmNt; Path=/; HttpOnly\n\n{\n  \"response\": {\n    \"return_code\": \"00\",\n    \"status_code\": 200,\n    \"message\": \"Transaction carried successfully\",\n    \"trx_id\": \"453c70c4b2434bd94bcbafb17518dc8e\",\n    \"description\": \"success\",\n    \"cust_msg\": \"to complete this transaction, enter your bonga pin on your handset. if you don't have one dial *126*5# for instructions\",\n    \"reference_id\": \"3e3beff0-fc05-417a-bbf2-190ee19a5e58\",\n    \"merchant_transaction_id\": \"95d64500-2514-11e6-bcb8-a7f8e1c786c4\",\n    \"amount_in_double_float\": \"10.00\",\n    \"client_phone_number\": \"254723001575\",\n    \"extra_payload\": {},\n    \"time_stamp\": \"20160528234142\"\n  }\n}\n```\n\n\n# This project uses GPLv3 LICENSE\n\n__TL;DR__ Here's what the license entails:\n\n```markdown\n1. Anyone can copy, modify and distribute this software.\n2. You have to include the license and copyright notice with each and every distribution.\n3. You can use this software privately.\n4. You can use this software for commercial purposes.\n5. If you dare build your business solely from this code, you risk open-sourcing the whole code base.\n6. If you modify it, you have to indicate changes made to the code.\n7. Any modifications of this code base MUST be distributed with the same license, GPLv3.\n8. This software is provided without warranty.\n9. The software author or license can not be held liable for any damages inflicted by the software.\n```\n\nMore information on the [LICENSE can be found here](http://choosealicense.com/licenses/gpl-3.0/)\n\n*__DISCLAIMER:__* _All opinions aired in this repo are ours and do not reflect any company or organisation any contributor is involved with._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkn9ts%2Fproject-mulla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkn9ts%2Fproject-mulla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkn9ts%2Fproject-mulla/lists"}