M-Pesa Daraja, Stripe & Multi-Gateway Payment Integration: Preventing Lost Transactions and Failed Webhooks

The Hidden Revenue Cost of Brittle Payment Integrations

Every week, growing e-commerce platforms, SaaS companies, utilities, and logistics operators lose thousands of dollars—and angry customers—to the same failure mode: a customer enters their M-Pesa PIN on an STK Push prompt (or completes a 3D-Secure card payment on Stripe/Paystack), receives an SMS confirming their money was deducted, and yet your application stays stuck on "Payment Pending."

Support tickets flood in, finance staff spend hours manually cross-checking M-Pesa portal CSVs against database orders, and worst of all, some systems allow a frustrated user or staff member to click "Retry" without idempotency locks—resulting in duplicate disbursements or double-credited wallets. At devManue Engineering, we replace brittle payment plugins with hardened, zero-loss payment orchestration layers.

1. Why Standard Payment Tutorials Fail in Production

Most developers build payment integrations assuming the happy path: send request $\rightarrow$ receive webhook 3 seconds later $\rightarrow$ mark order as paid. In real-world production across Safaricom Daraja, Airtel Money, Stripe, and Paystack, four edge cases happen daily:

2. Production Architecture: Webhook Ingestion + Active Polling Fallback

A resilient payment gateway integration never trusts a webhook to do heavy processing synchronously, and never assumes a webhook will arrive at all. Here is our two-tier pattern in Django:

1. Sub-50ms Raw Webhook Vault: When Safaricom Daraja or Stripe sends a callback, the HTTP view immediately writes the raw JSON payload to an immutable WebhookEvent table, returns 200 OK in under 30 milliseconds (preventing gateway timeouts), and dispatches a Celery worker task.
2. Active State Reconciliation: If an STK Push (`CheckoutRequestID`) has not transitioned out of INITIATED within 45 seconds, a background task proactively queries the gateway's query endpoint (`stkpushquery/v1/query`) to pull the authoritative result.

# Production Idempotent M-Pesa Daraja Callback & Fallback Reconciler
from django.db import IntegrityError, transaction
from django.utils import timezone
from .models import PaymentIntent, WalletLedger

@transaction.atomic
def settle_mpesa_transaction(checkout_request_id: str, mpesa_receipt: str, amount_paid: int) -> bool:
    """Guarantees exactly-once settlement even if webhook and active poller fire simultaneously."""
    intent = (
        PaymentIntent.objects.select_for_update()
        .filter(checkout_request_id=checkout_request_id)
        .first()
    )
    if not intent or intent.status == "SETTLED":
        return False  # Already settled idempotently

    if amount_paid < intent.expected_amount:
        intent.status = "PARTIAL_MISMATCH"
        intent.gateway_receipt = mpesa_receipt
        intent.save(update_fields=["status", "gateway_receipt", "updated_at"])
        return False

    intent.status = "SETTLED"
    intent.gateway_receipt = mpesa_receipt
    intent.settled_at = timezone.now()
    intent.save(update_fields=["status", "gateway_receipt", "settled_at", "updated_at"])

    # Database-level unique constraint on gateway_receipt prevents duplicate ledger credits
    WalletLedger.objects.create(
        customer_id=intent.customer_id,
        payment_intent=intent,
        gateway_receipt=mpesa_receipt,
        credit_amount=amount_paid,
    )
    return True

Losing revenue or staff hours to payment reconciliation bugs? Review our High-Throughput API & Payment Engineering Services or book a 30-minute Payment Architecture Discovery Call.

3. Frequently Asked Questions (FAQ)