Case study · Agent banking
Finseer: agent banking for rural India, on three rails and one ledger
Grameen Impact Ventures runs a network of village agents who give rural customers cash withdrawals, bill payments and merchant payments. I was architect and product owner of Finseer, the open-source platform behind that network, which ran in production from 2022 into 2024.
The problem
Agent banking is how formal finance reaches most of rural India. A local shopkeeper with a fingerprint scanner lets customers withdraw cash from their Aadhaar-linked bank account (AePS), pay bills over the national BBPS network, and pay merchants by scanning a UPI QR code. The agent earns a commission, supervisors manage clusters of agents, and the programme measures itself on gross transaction value (GTV) and agent income.
- Three rails, three partners, one ledger. Cash withdrawal ran through Fino Payments Bank, QR collection through Razorpay, and bill payment through a BBPS biller catalogue that kept changing. All of it had to post correctly into one ledger, with agent and supervisor hierarchies and GTV calculated on top.
- The numbers didn't match. The analytics store showed more transactions than the ledger, and some supervisors' GTV was missing from dashboards. A report that disagrees with the ledger is worse than no report.
- Production was falling over. By spring 2022 the production server was failing almost daily, and an agent standing in front of a customer who wants cash can't ask them to come back later.
- Partners changed their contracts under us. In 2024 Fino replaced its cash-withdrawal API with a version that needs an extra authentication call, and Razorpay retired the webhook event that QR collection depended on, which meant every existing QR customer had to be re-registered.
- The legacy reporting tool broke builds. It needed manual database changes that didn't survive containerised deployment.
The outcome
- About 2.5 years in production, covering fingerprint cash-out, UPI QR merchant collection and bill payment across GIV's agent network.
- Two forced partner migrations absorbed without losing the service. The new Fino withdrawal flow was tested in production jointly with GIV, with no further issues reported, and QR customers moved to Razorpay's new event model.
- Dashboards finance could trust. The legacy reporting tool was replaced with Grafana and Kibana, and no number reached a dashboard until it matched GIV finance's own reports.
- Daily outages ended by fixing the cause (an overloaded balance-validation batch job) instead of only restarting servers, backed by an incident protocol, deploy pipelines and a move to Kubernetes.
- A recovery point proven by restoring it. Every data store was backed up, restores were verified by matching row counts on the tables that hold money, and copies were staged in a separate AWS region. Long-term archival was still open work at the end.
What shipped, when
| When | Milestone |
|---|---|
| Mar 2022 | BharatQR merchant collection live, in UPI-only mode |
| May 2022 | Root cause of daily outages found; incident protocol and deploy pipelines in place |
| Jan 2024 | Fino's new authenticated cash-withdrawal flow live in production |
| Apr 2024 | QR registration and callbacks migrated to Razorpay's new event model, tested with GIV |
| Jun 2024 | Full backup of every data store, restore verified, staged in a second AWS region |
How it worked
Finseer extends Apache Fineract, an open-source core banking system I had earlier taken to bank scale for Novopay and IDFC's Bharat Banking division, so customers and agents have real savings accounts, overdraft limits and a full ledger, not just a payment switch. Each partner rail sits behind Finseer's own API. When Fino changed its withdrawal contract, agents' devices kept calling Finseer, and only the adapter behind it changed:
Agent device ─► Finseer: authenticate agent (wraps Fino's new auth call)
◄─ auth transaction ID
Agent device ─► Finseer: cash withdrawal (carries the auth transaction ID)
├─► Fino: withdrawal
└─► Ledger: post to agent float and customer account
Razorpay's change followed the same pattern: the registration and callback APIs changed inside Finseer, were tested against stubs first and then with GIV, and existing customers were re-registered.
Tradeoffs worth keeping
- Wrap every partner behind your own endpoint. It adds a layer, but it kept two partner API changes inside one adapter each instead of reaching every agent's device. Callbacks that can arrive twice are the other half of the same problem; I cover that in idempotency keys in payments.
- Operational failures look like code failures. The last "bug" in the Fino migration was an agent float account without enough balance. Check the business state before debugging code.
- Reconcile before you visualise. A verification step before publishing slowed new dashboards down and made them believable.
- Name both fixes. A scheduled early-morning restart was a fine stop-gap as long as the real fixes (the batch job and a proper Kubernetes deployment) were tracked beside it.
- A backup you haven't restored is only a hope. Verify it on the tables that hold money.
Still open at handover
Not everything was finished, and the backlog says so rather than hiding it. Three items were still open when the engagement ended in September 2024: moving the ledger database from MariaDB/MySQL to Postgres, a continuous-integration pipeline for the newer Fineract CN codebase, and a larger automated test suite. Long-term archival of the verified backups to cold storage was planned but not done. If I ran this again, the test suite would come first: both partner migrations had to be proven jointly with GIV in production, and more automated coverage would have shortened that.