Intégrer Dolibarr avec PayPal : Framework en 30 jours

Un guide pratique pour automatiser la gestion de vos paiements en ligne avec le ERP open‑source Dolibarr.

1️⃣ Contexte & Objectifs (Jour 1)

Objectif Pourquoi ?
Connecter Dolibarr à PayPal Permettre la saisie automatique des paiements reçus (ou effectues) via PayPal, éviter la saisie manuelle et garantir la conciliation comptable.
Créer un processus en 30 jours Structurer le projet en itérations de 7 jours (planification, mise en œuvre, tests, validation) pour livrer rapidement un module fonctionnel.
Documenter le workflow Faciliter la maintenance et le transfert à l’équipe support.

2️⃣ Architecture Globale (Jour 1‑2)

  1. Dolibarr (v9.x ou +) – ERP/CRM installé sur votre serveur (LAMP/LEMP).

  2. Extension “PayPal SDK” – Bibliothèque PHP officielle (paypal/rest-api-sdk-php).

  3. Webhook PayPal – Endpoint qui recevra les notifications d’évènements (payment.authorized, capture.completed, dispute.created, …).

  4. Base de données – Ajout de tables de liaison (si besoin) ou utilisation des objets existants (Invoices, Payments).

Schéma simplifié
Front‑office (site client) → PayPal Checkout → Webhook → Dolibarr (Webservice) → Paiement intégré

3️⃣ Jour 1‑3 – Phase de Recherche & Test de l’API PayPal

Action Détails
Créer un compte PayPal Business (ou Sandbox) Vous obtiendrez Client‑ID et Secret et le mode de paiement : REST.
Configurer un App dans le Dashboard PayPal Activer les scopes Payments, Invoices, Webhooks.
Lire la documentation officielle https://developer.paypal.com/docs/api/ – Sections Orders API (création, capture) Invoices API (si vous utilisez les factures automatisées).
Installer le SDK composer require paypal/rest-api-sdk-php.
Test local d’une création d’« Order */ Intent: AUTHORIZE** Exemple minimal : payment->create($request); → redirection URL vers PayPal.

Livrable : Script paypal_test.php qui crée une commande test, redirige et renvoie le statut de capture.

4️⃣ Jour 4‑7 – Conception du Webhook dans Dolibarr

Étape Implémentation
URL du webhook /paypal/webhook (ex. yourhost.com/dolibarr/paypal/webhook.php).
Enregistrement du endpoint Route ajoutée via .htaccess + script PHP.
Signature de vérif Utiliser hash_hmac('sha256', $rawBody, $pp_secret) pour valider que la requête vient réellement de PayPal.
Gestion des événements – PAYMENT.CAPTURE.COMPLETED → paiement final.
– PAYMENT.SALE (direct) → mode Sale.
– INVOICE.PAYMENT.COMPLETED (si vous utilisez les factures).
Mise à jour du paiement Dolibarr – Identifier la facture client (facture.id).
– Créer un paiement via Core\Payment::addPayment($amount, $method='PayPal', $label='PayPal', $ref='TxnId=xxxx');
– Marquer la facture comme paid ou partially paid.
Journalisation Sauvegarder json_decode(file_get_contents('php://input'), true) et loguer des détails (payment_status, txn_id, amount).

Livrable : paypal_webhook.php fonctionnel en sandbox, avec métriques de logs accessibles.

5️⃣ Jour 8‑12 – Développement du Module « PayPal » pour Dolibarr

Dolibarr possède un framework d’extensions (modules) qui s’appuie sur htdocs/core/modules. Nous allons créer un module paypal :

Fichier Contenu principal
mod_paypal/function.php Wrapper autour de l’API PayPal (création de commande, capture, vérif).
mod_paypal/submit.php UI qui injecte un bouton “Pay with PayPal” dans le formulaire de devis/facture.
mod_paypal/config.php Interface d’administration : champs Client ID, Secret, Mode (Sandbox / Production).
mod_paypal/icon.png Icône du module dans la liste des modules.
mod_paypal/receipts.php Affiche le reçu PayPal directement depuis la fiche paiement.

Code compact (exemple pour création d’une commande) 

require_once '$_SERVER[DOL_HOME]/core/modules/mod_paypal/function.php';

$order = Dolibarr::createOrderLine([

    'label'          => 'Abonnement mensuel',

    'price'          => $amount,

    'quantity'       => 1,

    'currency'       => $conf->currency->i,

    'payment_method' => 'paypal',

]);
$order->paypal_create_order(); // utilise le SDK sous‑couche

6️⃣ Jour 13‑15 – Intégration UI & Tests Fonctionnels

  1. Bouton de paiement

    • Dans customers, pro-forms, invoices, afficher le bouton « Arrêter paiement PayPal » intégré via le SDK Smart Payment Buttons ou le mini‑checkout REST.

  2. Redirection

    • Après création de l’Order, PayPal redirige vers return_url (ex. /paypal/return.php?token=XYZ).

  3. Gestion du retour

    • Le script de retour capture le token et l’appel au capture.

  4. Tests fonctionnels

    • Scenarios : paiement complet, paiement annulé, paiement partiel, paiement échoué.

    • Utilisation du mode Sandbox pour toutes les réponses.

    • Vérifier que le statut de la facture dans Dolibarr passe à Paid et que le champ paide/payment_ref est mis à jour.

7️⃣ Jour 16‑20 – Sécurisation & Conformité

Action Pourquoi
Chiffrement SSL L’API PayPal exige TLS 1.2+. Activez SSL sur votre serveur (openssl min_proto_version 1.2).
Limitation des scopes Ne demandez que les scopes strictement nécessaires (payment, invoice).
Double‑validation du webhook Toujours vérifier la signature et le PAYPAL-TRANSMISSION-ID.
Sauvegarde du token PayPal Stockez un client_id chiffré en base (crypt() ou openssl_encrypt) pour éviter les fuites.
Gestion des erreurs Retourner HTTP 500 avec message détaillé uniquement en environnement de dev ; en prod, renvoyer une réponse générique et logger.
Conformité PCI‑DSS En mode Hosted Checkout, le paiement se fait directement sur les pages PayPal → vous êtes hors du scope. En mode Direct API, vous devez vous conformer (non requis dans notre implémentation via webhook).

8️⃣ Jour 21‑25 – Optimisations & Documentation

Point Détails
Mode “Capture automatique” Décider si la capture doit être immédiate (capture) ou différée (ex. paiement en plusieurs fois).
Gestion des remboursements Ajout d’un endpoint /paypal/refund qui utilise le SDK refund et crée un return dans Dolibarr.
Mise à jour du journal de paiement Ajout de champs paypal_txn_id, paypal_status.
Documentation interne Créer un README.md avec : 

- Installation du module

- Paramètres de configuration

- Guide de test sandbox

- Guide de migration vers production

- FAQ (erreurs courantes)

| Mise à jour de la matrice de suivi | Importer le projet dans Trello/Asana et fermer les tickets traversés. |

9️⃣ Jour 26‑30 – Validation & Déploiement en Production

  1. Passage en production

    • Changer le mode dans le module (sandbox → production).

    • Mettre à jour les credentials avec ceux du compte Business réel.

  2. Tests de charge

    • Simuler 100 requêtes simultanées (via ab ou k6) pour vérifier que les appels PayPal respectent les limites de taux.

  3. Formation de l’équipe support

    • Walker them through le module, expliquer où trouver le log, comment activer/désactiver le webhook, comment réinitialiser les clés.

  4. Plan de rollback

    • Conserver les fichiers avant modification (cp -r mod_paypal mod_paypal.bak).

    • Si une anomalie critique, désactiver le webhook dans l’admin.

  5. Mise en production

    • Déployer via Git (git push → compressage) → Purger le cache (php -r "require_once DOL_STARTUP; dolibarr_clear_cache();").

    • Vérifier le tableau de bord PayPal → Webhooks pour confirmer la réception du statut webhook_id.

Livrable final : Module PayPal fonctionnel avec interface d’administration, traitement des paiements, webhook sécurisé, documentation complète et guide de migration.

📌 Points Clés à Ne Pas Manquer

Thème Astuce
Webhook PayPal envoie le même event_id une seule fois – assurez‑vous de le stocker pour éviter les duplications.
Idempotence Utilisez l’ID de transaction (paypal_txn_id) comme clé unique pour éviter les doubles captures.
Retours d’erreur PayPal renvoie parfois des erreurs temporaires (429, 502). Implémentez une logique de retry exponentiel.
Contrôle de la devise Le montant PayPal est arroundé au centième le plus proche – alignez avec la devise de Dolibarr.
Événements de dispute Lancez des alertes si un désaccord apparaît (dispute.created) – utile pour le service client.

🎉 Conclusion

En suivant ce framework en 30 jours, vous passez de la découverte de l’API PayPal à une intégration native dans Dolibarr : création de commande, capture, webhook sécurisé, UI client‑friendly et documentation interne. Vous avez ainsi :

  • ✅ Automatisation de la conciliation des paiements,

  • ✅ Visibilité du flux d’argent en temps réel,

  • ✅ Conformité PCI‑DSS (via Checkout hébergé) et sécurité des webhooks,

  • ✅ Processus reproductible pour les projets futurs (intégrations supplémentaires telles que Stripe, Adyen, …).

Bon développement ! Si vous avez besoin d’exemples de code plus détaillés ou d’un audit de config, n’hésitez pas à me le demander. 🚀

Publications similaires