---

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.
   • 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.
• Access documentation at https://www.community.nestict.com/dashboard.

---