Skip to content
Home » Posts » Enhancements available for Bulk Payments in Mojaloop

Enhancements available for Bulk Payments in Mojaloop

Why is the bulk payment use-case important at the moment?

An increase in government declared disasters fueled by climate change and covid 19 has put increasing pressure on the digital system in each country to succeed. This has led to initiatives like the ‘Digital Public Goods Alliance’ and ‘Co-Develop’ where open source project platforms are presented together and encouraged to interface and collaborate to produce standardised functional systems that each country can adopt. This aim is to enable governments to build and sustain digital public infrastructure that in-turn accelerates progress on the United Nations Sustainable Development Goals. The bulk payments use-case in particular plays an important part in supporting bulk disbursements of Government and NGO beneficiary funds.

In addition to this, the bulk payment use case is an important driver for adoption and for driving transaction volumes in an existing network. Bulk payments help solve common problems such as the payment of salaries, social payments and loan disbursements. In other words, this additional use case can help existing deployments become more successful.

What do the enhancements provide?

The bulk enhancements included in Mojaloop v14.1 are designed to enable more flexible usage and integration. These bulk enhancements:

  • Overcome the Bulk limitations of the Mojaloop FSPIOP API.
  • Include Discovery phase bulk API calls. This is where payee’s have their accounts or wallets identified and confirmed in bulk before committing to a transfer.
  • Multiple payee financial institutions can be included in a single API call.
  • Improved flexibility in how the API can be called. I.e. asynchronous calls are now also supported.

How to make use of this work?

The bulk enhancement has been added to a component in Mojaloop called the SDK Scheme Adapter. (This component is not a library, but an Interoperable solution composed of multiple microservices.) The SDK Scheme Adapter component is a reference connector utilising best practices for a financial institution to integrate to a Mojaloop hub. There are three typical ways in which the SDK Scheme Adapter component and the Bulk enhancements can be used.

1: Through using a third party connection tool like Payment Manager OSS

Payment Manager is an open source connection tool deployed by financial institutions to help manage their connection between their core banking system and the Mojaloop hub. Payment Manager uses the SDK Scheme Adapter to connect to Mojaloop, it automates the onboarding and maintenance of the Mojaloop security requirements, it provides a means to trace a transaction, and it collects and displays connection performance metrics. Payment Manager will directly benefit from the SDK Scheme Adapter enhancements.

2: Deploy the SDK-Scheme-Adapter as part of a custom connector.

Some financial Institutions have chosen to build and support their own custom connection into Mojaloop using the SDK Scheme Adapter. These organisations can directly benefit from the enhancements on offer by upgrading their SDK-Scheme-Adapter.

3: Parts of the design used as a reference.

The solution design is well documented and freely available through the Apache 2.0 Open Source Licensing. This means that any part of the design or code can easily be adopted into a custom implementation.
I.e. the adoption of:

  1. Interfaces – e.g. APIs & messages
  2. Event driven patterns
  3. Reuse of the test cases
  4. Use-cases – I.e. reuse the business cases
  5. Code

Functionally what is being done?

The bulk enhancements that have been released support the Payer financial service provider (Payer DFSP) that is making the bulk payment. Here is a functional diagram.

The Payer DFSP has three interaction or integration opportunities when connecting with their beneficiary management subsystem. These interactions are configured to align with the three phases of a Mojaloop transaction (Discovery, Agreement, Transfer). The bulk disbursements api call triggers the Discovery phase where all potential recipients have their DFSP and accounts resolved and confirmed. The confirmation of the party detail triggers the Agreement phase where each Payee DFSP is given the opportunity to perform AML checks and calculate the costs or discounts for each transaction. The final confirmation to proceed triggers the Transfer phase where the transfers are made.

What is the architecture used, and what does that provide?

Here is a diagram of the architecture used.

The architecture uses an Event Driven Design based on Domain Driven principles. The design is interoperable with existing functionality enabling upgrades with minimal impact. The design supports asynchronous processing, recovery from failures, is scalable, and can run on multiple infrastructures. For example, it can run as a lightweight fast memory based infrastructure, or as a production grade fully redundant system with no downtime. The solution utilises  Kafka and Redis as its underlying technologies for persistence, caching and message streaming infrastructure and is deployable on  Kubernetes  via Helm charts.

More on the testing strategy

At INFITX we align to a shift left testing principle; which means identifying bugs as soon as possible in the development process. To achieve this the testing strategy was chosen to have multiple types of tests while reusing the same test sets between the local, Continuous Integration tests and Helm tests on Kubernetes deployments. Unit tests run on our base code testing each functional module. Narrow-integration tests test the command handlers ensuring that functional requirements are met by asserting against their respective changes in the persistent stores and message queues. Lastly, our functional or end-to-end tests test all the components running together. The functional tests support local execution, execution as part of a Continuous Integration pipeline, and can be executed to confirm Kubernetes deployments as a helm test. This alignment of local and deployment test harnesses empowers the team to efficiently maintain a quality product.


The project design and implementation has been meticulously documented. If you are interested in this work, would like to make use of this work, or would like to contribute to the ongoing bulk workstream, please use this reference and contact me accordingly.

SDK-Scheme-Adapter Overview
An overview of this component and how it can be used.

Integration Flow Patterns
Highlighting patterns commonly used when integrating with the backend financial system.

Bulk Integration Flow Patterns
Highlighting patterns commonly used when integrating the bulk use case with the backend financial system.

Bulk SDK-Scheme-Adapter Design Support
This has an overview of the design used to build the bulk enhancements.

API Design
Detailed sequence diagram & error codes tables

DDD and Event Driven Design
Detailed event driven sequence diagrams

Detailed testing strategy, test case details, functional maps with test matrices highlighting coverage of the tests.

Join the conversation

Your email address will not be published. Required fields are marked *