Overview

The M-Pesa C2B Connector is a comprehensive Odoo module that seamlessly integrates Safaricom M-Pesa PayBill and BuyGoods payments into your Odoo accounting system. This module automates the entire customer-to-business (C2B) payment workflow, from webhook reception to payment reconciliation, eliminating manual data entry and reducing accounting errors.

Features

Webhook Integration - Automatic C2B webhook callback handling at /callback/c2b - Real-time payment processing and recording - Support for both PayBill and BuyGoods transactions - Comprehensive payload validation and error handling - Support for both sandbox and production environments

Payment Processing - Automatic creation of payment records from M-Pesa webhooks - Intelligent partner matching using phone number hashing - Auto-creation of new partners with customer names from M-Pesa data - Automatic payment posting and journal entry creation - Transaction reference tracking and metadata storage

Daraja API Integration - Full integration with Safaricom's Daraja API - OAuth token management for secure API authentication - C2B URL registration for webhook endpoints - Transaction simulation for testing - Support for multiple business short codes

Enhanced Payment Records - Extended payment model with M-Pesa-specific fields - Complete transaction metadata storage (TransID, MSISDN, etc.) - Customer name tracking (FirstName, MiddleName, LastName) - Bill reference number and invoice tracking - Raw payload storage for audit and debugging - Transaction timestamp preservation

Reconciliation Tools - Dedicated reconciliation wizard for unmatched payments - Manual partner assignment capabilities - Bulk payment processing and reconciliation - Auto-reconciliation status tracking - Phone number hash updates for future matching

Configuration Management - Easy-to-use configuration interface in Accounting settings - Environment switching (Sandbox/Production) - Multiple business short code support - Journal assignment for payment recording - Webhook URL configuration and testing

How It Works

1. Configuration Setup The module provides a configuration model (mpesa.paybill.config) where you set up:

• Environment (Sandbox/Production)
• Business Short Code (PayBill number)
• Till Number (for BuyGoods)
• Daraja API credentials (Consumer Key and Secret)
• Journal for recording payments
• Callback URL for webhook notifications

2. Daraja API Registration Once configured, the module can register your webhook URLs with Safaricom:

• Obtains OAuth token using consumer credentials
• Registers Confirmation and Validation URLs
• Stores registration status for monitoring
• Enables webhook reception from M-Pesa

3. Payment Processing Flow When a customer makes an M-Pesa payment to your PayBill/Till:

1. Safaricom sends a webhook to your configured callback URL
2. The module validates the webhook payload and required fields
3. Extracts transaction details (amount, phone number, reference, etc.)
4. Normalizes and hashes the customer's phone number
5. Searches for existing partner using phone number hash
6. Creates new partner with customer names if not found
7. Creates and posts payment record in Odoo
8. Returns success/error response to Safaricom

4. Partner Matching The module uses intelligent partner matching:

• Normalizes Kenyan phone numbers to standard format (+254...)
• Creates secure hashes of phone numbers for privacy
• Matches payments to existing partners using phone hashes
• Falls back to legacy hash formats for backward compatibility
• Auto-creates partners with full names from M-Pesa data

5. Reconciliation Workflow For unmatched or disputed payments:

• Use the reconciliation wizard to manually assign partners
• Bulk process multiple unreconciled payments
• Update phone hashes for future automatic matching
• Track reconciliation status and history

Installation

Configuration

Usage

Troubleshooting

Common Issues

1. Webhook Not Receiving Data - Verify callback URL is publicly accessible - Check SSL certificate validity - Ensure no firewall blocking Safaricom IPs - Verify business short code matches PayBill number
2. Daraja API Errors - Verify Consumer Key and Secret are correct - Check environment setting (sandbox vs production) - Ensure API credentials are active - Review registration status messages
3. Payment Creation Failures - Check journal configuration and permissions - Verify currency settings match KES - Review Odoo logs for detailed error messages - Ensure required fields are present in webhook
4. Partner Matching Issues - Verify phone number normalization - Check hash generation for phone numbers - Review partner creation logic - Use reconciliation wizard for manual assignment

Webhook Payload Validation The module validates these required fields: - TransID (Transaction ID) - TransAmount (Amount) - MSISDN (Phone number) - TransTime (Transaction timestamp) - BusinessShortCode (PayBill/Till number)

Log Monitoring Enable debug logging for detailed webhook processing:

_logger = logging.getLogger(__name__)
# Check logs in Odoo for C2B processing details

API Reference

Webhook Endpoint - URL: /callback/c2b - Method: POST - Content-Type: application/json - Authentication: None (public endpoint)

Expected Payload Format:

{
  "TransactionType": "PayBill",
  "TransID": "NLJ3H6KZ8A",
  "TransTime": "20250515123045",
  "TransAmount": "2500.00",
  "BusinessShortCode": "174379",
  "BillRefNumber": "TEST1234",
  "MSISDN": "254716680977",
  "FirstName": "Jane",
  "MiddleName": "M.",
  "LastName": "Doe"
}

Response Codes: - {"ResultCode": "0", "ResultDesc": "Accepted"} - Success - {"ResultCode": "C2B00011", "ResultDesc": "Invalid JSON"} - JSON parsing error - {"ResultCode": "C2B00012", "ResultDesc": "Missing required fields"} - Validation error

Support

For technical support and questions:

• Website: https://odoo.co.ke
• Email: support@odoo.co.ke
• Phone: +254739444447
• Author: Metro Ict Limited
• Module Version: 16.0.1.0.0

Documentation - Safaricom Daraja API: https://developer.safaricom.co.ke - Odoo Payment Documentation: https://www.odoo.com/documentation/

License

This module is licensed under OPL-1 (Odoo Proprietary License v1.0).

Changelog

Version 16.0.1.0.0 - Initial release for Odoo 18.0 - Full C2B webhook integration - Daraja API integration - Payment processing and posting - Partner matching and creation - Reconciliation wizard - Configuration management interface - Testing and simulation tools - Comprehensive M-Pesa metadata tracking