MSISDN Normalization

• Automatic Phone Number Standardization: Converts various Kenyan phone number formats to the standard international format (254XXXXXXXXX)
• Multiple Format Support: Handles local formats (07XXXXXXXX, 7XXXXXXXX) and international format (254XXXXXXXXX)
• Validation: Ensures only valid Kenyan mobile numbers are processed

Phone Number Hashing

• SHA-256 Encryption: Generates secure hashes of normalized phone numbers for privacy and security
• Duplicate Prevention: Prevents creation of duplicate contacts with the same phone number
• Legacy Compatibility: Maintains backward compatibility with existing M-Pesa phone hash fields

Enhanced Partner Management

• Alternate Contact Field: Additional contact field for partners
• Automatic Hash Updates: Phone hashes are automatically updated when contact information changes
• Duplicate Detection: Real-time validation prevents duplicate phone numbers across contacts
• Migration Support: Seamless migration from legacy M-Pesa hash fields to neutral phone hash fields

Point of Sale Integration

• POS Phone Validation: JavaScript validation for phone numbers in Point of Sale interface
• Real-time Feedback: Immediate validation feedback during data entry

Phone Number Processing Flow

1. Input Processing: When a phone number is entered in any of the contact fields (phone, mobile, alternate_contact)
2. Normalization: The number is processed through the normalization function:
   • Removes all non-digit characters
   • Converts local format (07XXXXXXXX) to international (254XXXXXXXXX)
   • Converts short format (7XXXXXXXX) to international (254XXXXXXXXX)
   • Validates the final format is exactly 12 digits starting with 254
3. Hashing: Normalized numbers are hashed using SHA-256 for security
4. Storage: Hashes are stored in the ke_phone_hashes field as comma-separated values
5. Validation: System checks for duplicates before saving

Data Flow Example

Input: "0712345678"
↓ Normalization
Output: "254712345678"
↓ Hashing (SHA-256)
Output: "a1b2c3d4e5f6..." (64-character hash)
↓ Storage
Field: ke_phone_hashes = "a1b2c3d4e5f6..."

Duplicate Prevention

The module implements robust duplicate prevention:

• Create Operations: Checks for existing hashes before creating new partners
• Update Operations: Validates against existing partners (excluding current record)
• Real-time Validation: Immediate feedback during data entry
• Error Messages: Clear error messages indicating which contact has the duplicate number

Installation

1. Copy Module: Place the payment_c2b_common_ke folder in your Odoo custom addons directory
2. Update Apps List: Go to Apps → Update Apps List
3. Install Module: Search for "KE C2B Common" and click Install

Configuration

No additional configuration is required. The module works automatically once installed.

Usage

Dependencies

• base: Core Odoo functionality
• contacts: Contact management
• account: Accounting module

Database Fields

res.partner Model Extensions:

• alternate_contact (Char): Additional contact field
• ke_phone_hashes (Char): Comma-separated SHA-256 hashes of normalized phone numbers
• mpesa_phone_hashes (Char): Legacy alias field for backward compatibility

SQL Constraints:

• phone_or_mobile_required: Ensures at least one phone number is provided

API Reference

Utility Functions:

# Normalize a Kenyan phone number
from odoo.addons.payment_c2b_common_ke.utils import normalize_kenyan_number
normalized = normalize_kenyan_number("0712345678")  # Returns "254712345678"

# Hash a normalized number
from odoo.addons.payment_c2b_common_ke.utils import hash_kenyan_number
hashed = hash_kenyan_number("254712345678")  # Returns SHA-256 hash

Partner Methods:

# Update phone hashes for a partner
partner._update_phone_hashes(msisdn="254712345678", alternate="254722345678")

Legacy Support

The module maintains full backward compatibility with existing M-Pesa integrations:

• Field Mapping: mpesa_phone_hashes field automatically syncs with ke_phone_hashes
• Data Migration: Post-installation hook migrates existing M-Pesa hash data
• API Compatibility: Existing code using M-Pesa fields continues to work

Migration Process

During installation, the module automatically:

1. Identifies Legacy Data: Finds partners with mpesa_phone_hashes but no ke_phone_hashes
2. Copies Data: Transfers hash data to the new neutral field
3. Maintains Sync: Keeps both fields synchronized for compatibility

Common Issues

Phone Number Not Accepted

• Ensure the number is a valid Kenyan mobile number
• Check that the number has 9-10 digits (excluding country code)
• Verify the number starts with 7 (after removing country code)

Duplicate Error Messages

• Check if the phone number already exists in another contact
• Use the search function to find the existing contact
• Consider if this is the same person with multiple records

Hash Field Not Updating

• Ensure you're saving the record after making changes
• Check that the phone number format is valid
• Verify the module is properly installed and activated

Point of Sale Validation Issues

• Clear browser cache and reload the POS interface
• Ensure the module assets are properly loaded
• Check browser console for JavaScript errors

Performance Considerations

• Hash Generation: SHA-256 hashing is computationally efficient
• Duplicate Checking: Database queries are optimized with proper indexing
• Batch Operations: Large data imports should be done in batches