### 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.
- 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 [Your GitHub Repo/Support Email].
- Documentation available at [Your Website/Dolibarr Wiki].
kevinowino869 released this