diff --git a/README.md b/README.md index 252d4a2..9727054 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,110 @@ -# Dolibarr M-Pesa Payment Module -## Overview -The M-Pesa Payment Module for Dolibarr enables seamless integration with M-Pesa, allowing businesses to accept payments directly from customers. +--- -## Features -- Generate payment URLs for invoices. -- Real-time payment processing via M-Pesa. -- Automatic payment confirmation and transaction recording. +### 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) -## Installation -1. Download the module ZIP package. -2. Extract and upload the contents to Dolibarr's custom modules directory (e.g., /htdocs/custom/mpesapay). -3. Go to **Home > Setup > Modules** and activate the "M-Pesa Payment Module". +#### 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. -## Configuration -1. Navigate to **M-Pesa Module Configuration** in Dolibarr. -2. Enter your M-Pesa Paybill Number and Passkey. +#### 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). -## Usage -1. Generate an invoice in Dolibarr. -2. Click on "Pay with M-Pesa" to initiate payment. -3. Customers complete payment via M-Pesa and the module confirms the transaction. +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. -## Support -For inquiries, contact [NESTICT INFOTECH](https://www.nestict.com). +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. -## License -This module is licensed under GPLv3. +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](https://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. + +--- + +This outlines a realistic first release for an M-Pesa payment module tailored to Dolibarr. It assumes familiarity with Dolibarr’s module development framework and M-Pesa’s Daraja API. If you’re looking to actually build this, you’d need to: +1. Set up a Dolibarr development environment. +2. Use the Module Builder in Dolibarr (or manually code in PHP) to create the module structure. +3. Implement M-Pesa API calls using PHP cURL or a library like Guzzle. +4. Test thoroughly with Safaricom’s sandbox. + +Would you like me to expand on any specific section, such as code snippets or deeper integration details? Let me know! \ No newline at end of file