This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Page tree
Skip to end of metadata
Go to start of metadata

Note: The payment gateway features/functionality are still under development. This document is a guideline for developers who wish to contribute to the project. 

Installation and Configuration Instructions

Configuring and testing the payment gateway requires interaction between several components. Fineract must be configured (through the community app) to enable the payment gateway. The payment gateway must be configured to use a supported vendor (currently the only supported vendor is Beyonic) - this can be done using the Gateway Configuration app. This document will walk you through the necessary steps to configure and use the Payment Gateway.


  1. MySQL
    1. Ensure that the Fineract databases are installed per the Fineract installation documents
    2. Create a database for the payment gateway:  create database `payment-gateway`
  2. ActiveMQ
    1. Install and verify that ActiveMQ is running. You can access the ActiveMQ console using this URL: http://localhost:8161/admin/index.jsp

Core Components

  1. Fineract
    1. Install the version of Fineract that includes support for the Payment Gateway. Until the payment gateway functionality becomes an approved part of Fineract, you can find the latest code here:
    2. Install and run Fineract (per the installation instructions). Ensure that the database migration scripts for the payment gateway tables have been installed (the 'mifostenant-default' database should contain the following tables: payment_gateway_config, payment
  2. Community App 
    1. Install the version of the community app that includes support for the Payment Gateway. The code can be found in this repo:
    2. Run the Community App. From the Admin→Organization page, select the option for Payment Gateway. On this screen, check the checkbox to enable the gateway, enter a URL for the payment gateway (this is most likely http://localhost:8080/payment-gateway/api/v1). Select a Gateway User - this is the user that will perform the transactions in Fineract when a message comes from the payment gateway. 
    3. Ensure that the Gateway user has Super User role enabled. (Admin→Users, click on username, Edit, assign Super User role to this user and save)
  3. Payment Gateway 
    1. Detailed instructions on installing the payment gateway can be found on this gist:
    2. Clone the payment gateway repo: (*Note: this code will eventually be merged to:
    3. Currently, the payment gateway should be run from an IDE/IntelliJ. From the IDE terminal:
      1. change branch: git checkout payment-gateway-core-functionality
      2. mvn clean install
      3. Run file as Java Application -
    4. The payment gateway will run at http://localhost:8080/payment-gateway/api/v1
  4. Gateway Config and Test App (Note: This app is a testing tool for developers who are working on this project and is not a part of the broader Fineract/Mifos project)
    1. Clone the Gateway configuration app from this repository:
    2. From the GatewayClient directory, run the following commands:
      1. yarn install
      2. yarn start
    3. The Gateway Client will run at: http://localhost:3100.
    4. Click on the Configure menu item at the top of the screen. Submit information on the form to configure a vendor in the payment gateway.Data for a Beyonic vendor implementation is as follows:
      1. Vendor Name: Beyonic
      2. Callback endpoint: (not needed at this point)
      3. Currency Type: BXC
      4. Active: checked/true
      5. Queue Auth Key: any data here is fine
      6. Vendor API Key: retrieve your API key from your Beyonic account. Contact Ed Cable or Steve Conrad for the Mifos test account information
      7. Vendor Auth Key: any data here is fine
      8. Vendor Meta: {'account': <Beyonic account number>} - again, contact Ed Cable or Steve Conrad for Mifos test account information
    5. Click on the Test menu item to Test the Beyonic integration (more information in testing section below)
  5. External Vendor (Beyonic)
    1. You can sign up for a Beyonic account for testing. Use the API key and account data for your account in the vendor configuration.
    2. For API documentation, visit
    3. To create new test user accounts and view transactions that have been executed on these test accounts, visit

Testing Payment Gateway with Beyonic

To test loan disbursement and loan repayment, do the following:

  1. Create a new loan product in Fineract (if loan products have been configured, you can use any of these products)
  2. Create a new test client account in Fineract. IMPORTANT: the client must have a mobile number assigned to the account in order to work properly. 
    1. In order to use the Test app, set the External ID for the client to the Beyonic API key
  3. Create a new loan for the test client
  4. Disburse the loan to the client. IMPORTANT: in the loan disburse page, click on the + icon (Show Payment Details) to view additional options. You will see a dropdown for payment channel which will display all of the payment channels that have been configured in the Payment Gateway. Select the Beyonic payment channel.
  5. When the loan is disbursed, it will automatically send those funds to the mobile account defined in Beyonic
  6. Use the test app to verify the loan disbursement and to do a loan repayment.
    1. On the test page, select the Fineract client that received the loan
    2. You will see the loan balance for this client. 
    3. Enter a loan repayment amount to pay back all or part of the loan. When you refresh the test app, you will see the loan amount change. You can also see the Beyonic account debit for the loan repayment.


Project Roadmap and Functionality to be implemented

  1. Integration with additional vendors, including Mojaloop
  2. Handling error cases and retrying transactions
  3. Transaction logging in payment gateway

  • No labels