diff --git a/README.md b/README.md index e840fe0..baced3b 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,100 @@ + + --- -### 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) +**License:** GNU General Public License v3.0 (consistent with Dolibarr’s open-source framework) #### 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. +Dolipesa 1.0.1 is a tailored payment module that seamlessly integrates M-Pesa, a widely used mobile payment platform in East Africa, with Dolibarr ERP/CRM. This first release empowers businesses to accept M-Pesa payments for invoices, orders, and other transactions directly within Dolibarr, utilizing its native payment infrastructure and M-Pesa’s API for a streamlined 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). + - Employs M-Pesa’s STK Push API to prompt customers for PIN entry on their mobile devices. + - Facilitates payments for invoices and sales orders within Dolibarr. + - Supports Kenyan Shilling (KES), with plans for broader currency compatibility in future updates. 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. + - Verifies transactions in real-time via M-Pesa’s callback/result URL. + - Automatically updates Dolibarr invoice/order statuses (e.g., "Draft" to "Paid") upon payment success. 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. + - Offers an admin panel to input M-Pesa API credentials (Consumer Key, Consumer Secret, Shortcode, Passkey). + - Allows customization of the payment description shown to customers during STK Push. 4. **Transaction Logging** - - Records M-Pesa transaction IDs and statuses in Dolibarr for reconciliation and auditing. + - Logs M-Pesa transaction IDs and statuses in Dolibarr for easy reconciliation and tracking. 5. **Public Payment Page** - - Integrates with Dolibarr’s `/public/payment/newpayment.php` endpoint to offer M-Pesa as a payment option. + - Enhances Dolibarr’s `/public/payment/newpayment.php` endpoint to include 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). +- **PHP Version:** 7.4 or later (aligned with Dolibarr’s specifications). +- **M-Pesa API Access:** + - Safaricom 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. +- **Server:** HTTPS-enabled (mandatory for secure API communication). +- **Dependencies:** PHP cURL extension for API interactions. #### Installation Instructions 1. **Download the Module** - - Obtain the `dolipesa-1.0.1.zip` file from [Your Repository/Dolistore Linkവ + - Get 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`). + - Log into Dolibarr as an administrator. + - Go to **Home > Setup > Modules > Deploy/Install External App/Module**. + - Upload `dolipesa-1.0.1.zip` and click **Install**. + - If upload issues occur, manually unzip the file into `/custom` (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. + - Navigate to **Home > Setup > Modules**. + - Find "Dolipesa - M-Pesa Payment," click **Activate**, and adjust settings as needed. #### 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`). + - Sign up at [developer.safaricom.co.ke](https://developer.safaricom.co.ke). + - Acquire a Consumer Key, Consumer Secret, and Passkey. + - Set 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. + - Go to **Home > Setup > Modules > Dolipesa - M-Pesa Payment > Configure**. + - Input your Shortcode, Consumer Key, Consumer Secret, Passkey, and Callback URL. + - Save your 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. + - Generate a test invoice in Dolibarr. + - Visit the public payment page (e.g., `https://your-dolibarr-domain.com/public/payment/newpayment.php?source=invoice&ref=INVREF`). + - Choose "M-Pesa," enter a test phone number, and confirm the STK Push in 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). +- **For Customers:** + - Select "M-Pesa" on the payment page, input your phone number, and approve the STK Push notification. +- **For Admins:** + - Track transactions via **Bank & Cash > M-Pesa Transactions** (a new module-added tab). #### 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. +- **Hook Implementation:** Integrates with Dolibarr’s "newpayment" hooks at `/public/payment/newpayment.php`, setting session variables (`TRANSACTIONID`, `FinalPaymentAmt`, `currencyCodeType`) per Dolibarr’s payment documentation. +- **API Calls:** Leverages M-Pesa’s OAuth token and STK Push endpoints (e.g., `https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest` for testing). +- **Security:** Enforces HTTPS for API calls; encrypts API credentials 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. +- Limited to KES transactions. +- Basic error handling without retry 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. + - Resolved callback URL validation issue. + - Marked as the initial stable release post-1.0.0 beta. #### Future Enhancements (Planned for 1.1.0) -- Multi-currency support with automatic conversion. -- Retry logic for failed transactions. -- Customer notification emails upon payment success. +- Multi-currency support with conversion. +- Retry mechanism for failed transactions. +- Payment success email notifications for customers. #### Support -- Report issues or request features at support@nestict.com. -- Documentation available at https://www.community.nestict.com/dashboard. \ No newline at end of file +- Submit issues or feature requests to [support@nestict.com](mailto:support@nestict.com). +- Access documentation at [https://www.community.nestict.com/dashboard](https://www.community.nestict.com/dashboard). + +--- +