Update README.md
Signed-off-by: kevinowino869 <kevinowino869@www.codelab.nestict.africa>
This commit is contained in:
parent
dba8026684
commit
3a06133a8c
99
README.md
99
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).
|
||||
- **PHP Version:** 7.4 or later (aligned with Dolibarr’s specifications).
|
||||
- **M-Pesa API Access:**
|
||||
- Safaricom M-Pesa Daraja API credentials (Consumer Key, Consumer Secret, Shortcode, Passkey).
|
||||
- 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.
|
||||
- Select "M-Pesa" on the payment page, input your phone number, and approve the STK Push notification.
|
||||
- **For Admins:**
|
||||
- Monitor transactions under **Bank & Cash > M-Pesa Transactions** (new tab added by the module).
|
||||
- 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.
|
||||
- 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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user