---

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 support@nestict.com.
• Documentation available at https://www.community.nestict.com/dashboard.

---

This outlines a realistic first release for an M-Pesa payment module tailored to Dolibarr. It assumes familiarity with Dolibarr’s module development framework and M-Pesa’s Daraja API. If you’re looking to actually build this, you’d need to:

1. Set up a Dolibarr development environment.
2. Use the Module Builder in Dolibarr (or manually code in PHP) to create the module structure.
3. Implement M-Pesa API calls using PHP cURL or a library like Guzzle.
4. Test thoroughly with Safaricom’s sandbox.

Would you like me to expand on any specific section, such as code snippets or deeper integration details? Let me know!