You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

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

The Mojaloop platform can be installed using the interop-devops repo: https://github.com/mojaloop/interop-devops

To create your own installation, use the instructions here: https://github.com/mojaloop/interop-devops/blob/master/README_VAGRANT.md

I created a Mojaloop installation on Ubuntu 16.04 that is publicly available. The important endpoints for this installation are:

mifosmojaloop.com:3000 - Central Directory service

mifosmojaloop.com:3001 - End User Registry

mifosmojaloop.com:3002 - Central Ledger

mifosmojaloop.com:3004 - Central Ledger Admin

Note, the interop-devops installation includes 2 sample DFSP instances. We are not using these instances at all, as Fineract is the DFSP for these cases.

Documentation for API calls for the central directory and central ledger can be found here:

https://github.com/mojaloop/central-directory/blob/9b3a0cb3c79512a9b8eb1c7712ea9d2b4e8c145f/API.md

        https://github.com/mojaloop/central-ledger/blob/master/API.md


Configuration of DFSPs

Before we can perform any transactions all Fineract instances involved in transactions need to be properly configured to use the Mifos Payment Gateway as well as Mojaloop.

Fineract and Payment Gateway

  1. The current version of Fineract with the Payment Gateway code (which is still in development) can be found at: https://github.com/conradsp/fineract/tree/payment-gateway-integration

  2. Create payment channels in Fineract for Mojaloop. I have updated the community app to allow users to create new payment channels (Organization->Payment Channels). The updated community-app can be found here: https://github.com/conradsp/community-app

    1. Create a mojaloop payment channel, point to the ActiveMQ instance on the Fineract machine, and set the queue names to mojaloop.request and mojaloop.response

  3. Ensure that the system user has super user role assigned to it


Mojaloop configuration

  1. Each DFSP has to be registered with Mojaloop – both the central-directory and the central-ledger. For each DFSP, make the following POST requests:

    1. http://mifosmojaloop:3000/commands/register

      1. Headers – the authorization uses admin/admin

        1. Authorization: “Basic YWRtaW46YWRtaW4=”

        2. Content-Type: “application/json”

      2. Body – I used Mifos1 and Mifos2 as dfspNames. The providerUrl is https://localhost:8443/fineract-provider/api/v1 or whatever is appropriate for your Fineract instance

        1. name: <dfspName>

        2. shortName: <dfspName>

        3. providerUrl: <API endpoint for Fineract instance>

      3. NOTE: this call will return an object which contains the key and secret which will be used for future requests. Save these values.

    2. http://mifosmojaloop:3004/accounts

      1. Headers: same as above

      2. Body:

        1. name: <dfspName>

        2. password: <dfspPassword>

  2. Set up charges and fees for transfers. Make the following POST request for each charge

    1. http://mifosmojaloop.com:3004/charges

      1. Headers: same as above

      2. Body

        1. name: <name of the charge>

        2. charge_type: “fee”

        3. rate_type: “percent” or “flat”

        4. rate: amount of charge

        5. minimum: minimum transfer amount to apply this charge

        6. maximum: maximum transfer amount to apply the charge

        7. code: <3 character code to identify the charge>

        8. is_active: true or false

        9. payer: sender, receiver or ledger

        10. payee: sender, receiver or ledger


Configure Interledger

On each Fineract instance, we must install the ilp-connector and ilp-service in order to communicate with the Central Ledger using the Interledger protocol.

  1. Install ilp-connector from https://github.com/interledgerjs/ilp-connector
    1. To correctly configure the ILP connector, several environment variables must be set, including: CONNECTOR_LEDGERS, CONNECTOR_ROUTES, CONNECTOR_PEERS, CONNECTOR_BACKEND, as well as other settings. See the documentation for this repo for more information.
  2. Install ilp-service from https://github.com/mojaloop/ilp-service
    1. This service requires several configuration environment variables as well, including:  ILP_SERVICE_LEDGER_ADMIN_ACCOUNT,  ILP_SERVICE_LEDGER_ADMIN_USERNAME, ILP_SERVICE_CENTRAL_CONNECTOR_PASSWORD,  ILP_SERVICE_LEDGER_ROOT,  ILP_SERVICE_CENTRAL_CONNECTOR_ACCOUNT,  ILP_SERVICE_CENTRAL_CONNECTOR_USERNAME,  ILP_SERVICE_CONNECTOR_ACCOUNT,  ILP_SERVICE_BACKEND, ILP_SERVICE_CENTRAL_CONNECTOR_PREFIX as well as others. Again, see repo documentation for details.


P2P payment flow:

The first transaction flow that has been implemented is a simple P2P (peer-to-peer) payment. The payment flow is based on the Mojaloop API documentation, page 173.

Before a user can participate in a transaction, the user must be registered in Mojaloop. For each user, make the following post request:

  1. http://mifosmojaloop.com:3000/resources

    1. Headers – use the key and secret that were returned when registering the Dfsp above

      1. Authorization: “Basic “+new Buffer(key+”:”+secret).toString(“base64”)

      2. Directory-Api-Key: dfspName

      3. Content-Type: “application/json”

    2. Body (NOTE: I was not able to get E.164 telephone lookup working correctly, so am using eur (end-user-registry) lookup)

      1. identifier: “eur:<unique id>” or “tel:<phone number>”

      2. primary: true

       

Once users are registered, the full flow for a P2P payment is:

  1. Look up the sender and recipient DFSPs in Mojaloop (based on tel or eur). This will provide the URLs where we can access each Fineract instance (through ActiveMQ)

    1. GET - http://mifosmojaloop.com:3000/resources?identifier=eur:<number>

      1. Returns object that contains the dfspName and providerUrl. The providerUrl is used to call Fineract

  2. Call the ilp-service /quoteSourceAmount API to determine fees for the transaction

    1. This call will provide the ledger URL for the recipient
    2. Endpoints needed in Fineract: ledger URL for recipient

  3. Prompt the sender with the fees for the request and wait for confirmation.

  4. Create ActiveMQ client to transfer messages between the gateway and Fineract. The hostname comes from step 1 above and the queue names will be ‘mojaloop.request’ and ‘mojaloop.response’

  5. Get the account numbers for the sender and recipient in Fineract – we use the provider URLs that we obtained in step 1 above and make a call to retrieve information about the sender and recipient from the DFSP (Fineract).

    1. Make a GET request to: providerUrl+”/receivers/”+<tel or eur identifier>

    2. Return the user data, including the account number (TODO: write out the complete response payload)

  6. Send ActiveMQ request to sender’s Fineract instance to verify that they have sufficient funds in the account for the transaction (transaction prepare)

  7. Create the transaction in the Mojaloop central ledger using the ilp service and connector. Generate a UUID to identify this transaction. 

    1. Call the ilp-service /payIPR method to execute the actual payment transaction.

      1. In this call, we will pass in the ledger URLs for both the payer and receipient

      2. Endpoints needed in URL: ledger URL for payment and credit for sender and receiver

  8. Notify the user of successful transaction


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)


Findings

        What worked out of the box

        What needed to be addressed

        Current gaps

  • No labels