Table of Contents

  1. Introduction

  2. Overview of Dolibarr’s Modular Architecture

  3. What is Stancer and Why Use It?

  4. Setting Up the Development Environment

  5. Understanding Dolibarr Module Structure

  6. Creating the Module Skeleton

  7. Configuring Module Properties and Dependencies

  8. Authenticating with the Stancer API

  9. Creating Payment Interfaces in Dolibarr

  10. Handling Payment Transactions

  11. Saving Transactions to the Database

  12. Adding Hooks and Triggers

  13. Integrating with Invoices and Orders

  14. Managing Payment Statuses

  15. Error Handling and Logging

  16. Testing and Debugging the Module

  17. Securing API Communications

  18. Translating and Localizing the Module

  19. Packaging and Distributing the Module

  20. Maintenance and Versioning

  21. Summary and Recommendations

1. Introduction

As digital payments become more integral to modern business operations, having seamless integration between ERP systems and payment gateways is crucial. Dolibarr ERP & CRM, being open source and modular, allows for custom integrations with third-party services. This article provides a step-by-step guide on how to build a custom payment module using the Stancer API for Dolibarr.

2. Overview of Dolibarr’s Modular Architecture

Dolibarr uses a modular design that allows developers to create and plug in new features. Modules are isolated directories that include PHP files, templates, configuration scripts, and hooks. A well-structured module can be activated or deactivated without affecting the core system.

3. What is Stancer and Why Use It?

Stancer is a payment platform that offers RESTful APIs to accept and manage credit card and SEPA transactions. It’s designed for developers and supports recurring payments, refunds, and fraud detection.

Reasons to integrate Stancer with Dolibarr include:

  • Easy API interface

  • Competitive pricing

  • Real-time processing

  • Compatibility with French and European markets

4. Setting Up the Development Environment

To begin:

  • Install Dolibarr locally or on a development server

  • Set up Apache, MySQL, and PHP (preferably via a LAMP/WAMP stack)

  • Clone the Dolibarr GitHub repository for module reference

  • Register for a Stancer developer account to obtain API credentials

5. Understanding Dolibarr Module Structure

A Dolibarr module generally includes:

  • modMyModule.class.php: Module descriptor

  • /core/ for configuration files and helpers

  • /admin/ for configuration UI

  • /class/ for business logic classes

  • /scripts/ for CRON jobs or CLI tools

  • /tpl/ for HTML templates

6. Creating the Module Skeleton

Start by duplicating a basic module and renaming all occurrences:

  • Replace names with stancerpayment

  • Update class names and file references

7. Configuring Module Properties and Dependencies

Edit modStancerPayment.class.php:

  • Set name, version, description

  • Declare dependencies (e.g., invoice, payment)

  • Define tabs, permissions, and setup values

Register the module in Dolibarr’s admin panel.

8. Authenticating with the Stancer API

Stancer uses basic HTTP authentication:

  • Store API key securely in the module config

  • Create a service class to handle HTTP requests

  • Use curl or Guzzle to manage communication

9. Creating Payment Interfaces in Dolibarr

Design payment forms and interfaces:

  • Add a "Pay with Stancer" button on invoices

  • Create a controller (/stancer/payment.php) to process requests

  • Use Dolibarr’s template engine to match UI design

10. Handling Payment Transactions

When user submits payment:

  • Collect invoice data and customer info

  • Initiate transaction via Stancer API

  • Handle success or failure responses

  • Update Dolibarr invoice accordingly

11. Saving Transactions to the Database

Create a custom SQL table (e.g., llx_stancer_transactions) to store:

  • Payment ID

  • Invoice ID

  • Amount

  • Status

  • Timestamp

Use Dolibarr’s DoliDB API to manage entries.

12. Adding Hooks and Triggers

Utilize Dolibarr’s hook manager to extend:

  • Invoice pages

  • Payment confirmation workflows

Example: Add a hook to display payment status on invoice detail view.

13. Integrating with Invoices and Orders

Ensure the module links with invoice status:

  • Update invoice to paid if transaction successful

  • Generate payment receipt

  • Add reference to Stancer payment ID

14. Managing Payment Statuses

Create logic to sync or query Stancer for status:

  • Success

  • Pending

  • Failed

  • Refunded

Provide an admin view to review and manage transactions.

15. Error Handling and Logging

Implement detailed error messages and logging:

  • Display user-friendly errors on UI

  • Write errors to Dolibarr logs or a custom log file

  • Handle timeouts, invalid API keys, and input validation

16. Testing and Debugging the Module

Perform unit and integration tests:

  • Simulate various transaction outcomes

  • Use Stancer’s sandbox environment

  • Validate database entries

  • Use XDebug or PHP error logs

17. Securing API Communications

  • Use HTTPS for all API calls

  • Never expose credentials in logs

  • Sanitize all inputs before sending

  • Secure the configuration screen with admin permissions

18. Translating and Localizing the Module

Support multiple languages:

  • Use langs->trans() for strings

  • Provide .lang files under /langs/

  • Translate admin interfaces and error messages

19. Packaging and Distributing the Module

  • Zip the module folder (stancerpayment/)

  • Provide a README with installation instructions

  • Optionally submit to Dolistore for public availability

20. Maintenance and Versioning

Follow semantic versioning:

  • Use changelogs to track updates

  • Maintain compatibility with new Dolibarr versions

  • Monitor Stancer API changes regularly

21. Summary and Recommendations

Developing a payment module for Dolibarr using the Stancer API is a valuable investment for businesses seeking automated payment workflows. By leveraging Dolibarr’s modular system and Stancer’s robust API, developers can build a seamless, secure, and user-friendly experience for both administrators and clients.

Careful attention to authentication, permission management, and UI consistency ensures long-term success and easy maintenance. Following best practices for security, translation, and documentation will make the module more adaptable and professional.

Whether for internal use or commercial distribution, this integration demonstrates the flexibility and extensibility of Dolibarr as a complete ERP solution.