Securing M-PESA Daraja API Callbacks: HMAC Verification, Idempotency Keys, and Replay Defense

The Real Threats to Payment Callbacks

Payment webhooks from telcos and aggregators operate over public internet endpoints. Without cryptographic signature validation, replay attack prevention, and database transaction locking, malicious actors can spoof payment confirmation payloads to credit accounts or release goods fraudulently.

Core Defenses Every Kenyan Developer Must Implement

1. IP Whitelisting & Gateway Filtering: Restrict callback endpoints to Safaricom's verified IP subnets at the web firewall or reverse proxy level.
2. Database Idempotency Locking: Use unique constraint indexes on MpesaReceiptNumber wrapped in DB::transaction() with pessimistic locking (lockForUpdate()).
3. Callback Verification via Query API: In high-value transactions, verify callback data by triggering an independent B2C/C2B transaction status query to Safaricom before final fulfillment.