Table of Contents

  1. Introduction

  2. What is Stancer and Why Integrate It?

  3. Objectives of the Module

  4. Understanding Dolibarr Module Architecture

  5. Development Environment Setup

  6. Authentication and Stancer API Access

  7. Building the Stancer Module

    • File Structure

    • Key Configuration Files

    • Payment Hook Integration

  8. Handling Transactions: Payments and Webhooks

  9. Testing and Debugging Stancer Integration

  10. User Interface and UX Considerations

  11. Real-World Integration Challenges and Lessons Learned

  12. Security and Compliance in Payment Modules

  13. Tips for Deployment and Maintenance

  14. Community Contribution and Future Enhancements

  15. Conclusion

1. Introduction

Dolibarr ERP/CRM is a powerful open-source platform used by businesses to manage sales, accounting, projects, and more. As online transactions become the norm, integrating reliable and modern payment gateways is essential. One such gateway is Stancer, a payment service designed for simplicity, transparency, and developer-friendly APIs. This article details the journey of developing and integrating a Stancer payment module into Dolibarr, including design choices, technical hurdles, and best practices.

2. What is Stancer and Why Integrate It?

Stancer is a French payment processor offering competitive transaction fees, a straightforward API, and services such as card payments, SEPA direct debits, and recurring billing. Key reasons for choosing Stancer include:

  • Transparent pricing

  • Developer-focused RESTful API

  • Compliance with European regulations (PSD2, 3DSecure)

  • Support for both single and recurring payments

Integrating Stancer into Dolibarr opens the door for users to manage payments directly from their ERP system, automate customer billing, and reduce manual processing.

3. Objectives of the Module

The main goals when designing the Stancer module for Dolibarr were:

  • Seamless integration into Dolibarr’s invoice and payment workflows

  • Real-time transaction processing and status updates

  • Support for one-time and recurring payments

  • Secure handling of sensitive payment data

  • Easy installation and configuration for non-technical users

4. Understanding Dolibarr Module Architecture

Before developing any module, understanding Dolibarr’s modular structure is crucial. Key elements include:

  • Module descriptor files (modStancer.class.php)

  • Hooks: Used to interact with Dolibarr events like invoice validation, third-party creation, or payment submission.

  • Triggers: Event listeners (e.g., trigger.inc.php) that react to database-level changes.

  • Menus and permissions: Defined in the module descriptor.

Dolibarr allows modules to extend existing entities (like invoices or thirdparties), add tabs, or override core behaviors.

5. Development Environment Setup

To build the Stancer module, we used:

  • Dolibarr v15+ installed on a local development environment (Apache + MySQL)

  • Composer for dependency management (for HTTP clients)

  • Git for version control

  • A test Stancer account to access the developer dashboard and API keys

Ensure MAIN_MODULE_STANCER is declared in Dolibarr’s conf file during development.

6. Authentication and Stancer API Access

Stancer uses basic HTTP authentication:

Authorization: Basic base64(YourPrivateKey:)

We used Guzzle (a PHP HTTP client) to make authenticated requests. All API calls—whether creating a payment, retrieving a transaction, or setting up a recurring charge—require the use of a secure private key issued by Stancer.

To securely store and use this key:

  • Use Dolibarr’s conf object ($conf->global->STANCER_API_KEY)

  • Mask the value in configuration interfaces

  • Validate it during module setup

7. Building the Stancer Module

File Structure

/custom/stancer/
├── class/
│   └── api_stancer.class.php
├── core/
│   └── modules/
│       └── modStancer.class.php
├── hook/
│   └── interface_99_modstancer_common.php
├── stancer.php
└── README.md

Key Configuration Files

  • modStancer.class.php: Defines module properties and installation behavior

  • api_stancer.class.php: Core class to manage API requests

  • hook/interface_99_modstancer_common.php: Hooks into Dolibarr forms

Payment Hook Integration

Using addMoreActionsButtons() we inject a “Pay with Stancer” button directly in invoice view pages. Clicking this button triggers a redirection to a secure payment form hosted on Dolibarr or via iframe embedding.

8. Handling Transactions: Payments and Webhooks

Real-Time Payments

When a user completes a payment, we immediately:

  • Call Stancer’s /payment endpoint

  • Save the transaction ID in a custom field on the invoice

  • Update Dolibarr’s payment records via the API or trigger

Webhook Integration

Stancer supports callbacks for events like:

  • Payment success or failure

  • Subscription renewals

We registered a webhook in the Stancer dashboard pointing to:

https://yourdomain.com/custom/stancer/webhook.php

This script reads the incoming JSON, validates it, and updates the invoice status in Dolibarr.

9. Testing and Debugging Stancer Integration

Testing covered:

  • Successful payments (Visa/Mastercard)

  • Payment declines (simulate with Stancer test cards)

  • Subscription renewals and cancelations

  • Error cases (network issues, malformed payloads)

We logged all API responses to a secure log file and used Dolibarr’s dol_syslog() for internal tracking.

Common issues included:

  • Encoding errors in POST payloads

  • Webhook IP whitelisting

  • Non-synchronous updates in recurring payments

10. User Interface and UX Considerations

Our module provides:

  • A configuration page under "Third-Party Setup" for entering the API key

  • Payment status indicators in the invoice view

  • Error messages when a transaction fails

  • Email notifications to both admin and customer on payment status

We avoided redesigning the core UI and instead extended existing templates where possible.

11. Real-World Integration Challenges and Lessons Learned

1. Dolibarr’s Version Compatibility

Changes in core objects across Dolibarr versions (e.g., Facture class) caused initial bugs. Solution: abstract logic in service classes and test across versions.

2. Secure Token Storage

We initially stored the API key in plain text. Moved to encrypted storage using Dolibarr’s built-in obfuscation methods.

3. Payment Confirmation Timing

Asynchronous webhook confirmation sometimes clashed with manual payment inputs. We added a delay and double-check logic.

12. Security and Compliance in Payment Modules

Security is paramount in payment integrations:

  • HTTPS is mandatory for all communications

  • The webhook endpoint must verify HMAC signatures (if available)

  • Sensitive data like card numbers are never stored—only tokens or transaction IDs

  • Audit logs are stored securely and periodically reviewed

We also reviewed GDPR compliance and informed users about data processing during setup.

13. Tips for Deployment and Maintenance

  • Use a staging environment for updates

  • Document all custom hooks and overrides

  • Schedule regular API key rotations

  • Monitor logs for failed transactions or webhook attempts

  • Backup configuration before upgrading Dolibarr

14. Community Contribution and Future Enhancements

We plan to:

  • Add native support for SEPA direct debits

  • Publish the module on Dolistore with documentation in English and French

  • Implement multi-currency support

  • Add compatibility with Dolibarr’s recurring invoice feature

We encourage contributions via GitHub and maintain an open roadmap.

15. Conclusion

Developing the Stancer module for Dolibarr proved to be a rewarding challenge. It required deep knowledge of both Dolibarr’s internals and modern API development principles. With careful planning, secure coding, and community feedback, we’ve created a flexible and production-ready payment solution.

For any Dolibarr users seeking to modernize their payment workflow, this integration is a scalable and user-friendly option. As payment technology evolves, we’ll continue to improve the module and support the community.