A payments building block any government can reuse

The problem

Governments pay people through a patchwork: a pension scheme here, a cash-transfer programme there, school grants somewhere else, each with its own beneficiary list and bank arrangement. GovStack's 2023 webinar series showed the scale: India reported 318 direct-benefit programmes moving about USD 80 billion to 1.78 billion beneficiaries in a year, Senegal said 92% of its government payments were already digital, and Nigeria had issued 97.5 million national ID numbers.

GovStack's bet was that payments could be specified once, as a reusable "building block", and implemented by any conforming vendor. Governments, international bodies and banking working groups had tried to define a generic government payments API before and not got there, because the constraints pull against each other:

• Every country's rails differ. Some route all payments through a central-bank switch on ISO 20022 or ISO 8583; others reach mobile money only through aggregators. Cards, ACH, wires and wallets all had to be reachable.
• Paying someone means finding their account, and that is a privacy problem. Linking a national identity to a financial address can't mean passing raw beneficiary data around in batches, which is still how many government systems work.
• Treasury keeps control. A ministry of finance may need to approve every batch before money moves.
• Prior art covered pieces, not the whole. Mojaloop, Mifos and the GSMA mobile-money APIs each solved part of the problem.

Delivery was a second problem of the same size: 219 must-have requirements, a five-organisation consortium, acceptance gated by independent reviewers, and other building blocks, such as Information Mediation (X-Road), being built at the same time.

The outcome

• Four modules shipped as open source, with no fork. Identity Account Mapper, Bulk Processor, Voucher Engine and Bill Pay were merged into the public Mifos Payment Hub EE codebase under MPL 2.0, so any government or vendor can use them.
• A shared G2P sandbox. A multi-tenant environment where the whole chain runs end to end, with separate tenants playing the paying bank, the payments building block and the receiving banks. It was later reused for hackathons and other government-payment programmes.
• 135 test cases catalogued, 99 executed, 0 failures. The 24 out-of-scope and 12 future cases were published alongside the passes.
• 88 requirements closed in a single integration sprint by evidencing what the existing platform already did (rate limiting, identity and access management, reconciliation, ISO 20022 status codes) instead of rebuilding it.
• A handover that lets someone else run it: a five-module training curriculum and a security knowledge transfer covering message signing, TLS, field-level encryption and API-gateway configuration.
• Gaps stated openly. Interoperability with the Information Mediation building block was documented as unproven at closure and carried forward as follow-on work, and delivery ran into 2024, past the original 2023 plan.

What shipped, when

How it worked

Instead of starting a new product, we extended Mifos Payment Hub EE, an open-source payment orchestrator. Every payment flow is a BPMN process run by Zeebe, small stateless connectors do the work, and every event streams through Kafka for audit. Adding a new rail means adding a connector and a diagram, not changing the core, which is what "generic across schemes" needs in practice.

Identity Account Mapper: privacy as an API

Government systems send a functional ID and never handle account numbers. The functional ID combines a foundational ID with an agency code and a programme code, so one person gets a separate, unlinkable identity in each programme. The mapper resolves it to a bank account, wallet or voucher at payment time, and the paying bank never sees the full identity record.

Bulk Processor: reject bad rows before money moves

A government batch is split into individual payments, each payee is checked against the mapper, valid rows are regrouped by destination bank, treasury approves, and results flow back to the programme.

Voucher Engine and Bill Pay

Vouchers serve programmes where cash is the wrong instrument, such as seed or food, and issuance is all-or-none so a programme never ends up with a half-issued run. Bill Pay handles money flowing back to government (bill lookup, payment and request-to-pay) on the same platform.

Tradeoffs worth keeping

• Extend a mature platform instead of building fresh. It constrained some design choices, but it closed 88 requirements in one sprint and left governments with software that already had a community behind it.
• Publish the failures with the passes. We self-assessed against GovStack's cross-cutting requirements early and listed the gaps (idempotency, API versioning, key rotation, timestamps, webhooks) as tracked work. Reviewers trusted the passes because the gaps were visible.
• When the spec and the code disagree, fix the code. Where delivered APIs had drifted from the published specification, we reworked them to match rather than arguing the interpretation. A standard only works if implementations follow it exactly.
• Pick the process that fits the project. A heavyweight scaled-agile framework didn't suit a small consortium; delivery picked up once we switched to plain Scrum and Kanban.

Public references: GovStack Payments specification · Mifos on GitHub