agtic/DoliPesa
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 2 Wiki Activity
DoliPesa/README.md
kevinowino869 e18a23a492 Update README.md 
Signed-off-by: kevinowino869 <kevinowino869@www.codelab.nestict.africa>
2025-03-30 13:23:45 +02:00

6.0 KiB
Raw Blame History

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

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!