Safaricom Daraja 3.0 & M-Pesa Ratiba: The Developer’s Playbook for Recurring Billing and STK Push

The Evolution of M-Pesa Integration in Kenya

For years, software developers building e-commerce checkouts and subscription SaaS apps in Kenya wrestled with the original Daraja 2.0 API. Dropped webhooks, cryptic response codes like [1032] Request cancelled by user, and the inability to automate recurring subscriptions forced businesses to rely on awkward manual monthly STK prompt pushes.

With the release of Daraja 3.0 and the groundbreaking M-Pesa Ratiba (Standing Orders API), Safaricom has modernized its developer platform. You can now build true recurring subscription billing—for gym memberships, SaaS software, insurance premiums, and utility retainers—directly debited from the customer's M-Pesa wallet on a predetermined schedule.

Understanding M-Pesa Ratiba: Automated Recurring Debits

Unlike standard Lipa na M-Pesa Online (STK Push) which requires the user to input their PIN for every single transaction, M-Pesa Ratiba allows the customer to authorize a continuous payment mandate once. The schedule can be daily, weekly, monthly, or customized.

When the billing date arrives, Safaricom's core engine automatically executes the debit without sending a prompt to the customer's phone, provided the account has sufficient funds. This eliminates churn and transforms how recurring revenue businesses operate in Kenya.

Hardening Daraja Callbacks: Idempotency & Race Condition Defense

The single most dangerous vulnerability in Kenyan payment implementations is handling callback webhooks naively. Telco network latency can result in Safaricom retrying the same payment callback twice within a few hundred milliseconds. If your backend does not implement strict database transaction locking, a customer might receive double credit or trigger duplicate inventory dispatches.

// Production-grade idempotent M-Pesa callback handler in Laravel
public function handleMpesaCallback(Request $request)
{
    $content = json_decode($request->getContent(), true);
    $stkCallback = $content['Body']['stkCallback'] ?? null;
    
    if (!$stkCallback || $stkCallback['ResultCode'] !== 0) {
        Log::warning('M-Pesa Payment Failed or Cancelled', ['payload' => $stkCallback]);
        return response()->json(['ResultCode' => 0, 'ResultDesc' => 'Accepted']);
    }

    $meta = collect($stkCallback['CallbackMetadata']['Item'])->pluck('Value', 'Name');
    $receiptNumber = $meta['MpesaReceiptNumber'];
    $amount = $meta['Amount'];

    // Atomic Database Transaction with Pessimistic Locking
    return DB::transaction(function () use ($receiptNumber, $amount) {
        $existing = Payment::where('mpesa_receipt', $receiptNumber)->lockForUpdate()->first();
        if ($existing) {
            Log::info("Duplicate M-Pesa callback ignored: {$receiptNumber}");
            return response()->json(['ResultCode' => 0, 'ResultDesc' => 'Already Processed']);
        }

        Payment::create([
            'mpesa_receipt' => $receiptNumber,
            'amount' => $amount,
            'status' => 'COMPLETED',
            'paid_at' => now(),
        ]);

        return response()->json(['ResultCode' => 0, 'ResultDesc' => 'Success']);
    });
}

The Next Frontier: WhatsApp Conversational Commerce

Leading Kenyan retail and tech brands are pairing Daraja 3.0 directly with the WhatsApp Business Cloud API. Instead of sending users through bloated website checkout flows where drop-off rates exceed 70%, customers browse catalog items, ask questions, receive quotes, and trigger instant M-Pesa STK prompts all within a single WhatsApp conversation thread.