DEV Community: Ronny Nyabuto

Building eTIMS for Concurrent POS Traffic

Ronny Nyabuto — Tue, 21 Apr 2026 10:12:05 +0000

Building an eTIMS integration that actually handles concurrent POS traffic taught me something I didn't expect to find in a government tax spec.
The scenario: a POS terminal submits an invoice, the network hiccups, the terminal retries. Both requests hit your signing service within milliseconds of each other. Standard idempotency pattern is: SELECT to check if this invoice key exists, proceed if absent. Under concurrent retry storms, both requests pass that check before either writes the result. Both invoke the VSCU JAR. Both get signed.
You now have two KRA fiscal receipt numbers for one commercial transaction.
This is not a deduplication problem you can fix in a database. KRA receipt numbers are issued by the JAR and registered upstream. The VSCU Specification v2.0 §4.4 has explicit sequence integrity requirements — gaps AND duplicates in rcptNo surface during KRA audits. You cannot unissue a receipt number. The defect is permanent.
Most engineers I've talked to immediately reach for Redis or a distributed lock manager. I get it — the instinct makes sense. But the database you're already running has atomic COMMIT semantics. That's your mutex.
The pattern that actually works: don't SELECT then INSERT. Just INSERT. Attempt the write immediately against a tenant-scoped key. Let the PRIMARY KEY constraint be the gate. INSERT succeeds → you're the winner, sign the invoice, commit the response. INSERT throws DataIntegrityViolationException → you're the loser, another thread owns this key. Poll for the winner's committed result and replay it verbatim. Winner crashes mid-flight → delete the placeholder, next attempt re-enters as a fresh winner.
Exactly-once fiscal receipt generation. No Redis. No Zookeeper. No distributed lock service. Just PostgreSQL doing what PostgreSQL has always done.
The deeper lesson building TaxID — our middleware layer that abstracts the VSCU JAR for ERP and POS integrations — is that you have to engineer to the cost of failure, not the probability. A 1-in-10,000 duplicate in a shopping cart is a recoverable annoyance. The same race condition in a government-mandated fiscal system is an audit defect with legal consequences under the Income Tax Act §16(1)(c). The probability is the same. The irreversibility is not.
One more §2.2 Policy 4 fact that surprises people: the VSCU JAR stops issuing receipt numbers after 24 continuous hours without a successful KRA sync. Not degrades. Stops signing entirely. If your offline queue architecture assumes unlimited buffering, it's wrong. The ceiling is documented, enforced by the JAR, and non-negotiable. At hour 24, the platform enters SUSPENDED state regardless of how much local queue capacity you have.
Read the spec before you build the queue.

What Daraja 3.0 actually changed for developers — and what it did not

Ronny Nyabuto — Thu, 16 Apr 2026 07:29:39 +0000

What Daraja 3.0 actually changed for developers — and what it did not.

Safaricom launched Daraja 3.0 on November 25, 2025, at the M-Pesa Integrators Forum in Nairobi. The press release mentioned cloud-native architecture, Security APIs, Mini App support, and a self-service onboarding model replacing the old paper-based process. 105,000 registered developers. The biggest M-Pesa API update since Daraja 2.0 launched in 2019.

Most of the coverage repeated the press release. This post does not.

What actually changed

The platform underneath changed. Daraja 3.0 moved to a cloud-native, microservices-based architecture. Safaricom claims capacity for up to 12,000 transactions per second — a significant ceiling lift over the previous architecture. The developer portal was redesigned. Self-service onboarding is now available, meaning you can go live without the old manual approval process that required back-and-forth with Safaricom's integration team.

New API categories were added:

Ratiba — scheduled and recurring payments. Daily, weekly, monthly, yearly billing cycles. This is new. There was no recurring payment API in Daraja 2.0.

Security APIs — fraud detection, prevention, identity verification. Limited public documentation available.

IoT APIs — payments for connected devices. Limited public documentation available.

Mini App platform — build lightweight apps that run inside the M-Pesa Super App. Built on Ant Group's Mini Program framework, the same technology that powers Alipay mini-apps. A separate IDE, a JavaScript-based SDK, a submission and approval process. This is a different ecosystem from anything that existed before.

What did not change

The STK Push endpoint path is the same: /mpesa/stkpush/v1/processrequest.

The OAuth token endpoint is the same: /oauth/v1/generate.

The callback payload structure is the same: Body.stkCallback, MerchantRequestID, CheckoutRequestID, ResultCode, CallbackMetadata.Item.

The base URLs are the same: sandbox.safaricom.co.ke for sandbox, api.safaricom.co.ke for production.

The authentication model is the same: base64-encoded Consumer Key and Consumer Secret, standard OAuth2 client credentials flow.

Existing Daraja 2.0 integrations do not break. If your code hits the STK Push endpoint and handles callbacks correctly, it continues to work on Daraja 3.0 infrastructure without modification. Safaricom was deliberate about backward compatibility on the core payment flows.

What changed at the developer portal level

Mandatory 2FA to access documentation. This sounds minor. It is not minor when you are trying to quickly look up a parameter while debugging at 11 p.m. and your authenticator app is on a different device.

Self-service onboarding. Previously, going live required manual review by Safaricom's team. The timeline was unpredictable. Self-service removes that bottleneck entirely.

The AI support chatbot. Community feedback is mixed. It answers common questions but struggles with edge cases and often redirects to the same documentation pages that didn't answer the question in the first place.

The sandbox problem

The Daraja 3.0 sandbox is unstable for failure-state testing. Connections drop. The environment runs almost exclusively in success mode — STK Pushes succeed, callbacks arrive, ResultCode is 0.

What you cannot test in the official sandbox: insufficient funds (ResultCode 1), wrong PIN exhaustion (ResultCode 2001), USSD timeout (ResultCode 1037), cancelled by user (ResultCode 1032), request in progress (ResultCode 1025).

Developers who only test against the official sandbox ship code that has never encountered a real failure mode. Production is where they find out what ResultCode 1032 looks like. Production is not the right place to find that out.

Pesa Playground, released December 2025, exists specifically to fix this. It runs offline, simulates the full mini-economy with persistent balances, and supports every failure state the official sandbox cannot. It is community-built, actively maintained, and the closest thing to a reliable local development environment the Daraja ecosystem has. If you are building on Daraja and not using Pesa Playground for failure-state testing, you are testing with one hand behind your back.

The Mini App platform — a separate conversation

The Mini App platform deserves separate treatment because it is not an extension of the existing Daraja API. It is a different product.

Mini Apps are JavaScript-based. They run inside the M-Pesa Super App container. The SDK is from Ant Group's Mini Program framework — the same technology powering Alipay's mini-app ecosystem. Development happens in a proprietary IDE called Mini Program Studio. The submission and approval process mirrors the WeChat/Alipay model.

If you are a Flutter developer expecting to build a Mini App in Dart, the answer is no. The two ecosystems do not intersect. Mini App development is JavaScript. Flutter is not involved.

There are already 80+ Mini Apps live in the M-Pesa Super App across Kenya, Lesotho, Ethiopia, and Mozambique. The platform is real and active. It is also completely separate from anything discussed in the Daraja API documentation, and Safaricom does not make this distinction prominently in their Daraja 3.0 marketing.

The honest summary

Daraja 3.0 is a platform upgrade, not an API overhaul. The developer experience has improved meaningfully — self-service onboarding is genuinely better, the capacity improvements are real, Ratiba is a net-new capability that was missing for years.

The core STK Push flow, the callback architecture, the asynchronous delivery model, the sandbox limitations — these are unchanged. The fundamental integration challenges that make M-Pesa difficult to build on correctly are the same in Daraja 3.0 as they were in Daraja 2.0.

There are no community SDKs updated for Daraja 3.0. There are no Flutter packages targeting the new endpoints. The only Daraja 3.0 SDK in existence is a C# library published March 2026.

The gap between what Daraja 3.0 makes possible and what the tooling ecosystem currently supports is wide. It will not close on its own.

Research conducted April 2026. Sources: Safaricom press release Nov 25 2025, TechCabal, TechArena, Techweez, developer.safaricom.co.ke, mpesaminiapps.safaricom.co.ke, github.com/OmentaElvis/pesa-playground. Daraja portal requires authenticated login for full API catalog.

Tags: mpesa flutter dart webdev

Safaricom's sandbox STK Query API returns FAILED for successful payments. Here's what's happening.

Ronny Nyabuto — Mon, 30 Mar 2026 16:17:02 +0000

Running reconciliation against the Daraja sandbox last week, I got this:

{"checked":3,"matched":0,"skipped":0,"mismatches":[
  {"checkoutRequestId":"ws_CO_26032026133641276708729173",
   "storedStatus":"PENDING","mpesaStatus":"FAILED"},
  {"checkoutRequestId":"ws_CO_26032026111016899708729173",
   "storedStatus":"SUCCESS","mpesaStatus":"FAILED"},
  {"checkoutRequestId":"ws_CO_26032026113146397708729173",
   "storedStatus":"SUCCESS","mpesaStatus":"FAILED"}
]}

The last two entries are the problem. Both have confirmed M-Pesa receipts in the database — UCQ5UAQ403 and UCQ5UAPYRY — with confirmed deductions on the test account. The STK callback delivered ResultCode: 0 for both. Money moved. Safaricom's own callback said so.

The STK Query API disagrees. It says both payments failed.

I searched Stack Overflow, the Safaricom GitHub repos, every community integration I could find. No prior documentation of this. Not a single issue or comment. It appears to be unreported.

What's actually happening

Safaricom's sandbox doesn't fully simulate the USSD network layer. This is documented behavior — it's why Pesa Playground exists. The sandbox can't reliably generate failure states. What's less documented is the inverse: the sandbox STK Query endpoint apparently cannot reliably confirm success states either. It defaults to FAILED when it can't definitively resolve a transaction, regardless of what the callback already told you.

The sandbox callback and the sandbox STK Query are not reading from the same source of truth.

How mpesa-stk@0.1.1 handled it

The library refused to act on the contradiction. matched:0 — it checked the payments, found that the STK Query response conflicted with an authoritative stored SUCCESS, and did not overwrite. The PENDING record from the orphaned payment stayed PENDING rather than being incorrectly resolved to FAILED.

That is the correct behavior. A reconciliation system that overwrites SUCCESS with a contradictory query response would be worse than one that does nothing.

What this means for your reconciliation implementation

Two things need to be true in how you handle STK Query responses:

Never overwrite a terminal SUCCESS or confirmed FAILED record based on a query response alone. The callback is the authoritative source. The query is a fallback for records that never received a callback — PENDING only.

Don't trust sandbox reconciliation results. The sandbox STK Query is not a reliable test surface for this code path. Test your reconciliation logic against a production environment, or accept that sandbox results for this specific path are noise.

The production question

I haven't run this against a live production environment. Safaricom's documentation implies the production STK Query returns accurate results — the sandbox is the broken environment, not production. If you've tested reconciliation in production and can confirm the query API behaves correctly there, I'd like to know. Leave a comment or find me on the Daraja Discord.

The finding stands regardless: if you're building reconciliation, your implementation needs to handle contradictory query responses. The sandbox will generate them. Production might too, in edge cases nobody has documented yet.

Tested on 2026-03-26, Daraja sandbox, mpesa-stk@0.1.1. Full test log in the flutter-daraja-raw repo.

I measured M-Pesa STK Push polling lag on a real device. The variance will ruin your UX.

Ronny Nyabuto — Thu, 26 Mar 2026 11:49:01 +0000

Same code. Same device. Same network. Same shortcode.

Test 1: 39 seconds from PIN entry to UI update.
Test 2: 3 seconds.

13x variance. Not a bug. Not a fluke. Just the math of a fixed polling schedule colliding with a non-deterministic callback.
When you fire an STK Push, Safaricom returns a CheckoutRequestID and ResponseCode: 0 almost immediately. Most developers celebrate this. It means nothing. It means Safaricom received your request. The customer hasn't seen a prompt yet.

The actual payment outcome arrives later — via a POST to your CallBackURL. That callback takes 5 seconds or it takes 45. Safaricom doesn't tell you when it's coming. And if your server isn't reachable when it arrives, Safaricom does not retry. The delivery attempt is fire-and-forget.

So the typical Flutter developer does what makes sense: they poll. Every 10 or 30 seconds, ask the server if anything happened. This works until it doesn't.

My polling schedule fired at T+10s, T+30s, and T+70s. In Test 1, the callback landed at T+45s — squarely between the T+30 and T+70 windows. The next poll was 25 seconds away. Safaricom completed the payment in 14 seconds. The user waited 39.

Test 1:
  PIN entered:        11:10:48
  Callback processed: 11:11:02  (14s — Safaricom's side)
  UI updated:         11:11:27  (39s — polling lag)

  Polls: T+10 → PENDING, T+30 → PENDING, T+70 → SUCCESS

Test 2:
  PIN entered:        11:31:55
  Callback processed: 11:31:59
  UI updated:         11:31:58  (3s)

  T+10 poll and callback arrived within 1 second of each other.
  Lucky timing. Not better code.

The same polling schedule. The only variable was when Safaricom's callback landed relative to the poll windows.

There is one optimisation that actually moves the number.

The real-world flow for most users: tap "Pay," get the USSD prompt, press home, open M-Pesa to confirm the request or check their balance, enter PIN, return to your app. The app was backgrounded the entire time. The callback arrived and was processed server-side while the user was in a different app. Without WidgetsBindingObserver, they come back to a spinner and wait for the next scheduled poll.

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.resumed) {
    ref.read(paymentProvider.notifier).checkStatusOnResume();
  }
}

The moment they return to your app, you poll immediately. My Test 7 result: 1–2 seconds from return to PaymentSuccess.

That is not a polling win. That is knowing when to trigger the poll. Most Flutter M-Pesa implementations do not have this. The USSD flow almost guarantees the user will background the app. The one scenario you should optimize for is the one most developers leave unhandled.

The failure mode nobody documents is worse.

Test 3: I killed the ngrok tunnel after the STK Push was sent but before the customer entered their PIN. Customer paid. Balance reduced. Server never received the callback. Safaricom made one delivery attempt, got no response, and moved on.

DB state after 90 seconds:

status:               PENDING
result_code:          null
failure_reason:       null
mpesa_receipt_number: null

The app timed out and displayed: "Status unknown. We did not receive a confirmation within the expected window."

That copy is deliberate. Telling a user their payment failed when money has already left their account is not a UX problem. It is a trust problem. The distinction matters more than most developers realize until a customer calls.

This is not a contrived scenario. It happens when your server restarts, when your laptop sleeps during a demo, when a deployment takes thirty seconds at the wrong moment. Safaricom does not retry. The only recovery is reconciliation — query the STK Push Query endpoint on a schedule and resolve orphaned PENDING records.

One caveat: Safaricom's sandbox STK Query API returned FAILED for confirmed SUCCESS payments during testing. That is a known sandbox limitation. Production behaves correctly.

The baseline from this session:

Polling lag: 3–39 seconds, non-deterministic.
Callback delivery: 100% when the server is reachable. 0% when it isn't.
Lifecycle optimisation: 1–2 seconds on resume, which covers the most common real-world flow.

Every Flutter developer building on M-Pesa either lives with these numbers, reinvents the solution from scratch, or doesn't know the problem exists until a production incident surfaces it.

No maintained Flutter package handles the full lifecycle — callback receipt, persistence, polling fallback, lifecycle recovery — without requiring a separately managed backend. That is the gap.

The next post will show what happens when you replace the polling cascade with Appwrite Realtime. The numbers are not subtle.

Tested on Google Pixel 9, Android 15. Daraja sandbox, Flutter 3.41. All timings are from real device logs. Test harness: flutter-daraja-raw.