Mifos Core Connector for Mojaloop Design Findings

The term fineract and Mifos are used interchangeably in this documentation to mean the same thing.

Overview

This documentation is an account of the experience I had while developing the mifos core connector. The idea is to make sure the steps of how I got everything working and testing is documented and can easily be referenced for someone else to use.

Deploying and setting up fineract for development

To setup fineract for development, you will need to do following.

Prerequisites

The following are required for you to successfully go through this documenation.

• Working knowledge of docker
• Docker installed on your machine

Deploy mariadb

Fineract uses mysql as it's default database management system. You will need to deploy an instance of mariadb on your localhost to be able to run fineract successfully.

Run this command to run a local instance of mariadb. Note the parameter -e MARIADB_ROOT_PASSWORD=mysql which sets the password for the mariadb instance.

docker run --name mariadb-11.2 -p 3306:3306 -e MARIADB_ROOT_PASSWORD=mysql -d mariadb:11.2

After running this command, you will have a local running instance of mariadb.

Setup database

Fineact requires some database resources to be in place for it to start successfully.

Clone the fineract repository on your local machine and cd into the repo folder.

git clone https://github.com/apache/fineract.git; cd fineract

After cloning the repository, please execute the following commands at the root of fineract repo folder to create the database resources.

./gradlew createDB -PdbName=fineract_tenants

./gradlew createDB -PdbName=fineract_default

After running these commands, if they executed successfully, the database resources will be created and now we can proceed to run fineract.

Deploy fineract

After you have deployed an instance of mariadb and created the database resources, you can then deploy the latest stable release of Apache Fineract from Docker Hub.

Run this command to deploy fineract locally.

docker run --name fineract -p 8443:8443 -p 8080:8080  -e FINERACT_DEFAULT_TENANTDB_PWD=mysql -e FINERACT_DEFAULT_TENANTDB_HOSTNAME=localhost -e FINERACT_SERVER_SSL_ENABLED=false --network="host" apache/fineract

Existing public fineract instances

There are existing public instances of Apache fineract hosted and maintained by Mifos Initiative

Here is one I used for the development and validation of my api routes

• https://demo.mifos.io/

You can make requests to this base url while referring to the api docs at Docs

Fineract Core Connector Sequence Diagram

Payee account in Fineract

Make sure to view this in github to see the rendered sequence diagram. Issue on Github

sequenceDiagram
    autonumber
    SDK Scheme Adapter->>+Core Connector: GET /parties/IBAN/{ID}
    Core Connector->>+Core Connector: Validate &Extract Account No from IBAN
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/search?query={AccountNo}&resource=savingsaccount
    Apache Fineract-->>+Core Connector: Response 200 OK [{}...]
    Core Connector-->>+Core Connector: Extract Account Id
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/savingsaccounts/{accountId}/
    Apache Fineract-->>+Core Connector: Response 200 OK {...}
    Core Connector->>+Core Connector: Verify Account is active and can receive deposits
    Alt If Account Active
    Core Connector-->>+Core Connector: Extract Client Id
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/clients/{clientId}/
    Apache Fineract-->>+Core Connector: Response 200 OK {...}
    Core Connector-->>+SDK Scheme Adapter: Response 200 OK {...}
    Else If Account Not Active
    Core Connector-->>+SDK Scheme Adapter: Response 404 Not Found
    End
    SDK Scheme Adapter->>+Core Connector: POST /quoterequests
    Core Connector-->>+Core Connector: No Fees for Deposits
    Core Connector->>+Core Connector: Validate &Extract Account No from IBAN
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/search?query={AccountNo}&resource=savingsaccount
    Apache Fineract-->>+Core Connector: Response 200 OK [{}...]
    Core Connector-->>+Core Connector: Extract Account Id
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/savingsaccounts/{accountId}/
    Apache Fineract-->>+Core Connector: Response 200 OK {...}
    Core Connector->>+Core Connector: Verify Account is active and can receive deposits
    Core Connector-->>+Core Connector: Extract Client Id
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/clients/{clientId}/
    Apache Fineract-->>+Core Connector: Response 200 OK {...}
    Core Connector-->>+Core Connector: Tiered KYC Checks need to be performed here.
    Core Connector-->>+SDK Scheme Adapter: Response 200 OK {...}
    SDK Scheme Adapter->>+Core Connector: POST /transfers
    Core Connector->>+Core Connector: Extract Account No from IBAN
    Core Connector->>+Apache Fineract: GET /fineract-provider/api/v1/search?query={AccountNo}&resource=savingsaccount
    Apache Fineract-->>+Core Connector: Response 200 OK [{}...]
    Core Connector-->>+Core Connector: Extract Account Id
    Core Connector->>+Apache Fineract: POST /fineract-provider/api/v1/savingsaccounts/{accountId}/transactions?command=deposit
    Alt If No Error
    Apache Fineract-->>+Core Connector: Response 200 OK {...}
    Core Connector-->>+SDK Scheme Adapter: Response 200 OK {...}
    Else If Error
    Core Connector-->>+SDK Scheme Adapter: Response 500 Server Error
    End

Integration for Payer Flow.

To initiate payments from fineract we decided to introduce a Dfsp Operations App which triggers transfers through the core connector. The core connector exposes an api for triggering transfers and accepting quotes returned from mojaloop.

The core connector handles the following.

• Checking the validity of the account from which funds are to be taken out
• Checking if the account balance is sufficient to fulfil the quote amount as returned from the SDK Scheme Adapter
• Reserving funds before committing to a transfer
• Handling any failures that happen during the transfer

Funds reservation models

During the design of this integration, we considered some transfer models. Here is a description of a the ones we considered.

• 1 Withdraw funds before sending acceptQuote=true to SDK Scheme Adapter
• 2 Using a reserve account in fineract to reserve funds from the payers account and crediting the funds back only if the transfer fails
• 3 Using a prefunded liquidity account from which transfers are made and then settlements are done later on.

For this implementation, we decided to go with option 1 which is described in the following sequence diagram.

sequenceDiagram
    autonumber
    Dfsp Operations App->>+Core Connector: POST /transfers {..} 
    Core Connector->>+Fineract: GET /fineract-provider/api/v1/savingsaccounts/{accountId}/
    Fineract-->>+Core Connector: Response 200 OK {...}
    Core Connector->>+ Core Connector: Check Account is active
    Alt If Account is inactive
    Core Connector -->>+ Dfsp Operations App: Error 500 {...}
    End
    Core Connector->>+ SDK Scheme Adapter: POST /transfers {AUTO_ACCEPT_QUOTES=false, AUTO_ACCEPT_PARTY=true}
    Alt If Account not found
    SDK Scheme Adapter-->>+ Core Connector: 400/500/504 {...} 
    Core Connector-->>+ Dfsp Operations App: 400/500/504 {...}
    End
    SDK Scheme Adapter-->>+ Core Connector: 200 OK {...}
    Core Connector->>+ Fineract: GET /fineract-provider/api/v1/charges/
    Fineract->>+ Core Connector: 200 OK [{..},{..}]
    Core Connector->>+ Core Connector: Calculate fineract charge and total amount and check Account Balance
    Alt If Quote ok
    Core Connector-->>+ Dfsp Operations App: 200 OK {.Quote.}
    Dfsp Operations App->>+ Dfsp Operations App: Notify customer of recipient and request confirmation of the terms and fees of the transfer
    Else If Qoute not ok
    Core Connector-->>+ Dfsp Operations App: 500 Error {...}
    End
    Dfsp Operations App->>+ Core Connector: PUT /transfers/{transferID} {acceptQuote=true}
    Core Connector->>+ Fineract: POST /fineract-provider/api/v1/savingsaccounts/{accountId}/transactions?command=withdraw
    Fineract  -->>+ Core Connector: 200 OK {...}
    Core Connector->>+ SDK Scheme Adapter: PUT /transfers/{transfersId} {acceptQuote=true}
    Alt If Transfer Successful
    SDK Scheme Adapter-->>+ Core Connector: 200 OK {...}
    Core Connector-->>+ Dfsp Operations App: 200 OK {...}
    Else if Transfer not Successful
    Core Connector ->>+ Fineract: Refund payer POST /fineract-provider/api/v1/savingsaccounts/{accountId}/transactions?command=deposit
    Fineract-->>+ Core Connector: 200 OK {...}
    SDK Scheme Adapter -->>+ Core Connector: 500/504 Error {...}
    Core Connector-->>+ Dfsp Operations App: 500/504 Error {...}
    End