One Acre Fund: farmer repayments on M-Pesa, checked before money moves

The problem

One Acre Fund (OAF) lends in kind. Farmers get certified seed and fertiliser at planting time and repay in many small payments before harvest, and in Kenya almost all of that money arrives over M-Pesa. At OAF's scale, small problems per transaction become large sums: a fee that's slightly too high, a payment credited to the wrong account, a repayment that never reaches the farmer's loan record.

• Collections cost too much and went through a middleman. OAF wanted to cut transaction costs by moving repayments from paybill to M-Pesa's Buy Goods service, and to replace a third-party mobile-money aggregator with a direct M-Pesa integration.
• Farmers needed a simpler way to pay. OAF wanted USSD payments on the same shortcode as its core programme, so a farmer with a basic phone could repay without an app.
• Every shilling had to land on the right loan. Each payment had to be validated against OAF's loan systems before Safaricom collected it, and afterwards three records had to agree: the workflow engine, M-Pesa and the loan ledger.
• It had to stay up through the seasons that matter. This was live money in OAF's own cloud through planting and repayment seasons, and OAF's engineers had to be able to upgrade it without downtime.
• Later, money had to flow out too. By late 2023 OAF needed to pay farmers in the field for produce, with name-to-number checks so money couldn't go to the wrong phone, plus payroll and vendor payments tied into SAP and its approval process.

The outcome

• Live in production from February 2022, starting with a KSh 1 test payment and growing to Buy Goods collection, paybill payments with ledger validation, bulk disbursement and SMS confirmations across QA, UAT and production through 2024.
• About 1.2 million repayment transactions a month flowing directly to M-Pesa instead of through the aggregator.
• One deployment chart instead of three. Customer-specific forks were folded into one maintainable Helm chart, which later became the base for the GovStack G2P sandbox.
• OAF could run it themselves. Terraform and Helm playbooks let OAF operate, replicate and scale the hub in its own hosting.
• Releases stopped needing downtime. Immutable release tags, a published release checklist, and a rule that documentation and tests ship in the same sprint as the feature.
• Not finished, and said so. Payouts were scoped with OAF's finance and market-access teams but aren't proven live, and an effort to cut events per payment workflow from about 700 towards 50 changed its measurement approach midway, so there's no final number to report.

What shipped, when

How it worked

Farmer dials USSD
  └─► USSD gateway (SMS confirmations)
        └─► Payment Hub
              ├─► Loan system: validate      (is this a real, open loan?)
              ├─► M-Pesa: collect            (farmer confirms on handset)
              ◄── M-Pesa callback: success or failure
              └─► Loan system: post repayment

Connectors for M-Pesa and OAF's two loan systems (Paygops and Roster) plug into the same open-source hub, so validate, collect and post is one orchestrated BPMN flow rather than custom code per system. The payloads carried country, currency and wallet-operator fields from day one, so the design wasn't Kenya-only.

That is why the hotfixes in May 2023 were about amount handling in the loan-system connectors: a repayment that posts with the wrong amount type agrees with M-Pesa on the handset and disagrees in the ledger, and the mismatch surfaces at reconciliation or, worse, on a farmer's loan record.

Tradeoffs worth keeping

• A green dashboard is not a working service. Early on, health checks reported services as healthy while they were failing. Health checks should test the dependency that actually breaks. Test environments have the same blind spot: a release can pass integration and acceptance and still break production.
• Customer forks are debt. A separate OAF chart felt faster and became the thing blocking upgrades. One chart with feature flags cost more up front and paid for itself on the next customer.
• Release tags are promises. When a released tag was re-pushed, clusters kept the old image and the only reliable fix was a reinstall. Never overwriting a tag turned hotfixes back into routine deploys. The full mechanism: why you should never reuse a release tag.
• Decide which errors are retryable, and write it down. Retrying more raises success rates but slows responses. That's a business tradeoff, so we argued it out explicitly with OAF instead of letting defaults decide. Retrying is only safe when a repeated call can't collect twice, which is the case for idempotency keys in payments.

What I would do differently

• Fix the release process the first time it is asked for. OAF asked for the mutable-tag problem to be fixed as top priority in May 2022. The immutable-tag rule landed in October 2022 and the symptom was still being reported in February 2023. Every month in between was a production reinstall waiting to happen.
• Separate "our failure" from "Safaricom's failure" on day one. Alerting that tells a Payment Hub fault apart from an M-Pesa fault was agreed as an action during payouts discovery in November 2023, nearly two years after the first live transaction. It belongs in the first release, because it decides who gets paged.
• Measure before optimising. The effort to cut events per workflow from about 700 towards 50 changed how it measured midway, so there is no before-and-after number. Fix the measurement first, then the pipeline.