| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Invoicing (account)
• Discuss (mail) • Contacts (contacts) |
| Community Apps Dependencies | Show |
| Lines of code | 511 |
| Technical Name |
payment_kopokopo_c2b |
| License | OPL-1 |
| Website | https://odoo.co.ke |
| Versions | 16.0 |
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Invoicing (account)
• Discuss (mail) • Contacts (contacts) |
| Community Apps Dependencies | Show |
| Lines of code | 511 |
| Technical Name |
payment_kopokopo_c2b |
| License | OPL-1 |
| Website | https://odoo.co.ke |
| Versions | 16.0 |
Payments • Automation
Kopo Kopo C2B Connector
Transform Kopo Kopo BuyGoods payments into automated Odoo account entries. Eliminates manual payment reconciliation with intelligent partner matching and comprehensive transaction tracking.
☁️ Compatibility
📸 Screenshots
Visual guide to Kopo Kopo C2B Connector functionality
Kopo Kopo Configuration
Configuration form with API credentials, webhook URLs, and subscription management.
Webhook Subscription
Success notification after subscribing to BuyGoods transaction webhooks.
🤖 Automated Processing
- 📡 /kopokopo/callback webhook handler
- 💳 Auto-creates and posts account payments
👥 Smart Partner Matching
- 🔍 Uses ke_phone_hashes for matching
- ➕ Creates new customers automatically
⚙️ Webhook Management
- ▶️ Subscribe/unsubscribe webhooks
- 🧪 Test webhook functionality
🔒 OAuth Integration
- 🔑 Secure API authentication
- 🖥️ Sandbox/production environments
🚀 Latest Release
2024-12-27- Initial release with MSISDN normalization and SHA-256 hashing.
- Partner fields with duplicate prevention and POS validation.
📅 Changelog
- ➕ Add Full automation workflows
- ⚡ Improve Performance & stability enhancements
📜 Licensing
License Type
OPL-1Redistribution
Not AllowedFull Policy
View Policy💬 Support & Contact
Kopo Kopo C2B Connector
Version: 16.0.1.0.0 Author: Metro Ict Limited Website: https://odoo.co.ke License: OPL-1
Overview
The Kopo Kopo C2B Connector is an Odoo module that enables seamless integration with Kopo Kopo's BuyGoods payment system. This module automatically receives, processes, and records customer-to-business (C2B) payments from Kopo Kopo webhooks, creating corresponding payment records in Odoo with automatic partner matching and reconciliation capabilities.
Features
Webhook Integration - Automatic webhook callback handling for Kopo Kopo BuyGoods transactions - Real-time payment processing and recording - Secure webhook verification with signature validation - Support for both sandbox and production environments
Payment Processing - Automatic creation of payment records from webhook data - Intelligent partner matching using phone number hashing - Auto-creation of new partners when not found - Automatic payment posting and journal entry creation - Transaction reference tracking and external ID mapping
Configuration Management - Easy-to-use configuration interface - OAuth token management for API authentication - Webhook subscription and unsubscription management - Test webhook functionality for validation - Support for multiple Till numbers (scope references)
Enhanced Payment Records - Extended payment model with Kopo Kopo-specific fields - Transaction reference and external ID tracking - Phone number and hash storage for reconciliation - Raw payload storage for audit and debugging - Received timestamp tracking
User Interface - Dedicated configuration menu in Accounting settings - Enhanced payment form views with Kopo Kopo fields - Tree and form views for configuration management - One-click webhook subscription/unsubscription
How It Works
1. Configuration Setup The module provides a configuration model (kopokopo.config) where you set up:
- Environment (Sandbox/Production)
- API credentials (Application ID and Client Secret)
- Journal for recording payments
- Callback URL for webhook notifications
- Till number (Scope Reference)
2. Webhook Subscription Once configured, the module can automatically subscribe to Kopo Kopo webhooks:
- Obtains OAuth token using client credentials
- Subscribes to buygoods_transaction_received events
- Stores subscription ID and webhook secret for verification
3. Payment Processing Flow When a customer makes a payment to your Till number:
- Kopo Kopo sends a webhook to your configured callback URL
- The module validates the webhook signature and payload
- Extracts transaction details (amount, reference, phone number, etc.)
- Searches for existing partner using phone number hash
- Creates new partner if not found
- Creates and posts payment record in Odoo
- Returns success/error response to Kopo Kopo
4. Partner Matching The module uses intelligent partner matching:
- Normalizes Kenyan phone numbers to standard format
- Creates secure hashes of phone numbers for privacy
- Matches payments to existing partners using phone hashes
- Auto-creates partners with transaction details when no match found
Installation
Prerequisites
- Odoo 18.0 or later
- payment_c2b_common_ke module (dependency)
- account module (standard Odoo module)
- Active Kopo Kopo BuyGoods account
- Public-facing server for webhook callbacks
Installation Steps
Download and Install
Place the module in your Odoo addons directory:
# Copy module to addons directory cp -r payment_kopokopo_c2b /path/to/odoo/addons/Update Module List
In Odoo, go to Apps → Update Apps List
Install Module
Search for "Kopo Kopo C2B Connector" and click Install
Install Dependencies
Ensure the following modules are installed: - payment_c2b_common_ke - account (usually pre-installed)
Configuration
Initial Setup
Navigate to Configuration
Go to: Accounting → Configuration → Kopo Kopo → Configuration
Create New Configuration
Click "Create" and fill in the required fields:
- Name: Descriptive name for your configuration
- Environment: Choose Sandbox for testing, Production for live
- Journal: Select the bank journal for recording payments
- Scope Reference: Your Till number from Kopo Kopo
- Application ID: Your Kopo Kopo Application ID
- Client Secret: Your Kopo Kopo Client Secret
- Callback URL: Your webhook endpoint (e.g., https://yourdomain.com/kopokopo/callback)
Subscribe to Webhooks
Click "Subscribe Webhook" to register your callback URL with Kopo Kopo
Webhook URL Setup
Your callback URL should be publicly accessible and point to: https://yourdomain.com/kopokopo/callback
Ensure your server: - Has SSL certificate (HTTPS required) - Can receive POST requests - Is not behind authentication for the callback endpoint
Testing
Test Webhook
Use the "Test Webhook" button to send a test transaction
Verify Configuration
Check that the webhook subscription was successful and secret was retrieved
Monitor Logs
Check Odoo logs for any webhook processing errors
Usage
Daily Operations
Viewing Payments - Go to Accounting → Customers → Payments - Kopo Kopo payments will have additional fields populated - Use filters to view only Kopo Kopo transactions
Partner Management - Partners are automatically created from transaction data - Phone numbers are normalized and hashed for matching - Manual partner assignment available if needed
Reconciliation - Payments are automatically posted upon creation - Manual reconciliation with invoices available - Use the "Un-reconciled by Kopokopo" field to track status
Monitoring - Check webhook registration status in configuration - Monitor payment creation in real-time - Review raw payloads for debugging
Troubleshooting
Common Issues
- Webhook Not Receiving Data - Verify callback URL is publicly accessible - Check SSL certificate validity - Ensure no firewall blocking requests - Verify Till number in scope reference
- Authentication Errors - Verify API credentials are correct - Check environment setting (sandbox vs production) - Ensure OAuth token generation is working
- Payment Creation Failures - Check journal configuration - Verify currency settings - Review Odoo logs for detailed error messages
- Partner Matching Issues - Verify phone number normalization - Check hash generation for phone numbers - Review partner creation logic
Log Monitoring Enable debug logging for detailed webhook processing information:
_logger = logging.getLogger(__name__) # Check logs in Odoo for webhook processing details
Support
For technical support and questions:
- Website: https://odoo.co.ke
- Author: Metro Ict Limited
- Module Version: 16.0.1.0.0
Documentation - Kopo Kopo API Documentation: https://app.kopokopo.com/documentation - 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 - Webhook callback handling - Payment processing and posting - Partner matching and creation - Configuration management interface - Webhook subscription management - Test webhook functionality
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module