Sim-Pesa is live.

Sixteen weeks ago, I could not log into the M-Pesa developer portal. Today, I shipped a local-first transactional appliance that simulates the entire M-Pesa STK Push flow — queue, locking, retries, webhooks, and all.

If you are new here: Sim-Pesa is a containerised payment simulator I have been building in public, one week at a time, to level up as a software engineer. This is the final entry. Be sure to check out the previous weekly blogs if you want to follow the full journey.

Let's close it out properly.

1. Where It Started

Four months ago, I wanted to understand how M-Pesa integrations actually work. The ecosystem that powers payments across East Africa felt like something I should know, but every time I tried to get started, I hit a wall.

The first attempt: YouTube tutorials. I could not follow them.

The second attempt: the official Daraja documentation. That day, the M-Pesa developer portal was refusing logins entirely — I never got in.

I eventually found Rizwan Hamisi's unofficial Daraja docs at mpesa-docs.vercel.app, which are genuinely excellent. But even then, I barely made it past the first page. The technical vocabulary alone was a problem — callback URLs, webhooks, idempotency, asynchronous communication — all of it was foreign to me.

My background at that point was Flask, Spring Boot, and university CRUD apps. Fintech was a different world.

I closed the docs and gave up.

2. The Idea

A few weeks later, the itch came back.

M-Pesa integrations were clearly valuable to know. But I kept running into the same barrier: the tooling around Daraja is built for developers who already understand the domain. If you are new, the learning curve is steep and the feedback loops are slow — because everything depends on external services that you do not control.

That became my pain point. And a pain point is the beginning of a project.

What if I built a simulator that makes Daraja approachable? Something that runs entirely on localhost, with no external dependencies, and lets developers test payment flows without fighting the sandbox?

I scoped it tightly. One feature: M-Pesa Express, known as STK Push. The most used Daraja endpoint. Nothing else.

Then I wrote a 14-page technical spec and a 16-week timeline.

Looking at it at my skill level then, it felt like a document written for a startup team of experienced engineers. Not a solo student project. But I committed to it anyway.

3. The Build

The first few weeks were rough.

I had never used Docker at scale, never touched Redis or BullMQ, and had only a surface-level understanding of PostgreSQL beyond basic queries. I was building with Node and TypeScript for the first time.

I fell into tutorial hell more than once. I started watching four-hour TypeScript courses and working through Docker documentation that ran to two hundred pages. At some point I realised that was the trap. You do not need to know everything about a tool before you can use it — you need to know just enough for what you are building right now.

Once I accepted that, things started moving.

Each week stacked knowledge onto the last. Concepts that had felt opaque started forming mental models. The technologies stopped feeling alien.

Some of the harder weeks:

• Week 6 — Concurrency control. I had to solve the problem of holding a database lock across human interaction time while a user enters a PIN. The answer was two-phase locking: acquire the lock, move the transaction to PROCESSING, release the database lock, then wait for the PIN event via Redis Pub/Sub. Simple in retrospect. Weeks of thinking to get there.

• Week 8 — First time writing tests. Testing exposed every architectural shortcut I had taken. Coverage ended up at 66% overall, but 87.5% on the integrity core. Lesson: bad tests are a symptom of bad architecture, not the cause.

• Week 13 — "UI week" turned into backend architecture week. Building real-time dashboard updates with Server-Sent Events forced a proper Redis Pub/Sub pipeline I had not planned for.

Every week had a version of that. A plan, a wall, a rethink, a solution.

You can read the full weekly breakdown in the build log series.

4. What Sim-Pesa Is Now

I started this project thinking of it as a learning exercise. Around Week 10 or 11, I stopped thinking of it that way.

It had become an actual tool.

Sim-Pesa is a local-first M-Pesa API simulator. You run it with Docker, complete a short onboarding flow that takes under sixty seconds, and immediately have a fully functional payment environment on your machine — with no dependency on Safaricom's sandbox.

Here is what you get out of the box:

• STK Push simulation

• Realistic webhook callbacks with the exact Daraja payload structure

• Real-time transaction monitoring via a live dashboard

• Manual PIN approval through a Virtual Smartphone UI

• Automatic exponential backoff retry logic for failed webhooks

• Intentional failure simulation (wrong PIN, insufficient funds, duplicate requests, cancelled transactions)

• Persistent transaction history across restarts

From your application's perspective, it behaves like a real M-Pesa environment.

Who it is for

Hackathon teams. Integrating Daraja under time pressure is painful — credentials, callback URL tunnelling, sandbox instability, and networking issues can burn hours that belong to the product. Sim-Pesa lets a team spin up the full stack locally, point their application at it, and demo a working payment flow reliably. No external dependency. No tunnel configuration.

Developers learning how payment systems work. Most tutorials show payments as synchronous: send request → receive success. Real systems are not like that. Payments are asynchronous. They involve queues, state transitions, retries, concurrency issues, webhook delivery, and human interaction delays. Sim-Pesa exposes those moving parts instead of hiding them.

You can watch a transaction move through PENDING → PROCESSING → SUCCESS or branch into FAILED and CANCELLED. You can simulate wrong PINs, duplicate submissions, and delayed callbacks. The goal is not to fake payments — it is to help developers understand how transactional systems actually behave.

Developers building payment integrations locally. Development environments that depend on external services you do not control are fragile. The sandbox is sometimes down. Callbacks sometimes never arrive. Requests timeout for no clear reason. Sim-Pesa moves the entire environment onto localhost — database, queue, worker, API, and dashboard — inside a self-contained Docker appliance. The environment becomes deterministic. That changes the developer experience more than I expected.

Anyone who wants to understand distributed systems visually. The Virtual Smartphone, live transaction feed, and real-time state updates turn invisible backend concepts into something interactive. Instead of just reading about asynchronous processing, eventual consistency, and transactional integrity, you can watch them happen. If you want to go deeper, you can subscribe directly to the Redis channels and watch the signals flowing through the system in real time.

5. What's Next

This project is finished. I do not think it is complete.

Sim-Pesa achieved what I set out to build. I wanted to deeply understand transactional systems, asynchronous workflows, queue-based architecture, concurrency control, and how real payment infrastructure behaves under pressure. Building it forced me to confront every one of those concepts directly, in a working system, with real consequences for getting it wrong.

But there is still a lot that can be improved:

• More realistic failure simulations

• Additional Daraja API endpoints beyond STK Push

• Webhook replay tooling

• Metrics dashboards and stronger observability

• CLI tooling for faster developer setup

• Multi-merchant support

• Better frontend polish

• Deeper contributor documentation

The idea itself has room to grow too. As M-Pesa integrations become more common across East Africa, developers need better local development tooling. Building payment integrations should not require fighting an unstable sandbox before you can even test your own business logic. That is the problem Sim-Pesa is trying to address.

If you are a developer who wants to dig in:

• Docs: simpesa-docs.vercel.app

• GitHub: github.com/paul-murithi/simpesa

Clone it. Break things. Raise issues. Open pull requests. Suggest ideas.

Somewhere around Week 6, this stopped being purely about me learning backend engineering. It became an experiment in building better developer experience around payment systems. I would like to see where that goes with more people involved.

This is the final entry of the Sim-Pesa build log. Sixteen weeks, sixteen posts, one finished product. Thanks for following along.

Tags: #mpesa #daraja #docker #nodejs #typescript #postgresql #redis #bullmq #fintech #buildinpublic #devtools #eastafrica #100daysofcode #backend