Skip to content

Developing a Core Connector for Mifos X

Overview

Open Source projects like Apache Fineract can be used by financial service providers as a core banking system. Mojaloop is used for implementing real-time payment networks for switching payments between different Financial Service providers.

The Author Elijah Okello is a passionate and skilled Software Engineer with 4+ years of experience. He holds a Bachelor’s degree in Software Engineering. Elijah values simplicity and efficiency in his coding approach, striving for clean and maintainable solutions. He has a keen and growing interest in new and emerging financial technologies. He is also a regular contributor to open-source projects including among others Mojaloop and Mifos X.

There will arise situations when a Fineract-powered core banking system needs to connect to a Mojaloop switch. This article provides an account of the experience encountered while developing a Mifos Core Connector for Mojaloop Payment Manager.

A little background about this project is that it was built as part of a project to demonstrate government-to-person payments (G2P).

Introduction

During the development of this core connector, we had to develop a sequence diagram to illustrate the API interaction between Apache Fineract and Mojaloop.

We then went on to implement the core connector based on the design for the G2P use case. The core connector was implemented to support the receipt of payments in a DFSP backend that runs Fineract as the core banking system.

Design 

The Core Connector is intended to support the receipt of payments from a Mojaloop Switch through the Mojaloop Connector (also called the SDK Scheme Adapter). 

Here is a sequence diagram showing the API interaction and design flow.

The idea was to make sure we support the Mojaloop-specific API requirement calls to support a payment transfer, i.e. account lookup, quotes and transfers.

The core connector receives requests from Mojaloop and maps them to the equivalent request(s) in Fineract to achieve a Mojaloop three-phase end-to-end transfer as a Payee organization.

In Fineract, we decided to integrate the Savings Account resource as the store of value for where funds will be credited once a payment is received from a payer. This supports the G2P or Government to Person use case that the core connector must operate in.

Another issue that needed attention was the representation of Fineract account numbers addressed in Mojaloop. This is called a party identifier in Mojaloop and must map to a specific Id Type.Mojaloop prescribes a fixed set of ID Types that all DFSPs that communicate with it must conform to be able to transact on the switch. Refer here to see a list of Mojaloop-accepted ID Types. For this particular implementation, we decided to use IBAN – International Bank Account Number as the format to represent Fineract account numbers in Mojaloop because it was the closest to a real-world scenario. This is the area where customisation may be required to align with the scheme’s supported party identifiers that the connector is deployed against.

To come up with this design, we had to run Fineract locally to test out some of the API resources exposed.

To delve into the details of how to set up Fineract and get started with testing it out, please refer to this documentation to get an overview of what it takes to get started with Fineract.

During development, we also used a publicly hosted instance of Fineract to test out our use cases. The URL is https://demo.mifos.io/fineract-provider/api/v1

Here is an example of a request that you could make for one of the actions in the sequence diagram. e.g 

GET /fineract-provider/api/v1/savingsaccounts/{accountId}/ 

Here is the HTTP 1.1 structure for the above request.

GET /fineract-provider/api/v1/savingsaccounts/1/ HTTP/1.1

Host: demo.mifos.io

fineract-platform-tenantId: default

Authorization: Basic bWlmb3M6cGFzc3dvcmQ=

The Authorization header is composed of the username and password for the Fineract instance. At the time of writing this article, the username is ‘mifos’ and the password is ‘password’.

When you make requests to fineract, you need to specify the tenant using the fineract-platform-tenantId request header. For this request, it is the default

For more requests, please refer to this Postman Collection to test out the APIs.

Implementation

The implementation of this core connector was done in Typescript to conform to the agreed design in the sequence diagram shared in the Design section of this article.

For convenience, please use this link to access the sequence diagram. 

The completed implementation of the Mifos Core Connector can be found here. It resides in the Mojaloop Foundation github organization as a repository. 

Demonstration

I prepared a video demonstrating the integration of Mojaloop via the Mojaloop Connector (SDK Scheme Adapter) and Apache Fineract. It demonstrates the crediting of funds in an account of a beneficiary who is in a DFSP that uses Apache Fineract as its core banking system.

This is part of the MOSIP/ G2P Connect POC. The relevance of this POC is to show the support Digital Public Goods can render to governments when they are in scenarios where they need to extend financial aid to their citizens. This can be achieved via open source as shown in this demo.

A little context to this video is that before executing the transfer, a payment token alias was registered by a Beneficiary Management Portal in Mojaloop and a payment token adapter such that when payment is made to the ALIAS, the actual account of the beneficiary can be found and funds will be credited to that account.

This video illustrates the crediting of funds in the account of a beneficiary whose account resides in a Mifos Powered DFSP

Tools 

The core connector was implemented in Typescript and Node. The web server built into the application uses hapi.js to serve the web API.

Testing in the source code is implemented using jest for both unit and functional tests. These tests are executed as part of the CI/CD pipeline on CircleCI.

The Mojaloop Testing Toolkit was also used to mock APIs where necessary and also for functional testing to validate functional requirements. TTK’s API mocking capabilities are invaluable because in some cases I did not have an actual API with which to test. But when I mocked the API, it was possible to proceed with development. All I had to do was to ensure that the request and responses matched the schema of the API I was trying to mock. 

The core connector is bundled up into a container image that is hosted on Docker Hub in a public repository.

Link to docker hub repo: https://hub.docker.com/r/mojaloop/mifos-core-connector

Here is a non-exhaustive list of some of the tools that I used during the project.

Lessons

During the development of the core connector, I realized that Fineract transactions that are crediting funds to an account are not charged. 

This affected the quoting phase of the Mojaloop API because there is no charge for a deposit. We found a workaround where we performed client verification but set all charges to zero and then replied to the Mojaloop API with a quote with zero charges.

Challenges

During the development of the core connector, I encountered a few challenges. 

  • IBAN validation. IBAN is used mostly in Europe. Some African countries do not use IBAN so if a string is developed with an unsupported country, the validation fails.
  • Payer support. The current implementation does not support initializing payments from Apache Fineract to a beneficiary in a financial service provider on Mojaloop.

Sources of Information 

Contact the INFITX Team