### Dolipesa 1.0.1 - M-Pesa Payment Module for Dolibarr ERP Release Date: March 30, 2025
Version: 1.0.1 (Initial Stable Release)
Developed by: [Your Name/Organization]
License: GNU General Public License v3.0 (aligning with Dolibarr’s open-source licensing) #### Overview Dolipesa 1.0.1 is a custom payment module designed to integrate M-Pesa, a popular mobile payment service in East Africa, with Dolibarr ERP/CRM. This initial release enables businesses using Dolibarr to accept payments from customers via M-Pesa for invoices, orders, and other transactions directly within the ERP system. The module leverages Dolibarr’s native online payment architecture and M-Pesa’s API to provide a seamless payment experience. #### Features 1. M-Pesa Payment Gateway Integration - Supports M-Pesa’s STK Push API for prompting customers to enter their PIN on their mobile devices. - Processes payments for customer invoices and sales orders created in Dolibarr. - Compatible with Kenyan Shilling (KES) as the primary currency (expandable in future releases). 2. Payment Confirmation - Real-time transaction verification using M-Pesa’s callback/result URL. - Updates invoice/order status in Dolibarr (e.g., from "Draft" to "Paid") upon successful payment. 3. Basic Configuration - Admin interface to input M-Pesa API credentials (Consumer Key, Consumer Secret, Shortcode, Passkey). - Option to set a custom payment description visible to customers during STK Push. 4. Transaction Logging - Records M-Pesa transaction IDs and statuses in Dolibarr for reconciliation and auditing. 5. Public Payment Page - Integrates with Dolibarr’s /public/payment/newpayment.php endpoint to offer M-Pesa as a payment option. #### Requirements - Dolibarr Version: 19.0.* or higher (tested up to 20.0.0 as of March 30, 2025). - PHP Version: 7.4 or higher (compatible with Dolibarr’s requirements). - M-Pesa API Access: - Safaricom M-Pesa Daraja API credentials (Consumer Key, Consumer Secret, Shortcode, Passkey). - A registered callback URL hosted on your Dolibarr server. - Server: HTTPS-enabled web server (required for secure API communication). - Dependencies: PHP cURL extension for API requests. #### Installation Instructions 1. Download the Module - Obtain the dolipesa-1.0.1.zip file from [Your Repository/Dolistore Linkവ 2. Install the Module - Log in to your Dolibarr instance with an administrator account. - Navigate to Home > Setup > Modules > Deploy/Install External App/Module. - Upload the dolipesa-1.0.1.zip file and click Install. - If the upload fails due to hosting restrictions, manually extract the ZIP file into the /custom directory of your Dolibarr installation (e.g., /var/www/dolibarr/custom/dolipesa). 3. Activate the Module - Go to Home > Setup > Modules. - Locate "Dolipesa - M-Pesa Payment" in the list, click Activate, and configure settings if prompted. #### Configuration 1. Obtain M-Pesa API Credentials - Register for Safaricom’s Daraja API at developer.safaricom.co.ke. - Generate a Consumer Key, Consumer Secret, and Passkey. - Provide a callback URL (e.g., https://your-dolibarr-domain.com/custom/dolipesa/callback.php). 2. Set Up in Dolibarr - Navigate to Home > Setup > Modules > Dolipesa - M-Pesa Payment > Configure. - Enter your M-Pesa Shortcode, Consumer Key, Consumer Secret, Passkey, and Callback URL. - Save the settings. 3. Test the Integration - Create a test invoice in Dolibarr. - Access the public payment page (e.g., https://your-dolibarr-domain.com/public/payment/newpayment.php?source=invoice&ref=INVREF). - Select "M-Pesa" as the payment method, enter a test phone number, and confirm the STK Push on a test M-Pesa account. #### Usage - For Customers: - On the Dolibarr payment page, choose "M-Pesa," enter your phone number, and approve the STK Push notification on your phone. - For Admins: - Monitor transactions under Bank & Cash > M-Pesa Transactions (new tab added by the module). #### Technical Notes - Hook Implementation: The module uses Dolibarr’s "newpayment" context hooks to integrate with /public/payment/newpayment.php, setting required session variables (TRANSACTIONID, FinalPaymentAmt, currencyCodeType) as per Dolibarr’s online payment system documentation. - API Calls: Utilizes M-Pesa’s OAuth token generation and STK Push endpoints (e.g., https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest for testing). - Security: Ensures HTTPS for all API interactions; API credentials are stored encrypted in Dolibarr’s database. #### Known Limitations (1.0.1) - Supports only single-currency transactions (KES). - Basic error handling; no retry mechanism for failed STK Push attempts. - Sandbox mode only (production requires Safaricom approval). #### Changelog - 1.0.1 (March 30, 2025): - Fixed minor bug in callback URL validation. - Initial stable release after 1.0.0 beta testing. #### Future Enhancements (Planned for 1.1.0) - Multi-currency support with automatic conversion. - Retry logic for failed transactions. - Customer notification emails upon payment success. #### Support - Report issues or request features at support@nestict.com. - Documentation available at https://www.community.nestict.com/dashboard.