Mpesa Rest API (MRA)
mpesa rest api converts the mpesa api to a RESTful API that is easy for developers to use instead of the current SOAP web service provided by mpesa.
Installation
Requirements
-Python 2.7 or 3.x
Configuration
In the settings file mpesa/settings.py
scroll to the bottom and replace the following urls VALIDATION_URL = "http://127.0.0.1:8000/c2b/" and CONFIRMATION_URL = "http://127.0.0.1:8000/c2b/"
with the validation and confirmation endpoint to your application respectively
example:
replace
VALIDATION_URL = "http://127.0.0.1:8000/c2b/"
CONFIRMATION_URL = "http://127.0.0.1:8000/c2b/"
with
VALIDATION_URL = "http://myapplication/validate_mpesa_payment/"
CONFIRMATION_URL = "http://myapplication/confirm_mpesa_payment/"
Development
git clone https://github.com/urandu/mpesa-rest-api.git
cd mpesa-rest-api
pip install -r requirements.txt
python manage.py runserver
Production (not ready for production)
git clone https://github.com/urandu/mpesa-rest-api.git
cd mpesa-rest-api
pip install -r requirements.txt
./start.sh
Docker
To run the application via using docker (docker should be installed on your machine) :
git clone https://github.com/urandu/mpesa-rest-api.git
cd mpesa-rest-api
docker-compose up
C2B Validation And Confirmation
For validation and confirmation you need to have validation end point that will receive validation requests in json form. You also need to have a confirmation endpoint in your application that will receive confirmation requests from MRA(mpesa rest api).
When requesting for validation and confirmation G2 API access from safaricom, they will ask you for two endpoints, the validation and the confirmation endpoints.
Below are the endpoints you should give them once you you deploy MRA
Confirmation endpoint = http://your_application_ip_address/confirmation/
Validation endpoint = http://your_application_ip_address/validation/
validation workflow and payloads
-when a users makes a paybill payment via mpesa from his/her phone, mpesa will send a validation request to MRA.
-MRA will parse the SOAP request and convert it to json.
-MRA will then post the json to the validation endpoint provided in the settings.py file. below is a sample (format) of the json payload:
{
"trans_time": "20140227082020",
"kycinfo": "[{\"KYCName\": \"[Personal Details][First Name]\", \"KYCValue\": \"Hoiyor\"}, {\"KYCName\": \"[Personal Details][Middle Name]\", \"KYCValue\": \"G\"}, {\"KYCName\": \"[Personal Details][Last Name]\", \"KYCValue\": \"Chen\"}]",
"trans_amount": "123.00",
"trans_type": "PayBill",
"msisdn": "254722703614",
"invoive_number": null,
"paybill_number": "12345",
"trans_id": "1234560000007031",
"account_number": "hjhdjhd"
}
-The response that MRA expects from the validation endpoint is :
The result_code returned by the validation endpoint should be 0 for success otherwise, use one of the codes below to describe the error:
result_code result_description
C2B00011 Invalid MSISDN
C2B00012 Invalid Account number
C2B00013 Invalid Amount
C2B00014 Invalid KYC details
C2B00015 Invalid Shortcode
C2B00016 Other Error
Example response:
{
"result_code": "0"
"result_description": "sucessful validation"
"custom_trans_id": "id from your application"
}
confirmation workflow and payloads
Once the confirmed transaction has been proccessed by mpesa, MRA will send a post request to the confirmation endpoint in the settings.py transaction
the payload in the post request shall be as below:
{
"trans_time": "20140227082020",
"kycinfo": "[{\"KYCName\": \"[Personal Details][First Name]\", \"KYCValue\": \"Hoiyor\"}, {\"KYCName\": \"[Personal Details][Middle Name]\", \"KYCValue\": \"G\"}, {\"KYCName\": \"[Personal Details][Last Name]\", \"KYCValue\": \"Chen\"}]",
"trans_amount": "123.00",
"trans_type": "PayBill",
"msisdn": "254722703614",
"paybill_number": "12345",
"trans_id": "1234560000007031",
"account_number": "hjhdjhd"
}
Online checkout (C2B)
For online checkout, you initiate a payment request from your application to MRA as outlined below
send a post request to http://your_mra_instance/request/payment
with the below params
-merchant_transaction_id: "gf5rsewalu8j" [optional]ID of the transaction generated by your application
-account_number: "xxxxxx" [optional] paybill account number
-amount: "50.00" the amount to be paid
-msisdn: "254726345xxx" the phone number that should make the payment (note the format)
response
{
"trx_id": "gstsf25sfsftsfs52",
"return_code": "00" 00=success 01=an error occured,
"description": "success"
}
If the user authenticates the action from his/her phone MRA will send a post request to the MERCHANT_ONLINE_CHECKOUT_CALLBACK
url that you specified in settings.py
the body of the request will contain the below payload
{
"msisdn": "254726983xxx",
"amount": "50",
"date": "10-10-1997",
"mpesa_transaction_id": "KMJH7700GDH",
"transaction_status": "success",
"return_code": "00",
"description": "payment successful",
"merchant_transaction_id": "dsdfsfsfsfs"
}
B2C
(coming soon)
B2B
(coming soon)