Welcome to another build log of Sim-Pesa. If you're new here, this is a project I've been building for 14 weeks now with the aim of leveling up my software development skills. It's a local transaction appliance designed to help developers test their M-Pesa payment integrations. It's built to run completely offline, removing the friction associated with the cloud Daraja API. Be sure to check out other articles in the series to follow what I've covered in previous weeks.

Last week, we built the React dashboard, bridging the gap between the backend and the frontend. The backend that we spent 12 weeks building — viewed through terminal logs and structured JSON — now has a nice UI with real-time updates.

This week, the main goal was to implement a Virtual Smartphone feature. I thought it would be cool to go a level higher and simulate the STK Push request.

The idea: Build a component complete with the phone chrome and user input keyboard, directly into our dashboard. In a real M-Pesa online integration, when you initiate a payment, you see that popup that appears on your phone for you to enter the PIN? That's what we want to add to Sim-Pesa.

The First Stumble: This Is an Event-Driven Problem

It's an easy component, right? We just add it as a modal that pops up after you initiate an STK Push request. How hard can it be?

It turns out, like everything else in our system, this too is an event-driven problem. Here's why.

Here's my current architecture at a very high level:

1. The user initiates an STK Push request

2. Auth middleware intercepts the request and checks Redis if the token is valid

3. If the token exists, the request is allowed to our Ingestion API

4. The Ingestion API is a thin layer that does minimal validation, DB insert, and enqueues the payment job, returning a response in <50ms

5. The worker reads jobs from the Redis Queue and starts processing the payment job

So far, so good. No real surprises there. The issue starts in the Worker service when it starts processing the job.

The Two-Phase Problem

Due to the human factor of manually typing a PIN, it wasn't feasible to hold DB locks throughout that time. So I split the processing into 2 phases or separate database transactions (you can read more about this in my Week 6 blog):

Phase 1 (Intent):

• Locks rows and does minimal validation (balance check)

• Moves the transaction to PROCESSING stage

• Releases locks and triggers PIN entry via the Virtual Smartphone

Phase 2 (Finalize):

• After user has entered PIN, Phase 2 runs

• Locks rows and rechecks balance again plus more validation

• Moves the transaction to a terminal state such as FAILED or SUCCESS

Here's what the code looked like:

async processTransaction(transactionalData: CreateTransactionDTO) {
  const { checkout_id } = transactionalData;

  // Phase 1: Lock rows and validate balance
  await repo.lockRowsValidate(transactionalData);
  await this.publish(checkout_id);

  // Keep PROCESSING visible long enough for dashboard SSE subscribers
  await wait(PROCESSING_VISIBILITY_DELAY_MS);

  // TODO: STK Push logic

  // Phase 2: Complete the transaction
  await repo.finalizeTransaction(transactionalData);
  await this.publish(checkout_id);
}

The Core Problem

Now we can clearly see that the transaction processing happens deep in the Worker layer. But the PIN prompt is in the UI client — in our case, a React dashboard. When the PIN is submitted, we have to send a POST request with the PIN entered as the form data.

So our current flow looks like this:

Worker: Phase1 → await PIN → Phase2

API: ↑ POST /pin arrives here

This is a classic problem where a long-running workflow spans two separate process boundaries (the Worker and the API). We need to manage the state of an asynchronous process across decoupled services that don't know about each other or share a memory space.

The Worker is literally await-ing something that will arrive through a completely different service. That's the crux of it.

The Solution: Continuation via Redis (A Shared Signal)

After much research and trial and error, I learned that the key insight is:

"You don't resume the worker. You let it finish, and you let the database act as the source of truth."

And it makes sense. It's what we've been preaching for this project ever since Week 1: "The database is the single source of truth." In a system driven by ephemeral events all over, one thing remains constant and true: The Database.

What We Were Doing Wrong

Our system was trying to hold the Worker hostage while it waits for a human to enter a PIN on the dashboard. In a distributed queue like BullMQ, a worker should never sit idle and wait() for external input.

If the Worker crashes, restarts, or the user takes forever to enter the PIN, that job is stuck in uncertainty, consuming memory and worker threads.

The Better Approach

Instead of one massive processTransaction() job that pauses in the middle, we need to break it down into distinct non-blocking events. Our transactions table status column already provides a finite set of states the transaction can be in. That would be the ultimate source of truth here.

One of the options I stumbled on was using BullMQ's moveToWaitingChildren. This is a built-in mechanism where, after Phase 1, the parent job moves itself to a waiting state. The PIN submission creates or resolves a child/dependent job that unblocks it.

But honestly, it was so complicated for me that I decided to reuse my current stack idea from last week.

We already used Redis Pub/Sub last week to publish and subscribe to events. Turns out we can use that same idea for this problem.

The Idea: Redis-Based Promise (Pub/Sub as a One-Shot Signal)

The idea is this:

After Phase 1, the Worker doesn't await finalizeTransaction directly. It awaits a Redis signal with a timeout.

The API layer, upon receiving the PIN POST, validates the PIN and publishes that signal.

So our logic becomes:

async processTransaction(transactionalData: CreateTransactionDTO) {
  const { checkout_id } = transactionalData;

  // Phase 1: Lock, validate, publish PROCESSING state
  await repo.lockRowsValidate(transactionalData);
  await this.publish(checkout_id);
  await wait(PROCESSING_VISIBILITY_DELAY_MS);

  // We SUSPEND here --- wait for PIN signal with a timeout
  const pinResult = await this.waitForPin(checkout_id, PIN_TIMEOUT_MS);

  // Check for pinResult returned message and publish events
  if (pinResult === 'TIMEOUT') {
    await repo.failTransaction(transactionalData, 1037); // DS Timeout
    await this.publish(checkout_id);
    return;
  }

  // Other checks for user cancelled request, wrong PIN, etc.

  // Phase 2: PIN was correct --- finalize
  await repo.finalizeTransaction(transactionalData);
  await this.publish(checkout_id);
}

The waitForPin() Function

The waitForPin() function waits for a PIN verification result using a Redis Pub/Sub channel. It subscribes to a channel tied to the checkout session and resolves when either:

• A message is received (e.g., CORRECT, WRONG_PIN, etc.)

• A timeout is reached

It uses a separate Redis connection for the subscription, cleans up resources after completion, and ensures the promise always resolves and never hangs.

Here's a high-level overview of what the function does:

function waitForPin(checkoutId, timeout):
  create Redis subscriber
  subscribe to "pin:<checkoutId>"
  
  start timeout timer:
    on timeout:
      unsubscribe + disconnect
      return "TIMEOUT"
    
    on message received:
      cancel timer
      unsubscribe + disconnect
      return message

The API Layer: Handling PIN Submission

Then in our API layer, we create a new dynamic route using the endpoint: /stkpush/pin/:checkout_id

The endpoint performs these actions:

1. Fetches the Transaction to Get the Phone Number

const txResponse = await service.getTransactionByCheckoutId(checkout_id);
const tx = txResponse.rows[0];

2. Validates the PIN Against the Users Table

const userResult = await service.getUserByMsisdn(tx.phone_number);
const user = userResult.rows[0];

if (user.pin === pin) {
  child.info("PIN submitted. Publishing pin signal");
  await service.publishPinSignal(checkout_id, "CORRECT");
} else {
  child.error("User submitted wrong PIN");
  await service.publishPinSignal(checkout_id, "WRONG_PIN");
}

3. Signal the Waiting Worker

Note that the channel has to be the same:

async publishPinSignal(checkout_id: string, signal: string) {
  await redisClient.publish(`pin:${checkout_id}`, signal);
}

Handling Cancellations

To handle the case where the user cancels the PIN prompt (simulating how a real user might cancel the STK Push prompt), we make a new endpoint that just publishes the CANCELLED signal:

stkRoute.post(
  "/cancel/:checkout_id",
  asyncHandler(cancelTransaction)
);

child.info("Request cancelled. Publishing CANCELLED signal");
await service.publishPinSignal(checkout_id, "CANCELLED");

How That Solves Our Problem

With that new flow, our new high-level architecture looks like this:

Worker: Phase1 → waitForPin() ← blocking on Redis SUB
                      ↓
API: POST /pin → publish('CORRECT') ──→ worker unblocks → Phase2
     or publish('CANCELLED') ──→ worker unblocks → FAILED

Timeout: after N seconds → 'TIMEOUT' ──→ worker unblocks → FAILED (1037)

The two services coordinate through Redis, which is already our shared backbone in the system. The Worker never holds a DB lock while waiting. It released the lock at the end of Phase 1, which is still the pattern our two-phase design was meant to support.

Important Detail: BullMQ Job Timeout

One important detail that came up here was BullMQ job timeout. BullMQ has a built-in mechanism that can fail a job if it takes too long without "checking in." If the code logic pauses for a long time, the job may be marked as stalled, which can lead to it being retried or failed.

How it works:

1. When a worker picks up a job, it places a "lock" on it for a specific duration (default is 30 seconds)

2. Automatic Renewal: Under normal conditions, BullMQ automatically renews this lock in the background while code is running

3. The Problem: If the code logic is CPU-intensive and blocks the Node.js event loop for too long, the worker cannot renew the lock

4. Result: BullMQ assumes the worker has crashed. The job is then marked as stalled and moved back to the "waiting" state to be processed again (or moved to "failed" if it exceeds the maxStalledCount)

To ensure our long-running job runs safely, I adjusted the lockDuration with a timeout longer than our STK PIN timeout. Otherwise, BullMQ would kill the job mid-wait.

This design maps cleanly to our spec's "Stage 4: Simulation Interaction" section and keeps the two-phase transaction integrity intact. The Worker suspends without holding any locks, the API handles the user interaction, and Redis is the thin coordination layer between them.

The React Frontend: The Virtual Smartphone

After setting up everything on the backend, it was time to integrate that to our frontend. What we're aiming for: when a user clicks "Initiate STK Push," the request is sent to our Ingestion API, processed by the Worker, and after Phase 1 runs and the transaction moves to PROCESSING, the UI should react and show the Virtual Smartphone for PIN entry.

The PinModal Component

To do that, I created a new functional component called PinModal that takes in PinModalProps:

• checkoutId — Represents a unique identifier for each transaction

• amount — Represents the transaction amount

• onClose() — Function that handles closing and opening of the smartphone modal

const PinModal = ({ checkoutId, amount, onClose }: PinModalProps) => {}

Handling PIN Submit

On PIN submit, the handleSubmit() function runs, sending a request to the endpoint we set up earlier:

const handleSubmit = async () => {
  if (pin.length !== 4) return;

  setIsSubmitting(true);
  setHasError(false);

  try {
    const response = await fetch(getApiUrl(`/stkpush/pin/${checkoutId}`), {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ pin }),
    });

    // Handle onClose and catch errors
  }
};

The Styling Challenge

From there, all that remained was the styling. As expected, it was quite difficult styling the component to make it look and feel like an actual smartphone. I utilized CSS and JavaScript for this final polished look:

Auto-Approve: The Fast Path

The final consideration is to enable auto-approve if the developer wants that fast and direct flow. If the auto-approve toggle on the dashboard is on, the dashboard automatically sends the default PIN to the backend without triggering the Virtual Smartphone modal.

I utilized a custom React hook:

export const useAutoApprovePin = ({
  autoApprove,
  pendingPinTx,
  setPendingPinTx,
}: UseAutoApprovePinParams) => {
  // Only run when auto-approve is enabled and a transaction exists
  if (!autoApprove || !pendingPinTx) return;

  // Send PIN automatically
  await fetch(`/stkpush/pin/${pendingPinTx.checkout_id}`, {
    method: "POST",
    body: JSON.stringify({ pin: "1234" }),
  });

  // Clear state after submission
  setPendingPinTx(null);
};

That React hook automatically submits a PIN when a transaction is pending and auto-approval is enabled. When triggered, it sends a request to the backend with a predefined PIN and clears the pending transaction state afterwards.

The high-level overview:

on change of (autoApprove, pendingTransaction):
  if autoApprove is false OR no pending transaction:
    do nothing
  otherwise:
    send POST request with PIN to backend endpoint
    if successful:
      clear pending transaction
    if error:
      log error

Otherwise, the UI renders the Virtual Smartphone:

{!autoApprove && pendingPinTx && (
  <PinModal
    checkoutId={pendingPinTx.checkout_id}
    amount={pendingPinTx.amount}
    onClose={() => setPendingPinTx(null)}
  />
)}

Final Insights: The Before and After

The Starting Point (Before)

Before we started, the transaction flow in apps/worker was "synchronous" from the Worker's perspective. It would:

1. Phase 1: Check if the user has enough money and lock the rows in the database

2. Phase 2: Immediately deduct the money and credit the merchant

The Problem: Real-world mobile money (like M-Pesa) doesn't work this way. When you initiate an STK Push, the system suspends the process while waiting for the user to physically type their PIN into their phone. Our system was missing this "human-in-the-loop" pause.

Summary of the Final Flow

1. API: Receives payment request → Queues job in BullMQ

2. Worker: Starts Job → Runs Phase 1 (DB check) → Pauses (Starts Redis Subscriber)

3. UI: Sees "PROCESSING" status via SSE → Pops up the PIN Modal

4. User: Enters PIN → UI hits API /stkpush/pin

5. API: Publishes "CORRECT" to Redis

6. Worker: Hears Redis signal → Resumes → Runs Phase 2 (Move money) → Job Complete

What's Next: The Onboarding Wizard (Week 15)

With that architecture, we've officially hit the Week 14 KPI. Next week, we build the Registration Flow — the "First Run" onboarding wizard.

The main goal of Sim-Pesa is to reduce friction for developers and other users testing their payment workflows. And to do that, we have to ensure that when the developer clones the repo and runs docker compose up, everything just works with zero or minimal manual configurations.

That's what Week 15 will be about. We're in the final stretch — only 2 weeks left.

Stay locked in for the next episode.

Tags: Redis Pub/Sub · Event-Driven Architecture · React · Virtual Smartphone · STK Push Simulation · BuildInPublic