Mojaloop Community Central

A Practical Blueprint for Merchant Payments with Mojaloop

Paul Makin — Thu, 17 Sep 2026 16:50:10 +0000

The Mojaloop Community has published the first formal release of the Mojaloop Merchant Payments Overview, providing adopters with a practical description of how merchant payments can be implemented alongside an existing Mojaloop deployment.

The document brings together the key components, architecture and operating considerations needed to support merchant payments while keeping merchant-specific functions separate from the core Mojaloop Hub.

Read the Mojaloop Merchant Payments Overview

Bringing Merchant Payments to Mojaloop

Merchant payments are an important use case for inclusive instant payment systems, but accepting a payment at a merchant involves considerably more than simply transferring funds. Merchants need to be registered and identified, appropriate know your business (KYB) checks need to be undertaken, payment acceptance mechanisms need to be provided, and schemes need to address operational and fraud risks.

The Merchant Payments Overlay is designed to provide these capabilities without adding them to the core Mojaloop Hub. The overlay brings these elements together into an architecture that adopters can adapt to their own regulatory, commercial, and operational environments.

A Flexible Merchant Registry

At the heart of the model is a Merchant Registry. Merchants are onboarded by authorized registering/acquiring DFSPs, with appropriate KYB checks undertaken before a unique Merchant ID is issued.

That identifier can then be made available to the Mojaloop-based IIPS as a routable alias, while the merchant’s DFSP maintains the definitive mapping between the Merchant ID and the account into which payments are received.

Importantly, the model does not prescribe a single way to operate the registry. The document describes both centralized and federated approaches, allowing adopters to select a model appropriate to their scheme governance and market structure.

Supporting QR-Based Acceptance

The overlay also provides a practical route to QR-based merchant acceptance. The current open-source implementation uses static QR codes, minimizing the technology required at the merchant premises. The customer scans the QR code using their DFSP’s smartphone application and enters the transaction amount.

The architecture can also be extended to dynamic QR codes, where the amount and other transaction information are incorporated into a QR code generated for an individual purchase. Numeric Merchant IDs can additionally support customers using USSD and feature phones, extending the model to a wider range of payment scenarios.

Security at the point of acceptance is also addressed. The overview describes how cryptographic signatures and a scheme-level trust model can protect QR codes against substitution or tampering. They also allow the customer’s application to verify that a QR code was issued under the authority of a participating DFSP and the scheme.

Keeping Merchant Functions Separate

For adopters, one of the main benefits of this approach is separation of concerns.

Mojaloop continues to provide interoperable routing, liquidity management and real-time funds transfer, while the overlay handles merchant-specific functions and merchant payment scheme rules. This separation allows a merchant payments service to evolve without introducing unnecessary complexity into the underlying IIPS.

The result is an approach that gives adopters a way to add merchant payments capabilities while maintaining a clear division between the core payment infrastructure and the functions specific to merchant acceptance.

Looking Ahead with LEIs

The document also points to future possibilities. Work with the Global Legal Entity Identifier Foundation (GLEIF) is extending the model to incorporate legal entity identifiers (LEIs) into merchant onboarding and payment addressing.

This creates opportunities to automate elements of KYB, strengthen merchant identity verification and, particularly for cross-border payments, use a globally recognized legal-entity identifier alongside the scheme-specific Merchant ID.

A Starting Point for Adopters

For organizations considering merchant payments, the Mojaloop Merchant Payments Overview provides more than a description of a feature. It sets out a starting architecture and operating model that can be adapted to local requirements while retaining a clear principle: keep merchant-specific complexity at the edge, and use Mojaloop for what it does best — the interoperable movement of funds between participating DFSPs.

For Mojaloop adopters looking to support merchant payments, the overview provides a practical foundation for understanding how these capabilities can fit alongside an existing Mojaloop deployment.

Read the Mojaloop Merchant Payments Overview

Bringing TigerBeetle to Mojaloop: The Road to a New Ledger

James Bush — Thu, 17 Sep 2026 11:03:12 +0000

Mojaloop's central ledger has run on MySQL since the platform's early days, and it has served the community well. As adoption grows and national payment systems push for higher throughput, the ledger has become one of the most important places to look for performance gains. That is why work is well underway to introduce TigerBeetle, a database built specifically for financial transactions, as a new ledger implementation for Mojaloop. Over time, it will replace the current MySQL ledger.

The main reason for the change is performance. A large share of the contention in today's ledger comes from row locking in the relational database. TigerBeetle's architecture greatly reduces that locking, and we expect a significant improvement in throughput as a result.

A change this close to the core of the platform needs a careful, open process. This post explains that process, what has been done so far, and what you can expect over the coming months, including how you can get involved.

Where we are today

We are currently in the implementation phase, and a preview release is expected in the coming weeks. Here is the full journey at a glance:

Phase	Status
1. Programme design	Complete
2. Implementation	In progress
3. Preview release (non-production)	Coming weeks
4. MLF and community testing	Upcoming
5. Community feedback incorporated	Upcoming
6. Production release	Upcoming

Phase 1: Programme design

Before writing any code, we needed a design the community could trust. This phase covered four areas of work.

Account mappings and a new chart of accounts. We defined how Mojaloop's accounts and their behaviours map onto TigerBeetle. This work was also seen as an opportunity to introduced a new chart of accounts (CoA) model more closely aligned with industry practices. The mappings were reviewed by the Technical Governance Board (TGB) and the Design Authority (DA). One point is worth stressing: the new CoA applies only to the TigerBeetle ledger. It will not be applied retrospectively to the existing MySQL ledger.

An abstracted ledger interface. To let Mojaloop support more than one ledger, the interface to the existing MySQL ledger is being refactored behind an abstraction. The rest of the platform then talks to "a ledger" rather than to MySQL directly.

Settlement redesign. Settlement was redesigned to serve two goals at once. It keeps existing behaviours intact, so the change is non-breaking for current adopters. It also prepares for a future in which TigerBeetle is the ledger.

Review with the Design Authority. The complete design was shared with the DA and discussed openly. No objections were raised, which cleared the way for implementation.

Phase 2: Implementation

This is where we are now. Lewis Daly from TigerBeetle is working with Mojaloop Foundation (MLF) staff, the core team and community contributors to build the agreed design.

We have kept the work as transparent and reviewable as possible:

Self-contained pull requests are raised regularly and announced in the usual PRs Slack channel. Each one can be understood on its own.
Open review. The core team and any interested community members review the PRs and give feedback, and we iterate until the features are ready for a preview.
Performance testing is running alongside development, so we can evaluate the new ledger's performance as it takes shape.
Testing is non-negotiable. Tests are refactored where the underlying code has been refactored. All existing unit, integration and end-to-end tests must continue to pass. New and expanded test coverage is being added for TigerBeetle-specific features.

If you have been meaning to look at the code, now is a great time. Review comments at this stage are the cheapest and most valuable kind of feedback.

Phase 3: Preview release (non-production)

In the coming weeks we will publish a preview release. It is for experimentation and testing only and is not intended for production use. To make that unmistakable, it will ship as a specially and clearly named Helm release.

The preview will include a range of configuration options so you can enable and explore the new features in your own test environments.

Documentation will accompany the preview. It will cover deploying TigerBeetle for development and test environments, plus an early look at our production deployment recommendations, including infrastructure requirements and deployment architectures. We are also looking at tooling to support data migration as part of this work.

Phase 4: MLF and community testing

Once the preview is out, the testing really begins.

The performance workstream will run benchmarks against the new ledger and publish the results. These results may lead to changes in the recommended infrastructure, and those changes will be published too.

We also want to hear from as many of you as possible. System integrators, adopters and all community members are encouraged to deploy the preview, test it in your own scenarios and share your feedback. Real-world configurations and use cases are the best way to find the edge cases that matter.

Phase 5: Community feedback incorporated

Feedback from the testing phase will be reviewed and folded back into the implementation. This loop is what turns a promising preview into a release the whole community can rely on.

Phase 6: Production release

The production release will be much more than a code drop. It will include:

Final deployment documentation for development, test and production environments, including a migration plan.
Updates across all Mojaloop documentation to reflect the TigerBeetle changes.
Tooling and scripts for a failsafe upgrade path, so existing adopters can move to the new ledger with confidence.
Training material and documentation on the new chart of accounts, so operators, hubs and integrators understand how the new model works.

How you can get involved

There are several ways to take part, both now and in the months ahead:

Follow and review the PRs announced in the PRs Slack channel.
Watch for the preview release announcement and try it out in a non-production environment.
Share your feedback, whether it concerns configuration, documentation, performance or the new chart of accounts.
Keep an eye out for the published benchmark results from the performance workstream.

Replacing the ledger is one of the most significant changes Mojaloop has taken on. By doing it in the open, with clear phases and plenty of chances for review, we aim to deliver a major performance improvement without compromising the stability adopters depend on. We look forward to your feedback on the preview.

AI Disclosure: This document includes content generated with assistance from Claude Opus 5. All content has been reviewed and validated by the author.

Recommending READ COMMITTED as Mojaloop's Default MySQL Isolation Level

Megan Cannon — Thu, 03 Sep 2026 19:04:07 +0000

Recommending READ COMMITTED as Mojaloop's Default MySQL Isolation Level
August 2026 - a recommendation from the Mojaloop core team to Mojaloop adopters and the wider community.
TL;DR
While investigating deadlocks reported against a Mojaloop deployment, we traced the cause to MySQL's default transaction isolation level, REPEATABLE READ, and found that switching to READ COMMITTED fixed two problems in the same deployment:

Incoming transfers were being blocked by the close settlement window process.
A long-standing deadlock in central-ledger's timeout handler (transfer timeout sweeps colliding with live transfer inserts) disappeared. We've already updated the reference example-mojaloop-backend chart in mojaloop/helm to set this correctly (PR merged post v17.2.0). In addition, one pre-requisite for this to work is the central-settlement version v17.4.0 .

This post explains the root cause, why we think it should be your production default too, and exactly how to make the same change on your own deployment - safely, reversibly, and without waiting for a future Mojaloop release.

The problem
Mojaloop's core write path (central-ledger) and its settlement path both hit the same InnoDB tables - transferStateChange, transferTimeout, and participantPosition - under MySQL's default isolation level, REPEATABLE READ.
Two symptoms showed up together:
● Settlement blocking live traffic. The close settlement window process - which scans and aggregates over ranges of transfers to close out a window - was taking shared locks that live incoming transfers then queued behind. Under load, transfer processing latency would spike every time a settlement window was closed.
● A timeout-handler deadlock. The cron-based timeout sweep runs an INSERT … SELECT to pull expired transfers. Under REPEATABLE READ, that statement takes shared next-key locks on the index range it scans - a normal part of how InnoDB prevents phantom reads at that isolation level. Those locks collided with live, in-flight transfer commits landing in the same index range at the same moment.
Both symptoms have the same root cause: REPEATABLE READ's phantom-read protection is implemented with locking (gap locks / next-key locks on range scans), and Mojaloop's write path is
dense enough, on the same narrow set of hot tables, that those locks become contention rather than protection.

Why REPEATABLE READ is the wrong default here
REPEATABLE READ exists to give a transaction a consistent snapshot across multiple statements - so if you SELECT the same range twice in one transaction, you see the same rows both times, and to guarantee that, InnoDB locks the gaps between index records to stop other transactions inserting into them.
Mojaloop's hot-path transactions don't need that guarantee:
● Transfer processing is short-lived: read position, apply a delta, write, commit. There's no multi-statement read-then-read-again pattern in the transfer path that depends on a frozen snapshot.
● Consistency where it actually matters: participant position balances - is enforced by explicit row locking (SELECT … FOR UPDATE) and unique constraints, not by gap locks preventing phantom rows.
● The thing that was relying on wide range scans (settlement aggregation, timeout sweeps) doesn't need repeatable-read semantics either - it needs to not block the write path while it scans.
READ COMMITTED removes the gap-lock behavior on non-matching rows for these scans (InnoDB still takes locks on rows it actually examines and modifies, just not the gaps around them). That's the entire fix: less locking on ranges, same row-level consistency guarantees where they're enforced explicitly.

Is this safe? What to check before you flip the switch
READ COMMITTED is not a free lunch - it changes semantics, and you should confirm these are true for your deployment before rolling it out:
● No code relies on repeatable snapshots within a transaction. Audit anything that runs more than one SELECT against the same range inside a single DB transaction expecting the second read to match the first (some reporting/reconciliation jobs are the usual suspects - the live transfer/settlement path in central-ledger is not one of them).
● binlog_format is ROW or MIXED. Statement-based replication is unsafe under READ COMMITTED because the same statement can legitimately produce different results depending on timing. ROW/MIXED (MySQL's default since 5.7.7) sidesteps this entirely - if you've explicitly forced STATEMENT anywhere, stop and fix that first.
● Nothing pins the isolation level per-connection. We confirmed database-lib (central-ledger's DB layer) has no afterCreate hook or per-connection isolation override - it inherits whatever the server default is. If your fork or a service you run does pin isolation level in application code, that code wins over the server default and won't be affected by this change either way - check for it so you know what you're actually changing.

Results
After the change: no recurrence of the timeout-handler deadlock, and closing a settlement window no longer visibly stalls incoming transfer throughput. This isn't a partial mitigation - the locking mode that caused both symptoms is gone.

What we've already changed upstream
The example-mojaloop-backend chart in mojaloop/helm already reflects this recommendation on its MySQL primary (which is provided for reference).
This alone doesn't change your production database. example-mojaloop-backend is a demo composition, not a values file any real deployment inherits automatically - if you're running Mojaloop in production, you almost certainly maintain your own values.yaml, and it needs the same change applied deliberately. That's what the rest of this post walks through.

How to change it on your own deployment
Below are the detailed steps for the configuration changes, once you’ve confirmed using central-settlement version v17.4.0 . This change (below) is server-wide, not central-ledger-only.

Test it live, no persistence, reversible in one command
SET GLOBAL transaction_isolation = 'READ-COMMITTED';
This affects new connections only - sessions already open keep their old isolation level until they reconnect. It does not survive a MySQL restart. This is the right first step: flip it, let connection pools cycle, watch your deadlock/lock-wait metrics, and revert with the same command if anything looks wrong.
Check current state at any time:
SELECT @@GLOBAL.transaction_isolation, @@SESSION.transaction_isolation;
Make it durable without a restart (MySQL 8.0+)
SET PERSIST transaction_isolation = 'READ-COMMITTED';
SET PERSIST writes the value to mysqld-auto.cnf in the data directory and applies it immediately and globally - no pod restart, no downtime. It survives a MySQL process restart too, as long as the data directory itself persists.
That last clause matters more than it looks. If your MySQL data directory doesn't persist across pod restarts - an ephemeral volume, common in dev/test deployments - mysqld-auto.cnf disappears the moment the pod is recreated, and you silently fall back to REPEATABLE READ. SET PERSIST alone is not enough on ephemeral storage - you need step 3 as well.
Bake it into your persistent server configuration (durable across restarts)
SET PERSIST only helps if the data directory it writes to survives. Either way, the isolation level should end up in whatever configuration your MySQL server loads on startup, so a redeploy, a restore, or a fresh replica doesn't quietly revert to REPEATABLE READ.
If you're running the Bitnami MySQL Helm chart (used by the Mojaloop reference deployment):
mysql:
primary:
extraFlags: "--transaction-isolation=READ-COMMITTED"
(An alternative, primary.configuration, fully overrides the default my.cnf - only worth it if you're already overriding the full config for other reasons, since you'd need to carry forward every default setting alongside the isolation line.) Apply with helm upgrade --install -f values.yaml.
If you're running MySQL another way - a self-managed server, a different Helm chart, or a managed service like RDS/Aurora/Cloud SQL - the mechanism differs but the target is the same: set transaction-isolation=READ-COMMITTED under [mysqld] in my.cnf, or the equivalent parameter in your provider's DB parameter group, and apply it through whatever config-management path you already use for that server.
Either way, this restarts the MySQL primary. On a single-primary/standalone topology that's a brief write-unavailability window, so schedule it like any other maintenance-window change: apply SET PERSIST first for immediate effect, then land the durable config change, so you get zero-downtime and durability without the two steps needing to be simultaneous.
Verify and monitor
SHOW VARIABLES LIKE 'transaction_isolation';
SELECT * FROM performance_schema.data_locks; -- confirm gap-lock behavior is gone on hot ranges
SELECT * FROM information_schema.INNODB_TRX; -- watch for long-running transactions post-change
Watch deadlock counters (SHOW ENGINE INNODB STATUS, or whatever you already scrape into Prometheus) before and after - you're looking for the timeout-handler-vs-live-insert deadlock signature to stop appearing entirely, not just get rarer.

Rollback
SET GLOBAL / SET PERSIST back to REPEATABLE-READ (or RESET PERSIST transaction_isolation to drop the override and fall back to compiled default), and revert whatever persistent configuration you changed in step 3. Nothing about this change is one-way.

A note to the community
This is a recommendation, not a mandate - you don't need our sign-off to try it, and every deployment is free to make this change on its own timeline. That said, if you're running Mojaloop in production and know of a reason REPEATABLE READ semantics are load-bearing somewhere we haven't audited - a reporting job, a reconciliation flow, a fork with different transaction boundaries - we'd like to hear about it, so we can document the exception for others weighing the same change.

Central Bank of Sudan

Steve Haley — Thu, 07 May 2026 13:57:11 +0000

RFP out for the Central Bank of Sudan. Please comment here with your information if you are looking for collaborators and partners and what you're looking for!

https://cbos.gov.sd/en/content/tender-announcement-national-instant-payment-system-project-nips

The Mojaloop Foundation Publishes Its Policy on the Responsible Use of AI Tools in the Community

James Bush — Mon, 13 Apr 2026 13:33:14 +0000

The Mojaloop Foundation is pleased to announce the publication of its policy on the responsible use of AI tools within the Mojaloop community. As AI technologies become increasingly embedded in how we design, build, and operate software, it is important that their use aligns with the Foundation’s principles of openness, transparency, and trust.

The policy provides clear guidance on how community members may use AI tools in ways that support collaboration and maintain the integrity of the Mojaloop open source ecosystem. It covers areas such as the use of AI for documentation, code development, and participation in community discussions, with an emphasis on human accountability and transparency.

This policy has been reviewed and endorsed by the Community Council, reflecting a shared commitment across the community to adopt AI responsibly while continuing to encourage innovation and contribution.

Given the rapid pace of change in AI technologies and their applications, this policy will be reviewed and updated regularly to ensure it remains relevant and effective.

You can read the full policy here:
https://docs.mojaloop.io/community/standards/ai_policy.html

We welcome feedback from the community as we continue to evolve our approach in this important area.

Replica Configuration, Scheduling, and Repeatability (Part 5 of 6)

Chris Law — Mon, 23 Mar 2026 12:19:56 +0000

In Part 5 of our Mojaloop v17 series, we focus on repeatability, ensuring performance remains stable and predictable under sustained load.
We refined deployment topology using topology-aware scheduling and resource isolation, reducing run-to-run variance and stabilising behaviour across replicas.

At a national scale, inconsistent pod placement and resource contention can quickly undermine throughput gains. These changes ensure the platform delivers consistent transaction processing, even during peak periods.

Replica Configuration, Scheduling, and Repeatability (Part 5 of 6)

Delivered in support of programmes led by the COMESA Clearing House, COMESA Business Council, GamSwitch Company Ltd, Institute for Inclusive Digital Africa, and the Central Bank of The Gambia.

Kafka Design for Real Throughput: Partitioning, Ordering, and Concurrency (Part 4 of 6)

Chris Law — Thu, 19 Mar 2026 11:26:52 +0000

In Part 4 of our v17 series, we focus on the event backbone — how Kafka design underpins sustained, high-throughput processing across the switch.

We revisited message flow design to enable true parallel processing, aligning partitioning with business domains and tuning concurrency to maintain correctness without limiting scale.

At a national level, small inefficiencies in partitioning, ordering, or consumer stability can quickly become bottlenecks. These changes ensure the platform delivers stable, predictable performance under sustained load.

Kafka Design for Real Throughput: Partitioning, Ordering, and Concurrency (Part 4 of 6)

Delivered in support of programmes led by the COMESA Clearing House, COMESA Business Council, GamSwitch Company Ltd, Institute for Inclusive Digital Africa, and the Central Bank of The Gambia.

Zero-Touch Kubernetes Networking with NetBird

Chris Law — Wed, 11 Mar 2026 13:10:30 +0000

A recent engineering write-up on netbird.io highlighted how the INFITX Africa platform team built a zero-touch private networking for Kubernetes environments using NetBird.

As our infrastructure spans on-premise and AWS environments, we needed a way for clusters to automatically join a secure private network without manual configuration or VPN management.

Using NetBird, Kubernetes Operators, and Crossplane, networking is now fully declarative and automatically provisioned as new clusters are created.

A great example of how cloud-native tooling can simplify secure infrastructure at scale.

INFITX Africa - Zero-Touch Kubernetes Networking

netbird.io - INFITX Africa Engineering in Focus: Zero-Touch Kubernetes Networking

Delivered in support of programmes led by the COMESA Clearing House, COMESA Business Council, GamSwitch Company Ltd, Institute for Inclusive Digital Africa, and the Central Bank of The Gambia.

Removing Bottlenecks at the “Front Door” (Ingress and Gateway Path) (Part 3 of 6)

Chris Law — Tue, 10 Mar 2026 13:00:10 +0000

In Part 3 of our v17 series, we look at the ingress and gateway layer — the critical “front door” of the switch that determines how efficiently transaction traffic enters the platform.

We modernised the gateway path to unlock the full performance potential of the core services, introducing high-performance ingress components and optimising identifier handling for high-concurrency processing.

At a national scale, even small architectural constraints can become throughput bottlenecks. These changes ensure the platform can sustain high transaction volumes while maintaining security, efficiency, and global interoperability.

Removing Bottlenecks at the “Front Door” (Ingress and Gateway Path) (Part 3 of 6)

Delivered in support of programmes led by the COMESA Clearing House, COMESA Business Council, GamSwitch Company Ltd, Institute for Inclusive Digital Africa, and the Central Bank of The Gambia.

Batching, Caching, and Cutting “Chatty” Work (Part 2 of 6)

Chris Law — Mon, 02 Mar 2026 15:30:04 +0000

In Part 2 of our v17 series, we highlight the architectural refinements designed to unlock sustained, high-volume throughput.

We have optimized the critical path by introducing high-efficiency batching for transfer workflows and streamlining processing steps to minimize latency.

At a national scale, every millisecond counts. These structural enhancements ensure the platform remains lean and responsive as transaction volumes grow, providing a future-proof foundation for global financial inclusion

If you operate or govern a national payment infrastructure, this series is written for you.

Batching, Caching, and Cutting “Chatty” Work (Part 2 of 6)

Delivered in support of programmes led by the COMESA Clearing House, COMESA Business Council, GamSwitch Company Ltd, Institute for Inclusive Digital Africa, and the Central Bank of The Gambia.

Building World-Class Mojaloop Platforms Together (Part 1 of 6)

Chris Law — Mon, 23 Feb 2026 11:56:40 +0000

Mojaloop is increasingly being relied upon as a national and regional payment infrastructure. In that role, performance is not a vanity metric; it is a trust requirement.

In Part 1 of our six-part series, we explore why sustained throughput, predictable latency, operational stability, and security-enabled performance are foundational to production-grade payment switches

Drawing on INFITX’s performance engineering work in Mojaloop v17, delivered in collaboration with the Mojaloop Foundation and adoption partners including COMESA DRPP and GISP Bantaba 2.0, we outline the core optimisations and reproducible deployment approach that strengthen real-world platform readiness

If you operate or govern a national payment infrastructure, this series is written for you.

Building World-Class Mojaloop Platforms Together (Part 1 of 6)

Delivered in support of programmes led by the COMESA Clearing House, COMESA Business Council, GamSwitch Company Ltd, Institute for Inclusive Digital Africa, and the Central Bank of The Gambia.

Attention developers: Nathan Delma is here to work with you!

Paula Hunter — Fri, 07 Nov 2025 15:00:00 +0000

https://mojaloop.io/nathan-delma-mojaloop-foundation-community-engineering-lead/