Skip to main content

MPesa Payment Integration

Implementation Overview​

We've integrated MPesa as our primary payment processing system with the following architecture:

Backend Implementation​

  • MPesa Utility Class: Located at utils/mpesa.py
    • Handles all MPesa API interactions
    • Provides methods for:
      • Payment initialization
      • Transaction status checks
      • Payment verification

Legacy Webhook Handling​

  • PHP Endpoint: /hj/c.php
    • Acts as a bridge for legacy webhook notifications
    • Forwards MPesa payment notifications to our main system
    • Maintains detailed logs of all transactions

Key Components​

The MPesa Utility Class​

# Sample structure of mpesa.py
class LNMOMakeCalls:
    ...

PHP Bridge Endpoint​

The /hj/c.php script serves as: Check Github for code

  1. Webhook Receiver - Captures all MPesa payment notifications
  2. Data Logger - Maintains complete transaction records in:
    • received_data.txt (raw incoming data)
    • response_log.txt (forwarding results)
  3. Protocol Bridge - Forwards data to our modern backend system

Implementation Challenges & Solutions​

  1. Legacy System Constraints

    • Couldn't modify original webhook destination
    • Solution: Created PHP bridge to forward requests

  2. Data Reliability

    • Implemented dual logging (receipt and forwarding)
    • Added comprehensive error tracking

  3. Time Synchronization

    • Originally had timezone issues
    • Solution: Standardized on Africa/Nairobi time

Best Practices Implemented​

  1. Comprehensive Logging

    • All transactions logged with timestamps
    • Both successful and failed attempts recorded

  2. Error Handling

    • JSON validation before processing
    • HTTP status code tracking
    • cURL error capturing

  3. Data Integrity

    • Raw data preservation
    • Response verification

Future Improvements​

  1. Replace PHP bridge with direct webhook support
  2. Add transaction reconciliation process
  3. Implement automatic retry mechanism for failed forwards
  4. Enhance security with request validation

Would you like me to elaborate on any specific aspect of the implementation?