M-Pesa Daraja integration done properly, in production.

STK Push (Lipa na M-Pesa Online): customer-facing checkout done right

STK Push is the most common Daraja integration request, and also the most commonly broken one. The API call that initiates a push is straightforward. The complexity sits in everything that follows: the callback that Safaricom posts to your server must be reachable from the public internet, must respond within a narrow window, and must handle the full range of result codes — not just success. We structure STK Push integrations with a dedicated callback endpoint that validates the incoming payload signature, writes a transaction record in a pending state before the push is even initiated, and transitions that record to confirmed or failed based on the callback result. If Safaricom never delivers a callback — which happens — the integration polls the transaction status API on a configurable schedule rather than leaving a payment dangling. The customer sees a definitive outcome. Your ledger matches.

• Dedicated callback endpoint with payload validation and idempotency key enforcement
• Pending transaction record written before STK Push is initiated
• Automated status polling for callbacks that never arrive
• Full result-code handling — including cancellations, timeouts, and insufficient funds

C2B and B2C: paybill/till collection and bulk payouts

C2B (customer-to-business) handles payments made by customers to your paybill number or till. The integration registers your confirmation and validation URLs with Safaricom, receives incoming payment notifications, and matches them to open orders or accounts in your system. Validation URLs let you accept or reject a payment before it settles — useful when you need to verify an account reference before funds land. B2C (business-to-customer) runs in the opposite direction: your system initiates a payout to a customer or worker's phone number. This is the flow that powers our production payroll in MkulimaOS. Payroll totals are calculated from attendance and piece-rate records, the B2C request is initiated with a generated originator conversation ID, and the result callback updates the worker's disbursement record. We enforce one-disbursement-per-payroll-period at the database level, so a network retry cannot result in a double payment. The Daraja API returns both synchronous acknowledgements and asynchronous result callbacks — our integrations handle both, rather than treating the acknowledgement as confirmation.

The hard part: callbacks, reconciliation, idempotency, and timeouts

This section is the reason most M-Pesa integrations break on go-live, and it is the part that most tutorials skip. Safaricom's callback delivery is eventually consistent, not guaranteed. Your callback endpoint can receive a notification twice, out of order, or not at all. An integration that processes callbacks naively will double-credit accounts on duplicate delivery and leave transactions unresolved when delivery fails. We approach this with a set of patterns we have proven in production. Every initiated transaction is assigned a unique merchant request ID before the API call is made. The callback handler checks that ID against a processed-transactions table before taking any action — if the ID is already there, the callback is acknowledged and discarded without re-processing. If a callback has not arrived within a configurable window, a background job queries the Daraja transaction status endpoint and reconciles the result directly. Timeouts on outbound API calls are handled explicitly: a request that times out is not assumed to have failed, because the payment may have been initiated on Safaricom's side before the connection dropped. The correct response is to query status — not to retry the initiation, which risks a double charge.

• Idempotency key stored before API call; callback handler checks before acting
• Duplicate callback detection via processed-transactions table
• Background reconciliation job for callbacks that never arrive
• Explicit timeout handling: status query, not blind retry
• Transaction state machine: pending → confirmed / failed / refunded

Sandbox to production: Daraja go-live, credentials, and integrating into your app

The Daraja sandbox and production environments use different credential sets, different base URLs, and occasionally different API behaviour. The go-live process requires submitting your integration for Safaricom's review, which involves documenting your use case, configuring your shortcode, and ensuring your callback URLs are publicly reachable and return the correct response format. We have done this process multiple times and can guide you through it or handle it end-to-end. For integrations into existing systems, we treat your codebase as the integration surface: we read your stack, identify where payment initiation and confirmation need to plug in, and write the integration layer to match your conventions rather than introducing a foreign pattern. For greenfield projects, we scaffold a clean service layer — Daraja client, transaction repository, reconciliation job — that is testable independently of the M-Pesa API itself, using Safaricom's sandbox for end-to-end verification. Everything we write is delivered with documentation, and you own it on delivery. There is no Spidey Labs dependency in your payment path.