MPESA B2B API (wrapper)

A wrapper that makes it easy to integrate with the MPESA B2B API.

The below endpoints are available:

[POST] api/v1.0/payment/initiate                      ✅
[POST] api/v1.0/payment/timeout                       ✅
[POST] api/v1.0/payment/confirm                       ✅

☝🏽 See requests.http for sample requests + payloads.

TODO:

• Unit tests
• Logging
• Swagger docs
• CI/CD
• Dockerize
• Deployment (or how-to section on how to deploy or run the app in production)

Usage

Make a copy of env.sample file named .env, and make sure all the ENVIRONMENT_VARIABLES are set.

$ cp env.sample .env  # make a copy of .env.sample called .env

(1) Development

Prerequisites:

• Python
• Pipenv
• SQLite

With Docker:

Make sure you have both docker and docker-compose installed locally.

$ make build-start-container-dev

Without Docker:

# clone the repo
$ git clone [email protected]:clovisphere/mpesa-b2b-wrapper.git
# cd into project root
$ cd mpesa-b2b-wrapper
# generate a secret key
$ export SECRET_KEY=$(python -c "import secrets;print(secrets.token_urlsafe(16))")
# set database
$ export SQLALCHEMY_DATABASE_URI_DEV=sqlite:///demo-dev.db
# install dependencies
$ pipenv install
# activate virtualenv
$ pipenv shell
# run migrations
$ flask db upgrade
# run the app in debug mode
$ flask run --debug --host=0.0.0.0 --port=8000

If you need any help with migration, please refer to Flask-Migrate.

Test it out:

1. /health

with httpie:

http :8000/health

you'd get:

{
    "status": "healthy 😊"
}

To run unittest,

# install dev dependencies
$ pipenv install --dev
# run tests
$ coverage run -m pytest
# generate coverage report
$ coverage report -m

(2) Production

Prerequisites:

• Nginx
• Python
• Node.js
• MySQL or PostgreSQL

IMPORTANT:

1. You need to create a .env file in the project root, and copy all the ENVIRONMENT_VARIABLES in env.sample to it.
2. Make sure to add your PUBLIC KEY in config/cert, the name of the key is to be specified in the .env file as SSL_CERT.

With Docker:

# DATABASE_URL is of the form: mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}/{DB_NAME}
$ make build-start-container-prod DATABASE_URL=url_to_your_prod_db

Without Docker:

You may follow this guide to set up your server.

$ cd /var/www
$ git clone [email protected]:clovisphere/mpesa-b2b-wrapper.git
$ sudo chown -R $USER:www-data /var/www/mpesa-b2b-wrapper
$ sudo chmod -R 755 /var/www/mpesa-b2b-wrapper
$ pip install pipenv
$ pipenv install --system --deploy --ignore-pipfile
$ npm install pm2 -g

Set the below ENVIRONMENT_VARIABLES (they should be set in .env).

$ export FLASK_ENV=production
$ export SECRET_KEY=$(python -c "import secrets;print(secrets.token_urlsafe(16))") 
$ export SQLALCHEMY_DATABASE_URI=mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}/{DB_NAME}

Create database tables with the below command:

$ flask db upgrade

Let's use PM2 to manage the application.

# create and start app
$ pm2 --name mpesa-b2b-wrapper start 'gunicorn --bind=0.0.0.0:5000 wsgi:app --workers=4 --timeout=120 --log-level=info'
# List the status of all application managed by PM2
$ pm2 ls
# To display logs in realtime
$ pm2 logs
# To restart or reload the app
$ pm2 [reload|restart] mpesa-b2b-wrapper
# To stop or delete the app
$ pm2 [stop|delete] mpesa-b2b-wrapper

Troubleshooting

• If for some reason, you choose to use PostgreSQL instead of MySQL, you need to install the below dependencies (assuming you are using a Debian-based distro):

$ sudo apt-get install libpq-dev
$ sudo apt-get install python3-psycopg2
$ export SQLALCHEMY_DATABASE_URI=postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}/{DB_NAME}

• To use a different Python version in your Pipfile, follow this guide.

Author

Clovis Mugaruka

• github.com/clovisphere
• twitter/clovisphere

License

Copyright ©️ 2023, Clovis Mugaruka.
Released under the MIT License.