101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
|
||
|
||
---
|
||
|
||
**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).
|
||
|
||
---
|
||
|