DoliPesa/README.md

---

**License:** GNU General Public License v3.0 (consistent with Dolibarr’s open-source framework)

#### Overview
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**
   - 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**
   - 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**
   - 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**
   - Logs M-Pesa transaction IDs and statuses in Dolibarr for easy reconciliation and tracking.

5. **Public Payment Page**
   - 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 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 (mandatory for secure API communication).
- **Dependencies:** PHP cURL extension for API interactions.

#### Installation Instructions
1. **Download the Module**
   - Get the `dolipesa-1.0.1.zip` file from [Your Repository/Dolistore Link].

2. **Install the Module**
   - 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**
   - Navigate to **Home > Setup > Modules**.
   - Find "Dolipesa - M-Pesa Payment," click **Activate**, and adjust settings as needed.

#### Configuration
1. **Obtain M-Pesa API Credentials**
   - 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**
   - 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**
   - 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:**
  - 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:** 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)
- 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):**
  - 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 conversion.
- Retry mechanism for failed transactions.
- Payment success email notifications for customers.

#### Support
- 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).

---