DoliPesa/README.md

---

### 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](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.