Mojaloop Integration

Context

Fineract provides accounts and can be thought of as a Digital Financial Service Provider (DFSP) backend software stack.  Mojaloop is an embodiment of the LevelOneProject.org principles in code, and provides the interoperability switch for transfers for all kinds of payment use cases. Integrating Fineract with Mojaloop is about bringing these two platforms together in a way that creates full end to end flows of funds, and thereby lowers the cost to providers and to end customers.

Use Cases

The initial use cases that we wish to implement are as follows. In each case the transfers will occur between different DFSPs. We will use multiple Fineract instances, and will also work to look at other DFSPs such as Musoni or even a provider like mPesa.

1. Peer-to-Peer (P2P) transfer
2. Merchant Payment
3. Bulk transfer (ie. payroll disbursement)

Installation of Mojaloop platform

Instructions for installing the Mojaloop platform can be found here: http://mojaloop.io/documentation/deployment-guide/

Configuration of DFSPs

Before we can perform any transactions all Fineract instances involved in transactions need to be properly configured to use the Payment Hub as well as Mojaloop. The architecture looks as follows:

Payment Hub

The code for the payment hub can be found here: https://github.com/openMF/payment-hub

Merchant Payment flow:

• The payer initiates the payment  using an interface of a channel (Mobile Application most probably, InternetBank, or other).
• The channel triggers the payer-side Payment Hub by the corresponding REST call - see API specification.
• The payer-side Payment Hub have to be able to instruct Fineract to lock the amount on the payer’s account.
• The payer-side Payment Hub handles the sending workflow and related calls with Mojaloop and Fineract:
• lookup of the payer and payee user via Mojaloop
• Payment Hub maps the Mojaloop identifier to tenant+account identifier
• Payment Hub does the authentication if necessary with Mojaloop and Fineract - demo version: just checks, if the request-sender user exists
• quote: gathering transaction costs and fees directly from payer-side Fineract and via Mojaloop from the payee side
• handles the transfer flow

During the flow the Payment Hub instructs Fineract to provide necessary information, persist data and status changes where it is required.

• The receiver-side Payment Hub handles the receiving workflow and related calls with Mojaloop and Fineract:
• responds to account lookup requests
• responds to costs and fees request by calling forward to Fineract
• handles the transfer flow

During the flow the Payment Hub instructs Fineract to provide necessary information, persist data and status changes where it is required.

• Based on the instructions of the Payment Hubs, the connected Fineracts acts correspondingly, provide the requested data, persist the status changes, book the amount on the accounts.

P2P payment flow:

• The payee initiates the payment with a payment request using an interface of a channel (Mobile Application most probably, InternetBank, or other).
• The channel triggers the payee-side Payment Hub by a REST call, by sending in
• the payer identifier,
• the payee identifier and
• the amount.
• The payee-side Payment Hub triggers the corresponding workflow, to request the amount via Mojaloop.
• The payer-side Payment Hub gets a call from Mojaloop about the payment request.
• The payer-side Payment Hub sends a message with a notification to the registered channel, about the payment request. To prevent dependency of the implementation of the banking channels, every notification will fall back to be successful.
• The payer-side channel sends confirmation to the Payment Hub.
• The payer-side Payment Hub have to be able to instruct Fineract to lock the amount on the payer’s account.
• The payer-side Payment Hub handles the sending workflow and related calls with Mojaloop and Fineract:
• lookup of the payer and payee user via Mojaloop
• Payment Hub maps the Mojaloop identifier to tenant+account identifier
• Payment Hub does the authentication if necessary with Mojaloop and Fineract - demo version: just checks, if the request-sender user exists
• quote: gathering transaction costs and fees directly from payer-side Fineract and via Mojaloop from the payee side
• handles the transfer flow

During the flow the Payment Hub instructs Fineract to provide necessary information, persist data and status changes where it is required.

• The receiver-side Payment Hub handles the receiving workflow and related calls with Mojaloop and Fineract:
• responds to account lookup requests
• responds to costs and fees request by calling forward to Fineract
• handles the transfer flow

During the flow the Payment Hub instructs Fineract to provide necessary information, persist data and status changes where it is required.

• Based on the instructions of the Payment Hubs, the connected Fineracts acts correspondingly, provide the requested data, persist the status changes, book the amount on the accounts.

End of day activities/reconciliation

Here, we will outline the process to Reconcile ledgers

Call central ledger API to settle transfers and fees (http://mifosmojaloop.com:3004/webhooks/settle-transfers)

Further Context : Why Mojaloop and Fineract together? 

We can imagine a scenario in a country or region where Fineract provides the account management and effectively runs the Digital Financial Service Provider (DFSP) operations while Mojaloop provides the connective tissue between different financial institutions.  

From the perspective of microfinance and other financial inclusion institutions, this solves one of the issues with the high cost of repayments via digital channels.  Imagine if all microfinance payments could be made for free. Imagine a scenario where one microfinance institution has some merchants that can be paid for their services electronically and another offers transaction accounts and consumer credit. The combination of fineract and mojaloop imagines a world where there are many instances of community driven banks, microfinance institutions, credit unions, digital banks, mobile money credit offerings, which can be natively connected for payments.  As with any good ecosystem, the end points of service delivery and the connective tissue have to be brought together in an optimized manner.

The integration we imagine for demonstration purposes, in a lab like setting, would include multiple instances to allow for on-us and off-us transactions for a variety of use cases:  bulk payments (G2P or B2C), P2P, C2B, and remote C2B.

What is Mojaloop to the Mifos/Fineract projects?

The Moja loop project grew out of the need for global interoperability in the financial transactions market, to include by existing regulated financial institutions, new mobile money operators, and other regulated digital transaction account providers. This is about So connecting different customers, entrepreneurs, merchants and Digital Financial Services Platform (DFSP) together - via interoperability - which thus the project imagines enables the more than 2 billion poor and unbanked people to access financial services with little or no fees. Mojaloop is an interoperable payments network (or “switch” in bank parlance) based on a microservice architecture and is made up of over 20 component microservices which each have individual microservice having a github repository. While the docs repository documents the overall architecture, component design, message flow and an overview of Moja loop, each individual repository amongst the mojaloop github repositories describes component-specific details including source code and APIs.

In order to achieve this ambitious goal of interoperability, the Mojaloop project has put in place  the following;

1. A set of central services (central ledger, identity lookup, fraud detection & enforcement of scheme rules) which is a hub through which money flows from one DFSP to another.

2. A set of interfaces ( alongside example code ) which a DFSP can use to learn how moja loop works and to connect to the system.

3. A complete exemplary implementation of the payments side and an existing client which a DFSP can host to connect to Mojaloop.

1. Central Services : The central services is a hub through which money flows from one DFSP to another, more like a national central bank or clearing house. It contains a central ledger to record transactions, a central identity lookup for account holder directory and a central service which enforces scheme rules. These central services are  found on https://github.com/mojaloop?utf8=%E2%9C%93&q=central&type=&language= 

1. 1. central-ledger : The central ledger service facilitates clearing and settlement of transfers between DFSPs including brokering real-time messaging for clearing funds, maintaining positions for a deferred settlement and propagating scheme-level and off-transfer fees. hosted by a scheme to record and settle transfers
   2. central-hub : Operational Hub for central services which accesses a series of endpoints on the central ledger to retrieve specific data and display it on the end user. 
   3. central-fraud-sharing : A series of services designed to offer the participants an avenue to share end user and transactional information to help promote overall health of the scheme via fraud prevention.
   4. central-kms : The Central Key Management System facilitates forensic logging functionality for central services.
   5. central-directory : The central directory enables DFSPs to register and retrieve scheme identifiers which can be used by DFSPs to discover end users.
   6. Central-services-error-handling : This service enables error-handling and it’s repository is right here.
   7. central-end-user registry : The central end user registry is an example service that shows the power of the central directory. It can be used to register a DFSP's payment URL and receive a user’s number in return which can then be looked up through the central directory to make a payment.
   8. central-services-authentication: Share authentication and authorization tokens  for central services. It’s repository is here.
   9. central-services-database : Shared databases code for central services with repository here .
   10. central-services-shared : Shared code for central services with repository here.
        
2. Interface : This is a set of interfaces which feigns a DFSP and can be used to feign  connection to the interoperable network. This is aimed at making it very straightforward for a DFSP to connect to the interoperable Mojaloop platform. These interfaces can be found on https://github.com/mojaloop?utf8=%E2%9C%93&q=dfsp-&type=&language= .

Typically mimicking a mobile money provider, customers connect to it using USSD ( Unstructured Supplementary Service Data ) which is a Global System Of Mobile ( GSM ) communication technology used to send text between a mobile phone and other component in the network.

1. 1. Feature Phone  : The frontend of a DFSP's app on the customer's phone. The DFSP's Customer uses a Mobile phone ( probably running a Mobile app ) to access these services.

1. 1. USSD-over-GSM : This is used to interface the DFSP and Client's Phone because Mobile Money Payments are championed by Telecom Companies. Other Financial Providers may use newer technologies like event processing implemented using ActiveMQ in-network transfers implemented in REST calls.

1. dfsp-account : This service contains information about relations between users and their accounts. It handles users, roles ( customer, merchant and agent ) and permissions ( peer-to-peer, cash-in, cash-out, invoice, mini-statement-menu and check-balance ). It’s repository can be found here.

2. dfsp-ledger : This service is used to keep track of all transactions carried out in the DFSP, user’s financial accounts, etc. The business logic and orms for account, account type, commission, currency, fee, quote, transfer, transfer state and transfer type.

3. dfsp-identity : The identity service is used to manage identity-related data like sessions, images, PINS, etc and contains constants depicting available actions and corresponding roles which can perform them.

4. dfsp-transfer: The transfer service contains information about transfers, invoices (types, payments,statuses) and invoice notifications ( when sent from merchant’s DFSP to client’s DFSP).

5. dfsp-admin : Used as the main interface for users with an admin role, the administration microservice has a panel that provides functionality to set transaction rules, process bulk payments, check queues with action notifications.

6. dfsp-ussd : Designed as a featured phone upon which users can click buttons and see alphanumerics on screen, the USSD service is used to simulate a USSD interface over HTTP by sending requests to USSD server and displaying the responses from it.

7. dfsp-subscription : The subscription service is used to map between users and their phone numbers. DFSP Subscription Service

8. dfsp-api : The API service is the main contact point between the dfsp services and it exposes two main APIs viz the Invoice API and Pending Transactions API which handle business logic for creating and paying pending transactions.

9. dfsp-rule : The rule service  is right here.

10. dfsp-mock : The mock service is right here

1. Example : Exemplary implementation of the payments side and an existing client which a DFSP can host to connect to Mojaloop.

1. Mojaloop Client : Mojaloop can be installed at the DFSP's infrastructure using the instructions in the interop-devops - using Vagrant, VirtualBox, SSH Client and AWS Config files for an Amazon EC2 Environment. Some microservices running on the Mojaloop client include;

1. interop-devops : A service for devops to deploy Moja loop in a local setting.

2. interop-elk : This repository contains Configurations, Scripts for FileBeat, LogStash and Elastic Search (ELK)

3. interop-parent : This repository contains a POM file that contains the dependencies required for all the interop projects.

4. interop-common : This repository is packaged as a library for all interop projects such as interop-domain, interop-dfsp-directory, interop-ilp-ledger and interop-scheme-adapter. This contains common classes and common properties files that are used by interop projects.

5. interop-domain : This repository contains shared properties, http configurations and metrics for all the interop services.

6. interop-dsfp-directory : This project provides an API gateway to the Inter-System Trunk (IST) Directory Naming Service and provides resources to get/register information.

7. interop-ilp-ledger : This repository provides an interop API implementation of the ILP Ledger Service.

8. interop-schemer-adapter : This project provides an API gateway to the ilp-service microservice.

9. interop-switch : This repository is an implementation of the Moja loop API which provides the main features for lookup and quote.

10. interop-mock-central-directory : This project acts as a mock for central-directory - for situations where Pathfinder is not configured or is unavailable.

11. ilp-service : This repository is an Interledger Protocol (ILP) sending and receiving client with a RESTful API, designed for the Mojaloop.io project

... 

forensic-logging-client : Client to connect to the forensic-logging-sidecar

forensic-logging-sidecar : Sidecar to permit services to perform forensic logging

pathfinder-provisioning-client : Library for provisioning Pathfinder records