What Daraja actually is
Daraja (developer.safaricom.co.ke) is Safaricom's developer portal and the REST API layer over M-Pesa. You register an organisation, create an app, receive a Consumer Key and Consumer Secret, and exchange them for short-lived OAuth bearer tokens. Everything else — STK push, C2B, B2C, transaction status, account balance, reversal — is an HTTPS endpoint with JSON payloads. There is no SDK dependency you cannot live without; a working integration is disciplined HTTP, correct callback handling, and honest reconciliation.
A sandbox with predefined test credentials (the well-known shortcode 174379 for STK push testing) lets you build the entire flow before any production paperwork exists. Production access means going live per-app on the portal and completing Safaricom's production onboarding for your shortcodes.
What you can build with it
Four capability families cover almost every Kenyan business case. Collection (C2B): customers pay you via Paybill or Till, with optional validation and confirmation callbacks so your system approves or records each payment in real time. Checkout (STK push, the Lipa na M-Pesa Online API): your system triggers a payment prompt on the customer's phone mid-transaction — the standard for web and app checkouts. Disbursement (B2C and B2B): sending money to customers, staff or suppliers programmatically — payouts, refunds, settlements. Visibility: transaction status and account balance queries, plus the reversal API for error recovery.
Most systems we architect combine collection or checkout with a reconciliation layer — the part that turns a pile of callbacks into books that close cleanly.
How STK push actually works
The STK push flow has five steps. One: exchange your Consumer Key and Secret for an OAuth access token (client credentials grant, tokens expire — cache them, refresh before expiry). Two: build the request password by Base64-encoding shortcode + Lipa Na M-Pesa passkey + timestamp together. Three: POST to the processrequest endpoint with the business shortcode, password, timestamp, transaction type (CustomerPayBillOnline or CustomerBuyGoodsOnline), amount, customer's phone number as PartyA, your shortcode as PartyB, your callback URL, an account reference and a description. Four: Safaricom pushes a payment prompt to the customer's phone; they enter their PIN. Five: Safaricom calls your CallBackURL with a result — ResultCode 0 means success — and your system must respond promptly and record idempotently, because callbacks can and do arrive more than once.
The two engineering sins at this step are non-idempotent callback handling (double-recording a payment) and validating nothing before trusting the payload. Both are solved deliberately, not by luck.
Sandbox versus production
Build everything in the sandbox first: it exercises the same request shapes with canned responses and test credentials, which surfaces 80% of your bugs before money moves. Going to production involves switching base URLs (sandbox.safaricom.co.ke to api.safaricom.co.ke), using your production app's credentials, and — the part that surprises teams — production shortcode configuration: your Paybill or Till must be linked for the APIs you intend to use, and validation/confirmation URLs must be registered. Safaricom's onboarding for production shortcodes is a process with its own timeline; plan for it rather than discovering it the week you launch.
The security non-negotiables
Treat Daraja credentials like production database passwords: in a secrets manager, never in client-side code, never in a repo. Verify callbacks — at minimum, validate that the payload's structure, amounts and receipt codes match an initiated transaction before acting on it, and reject what doesn't reconcile. Use HTTPS everywhere (Safaricom requires https callback URLs) and prefer an allow-listed, unguessable callback path. Log every callback immutably, because when a payment dispute arrives three weeks later, the callback log is your evidence. And scope permissions: an app that only collects should not hold B2C credentials that can disburse.
What integration actually costs
The API itself is not where the money goes — Daraja access is free to register, and Safaricom charges transaction fees per M-Pesa rules, not per API call. The real cost is engineering, and the Kenyan market spans four tiers: off-the-shelf plugins (KSh 5,000–15,000 one-time), basic custom Daraja API work by a developer (KSh 20,000–50,000+), a hardened production checkout with idempotent callbacks and real security (KSh 50,000–120,000, typically two to four weeks), and a full commerce integration — collection, disbursement, reconciliation, admin tooling, failure handling — from about KSh 150,000 upward, with complex builds past KSh 500,000. We break this down honestly in our M-Pesa integration cost guide, including what drives each range.
Settlement reconciliation: the part everyone underestimates
Callbacks tell you a payment happened; settlement reports tell you what actually hit the bank. The two disagree regularly — timing differences, reversals, fees, duplicate notifications — and the difference is exactly where finance teams lose days. A proper integration matches transactions idempotently on Safaricom's transaction IDs, closes daily, and routes only genuine exceptions to a human. We treat reconciliation as a first-class feature, not a month-two surprise — the full reasoning lives in our settlement reconciliation guide.
When to bring in a studio
If you need one STK push button on an otherwise static site, a plugin or a competent freelance developer can ship it. Bring in engineering discipline when money paths compound: marketplaces and platforms where many parties transact; systems where the ledger must reconcile to the shilling; disbursement flows where a bug pays the wrong person; or an existing integration that has become nobody's job to maintain. The pattern worth remembering: the demo is easy, the system is the work. A studio's value is that the second one is the default, not the upgrade.
CONTINUE THE THREAD
DEFINITIONS FROM THE LEXICON
Related services: platform engineering & M-Pesa integration · pricing