Réconciliation des paiements
La page Réconciliation des paiements (menu Facturation -> capPatrol -> Paiements) répond à un problème concret : une facture marquée payée par une passerelle alors que l'encaissement a en réalité eu lieu sur une autre.
Le cas le plus fréquent : un client tente de payer par Stancer, le paiement est refusé, puis il revient payer par Mollie. Le paiement Mollie est bien encaissé, mais le lien de la facture reste accroché a la tentative Stancer refusée. capPatrol détecte cet écart et vous propose de le corriger.
Comment ça marche ?
capPatrol croise trois sources de vérité :
- Ce que Dolibarr enregistre sur le paiement de la facture (la passerelle et l'identifiant de transaction).
- La table de chaque passerelle (Stancer, Mollie) qui conserve l'état réel de chaque transaction (encaissée, refusée, expirée...).
- L'API de la passerelle (optionnel), qui confirme l'état réel d'une transaction au moment de la vérification.
Stripe ne tient pas de table locale par transaction : ses paiements sont contrôlés par recoupement avec les autres passerelles et, si activé, par appel API.
Les types d'incohérence
| Type | Description | Gravité |
|---|---|---|
| Lié à une tentative refusée | Le paiement enregistré pointe vers une tentative refusée sur une passerelle, alors qu'une autre passerelle a réellement encaissé la facture. C'est le cas Stancer refusé / Mollie payé. | Élevée |
| Mauvaise passerelle | Une transaction encaissée existe sur une passerelle différente de celle enregistrée par Dolibarr. | Élevée |
| Double encaissement | La facture apparaît encaissée sur deux passerelles à la fois. | Élevée |
| Paiement orphelin | Le paiement Dolibarr pointe vers une transaction introuvable côté passerelle. | Moyenne |
| Montant incohérent | La transaction est bien encaissée mais son montant ne correspond pas au paiement. | Moyenne |
Les paiements répartis légitimement sur plusieurs passerelles (une partie Stancer, une partie Mollie, chacune correctement enregistrée) ne déclenchent aucun signalement.
Les prélèvements SEPA groupés (une seule transaction de la passerelle qui règle plusieurs factures d'un même client le même jour) sont aussi reconnus : le montant de la transaction étant la somme des factures du lot, capPatrol ne déclenche pas de signalement de montant incohérent sur ces factures.
Vérifier les paiements
Le bouton Re-vérifier les paiements maintenant lance une analyse synchrone de l'entité courante. Cette analyse manuelle interroge systématiquement les API des passerelles afin de confirmer l'état réel des transactions : c'est cette confirmation qui rend la correction en un clic disponible.
La vérification tourne aussi automatiquement chaque nuit avec les autres détecteurs de capPatrol. En tâche de fond, l'appel API est désactivé par défaut (pour préserver les quotas) : il s'active dans la configuration via l'option Re-vérifier via les API des passerelles.
L'API fait foi sur les tables locales
Les tables internes des passerelles peuvent être périmées : si le webhook signalant le refus final d'une transaction n'a pas été reçu, la ligne locale peut rester marquée "encaissée" alors que la passerelle l'a refusée. Quand la re-vérification API est active, capPatrol fait donc primer l'état réel de l'API : un faux double encaissement (dont la seconde transaction est en fait refusée côté passerelle) ou un faux signalement de mauvaise passerelle est automatiquement écarté. C'est pourquoi le bouton de re-vérification manuelle interroge toujours les API.
Piste de paiement d'une facture
Depuis la fiche d'une facture client (bouton Piste de paiement dans la barre d'actions), capPatrol affiche l'historique chronologique complet des paiements de cette facture : chaque tentative sur chaque passerelle (Stancer, Mollie) avec son horodatage et son état, ainsi que les paiements enregistrés dans Dolibarr.
On lit ainsi par exemple :
- 08h10 - Mollie - Refusé / échoué - 9,60 EUR
- 11h00 - Stancer - Encaissé - 9,60 EUR
- 11h00 - Dolibarr - Enregistré - 9,60 EUR (Stancer)
Le bouton Recherche approfondie interroge en direct les API des passerelles pour afficher l'état réel et actuel de chaque transaction (utile quand une table interne de passerelle est périmée). Sans recherche approfondie, l'historique s'appuie sur les données locales et n'affiche aucune synthèse (elles peuvent être périmées) : seule la recherche approfondie produit une synthèse fiable et un verdict de cohérence.
Corriger les données locales périmées
Quand la recherche approfondie révèle qu'une table interne de passerelle ne reflète pas l'état réel (par exemple Stancer marqué "encaissé" alors que l'API dit "refusé", ou Mollie marqué "en attente" alors que l'API dit "payé"), capPatrol affiche un bandeau d'avertissement et, si vous avez le droit de correction, un bouton Corriger les données locales. Ce bouton réécrit le statut local de chaque transaction concernée pour qu'il corresponde à la réalité renvoyée par l'API. Une fois corrigées, la vue locale et la vue approfondie concordent, et la réconciliation globale ne remonte plus de faux signalements sur ces transactions.
Seul le statut est modifié (jamais les montants ni les identifiants). L'opération nécessite le droit Corriger un paiement mal rattaché.
Comprendre un signalement (journaux)
Si un signalement vous surprend, activez le niveau de journalisation DEBUG de Dolibarr puis relancez la re-vérification : capPatrol trace, pour chaque paiement, la passerelle enregistrée, l'identifiant de transaction, l'état trouvé localement, les transactions retenues ou écartées sur les autres passerelles, le résultat des appels API et la décision finale. Filtrez les journaux sur CAPPATROL: recon.
Corriger un paiement mal rattaché
Pour les incohérences confirmées par API du type Lié à une tentative refusée et Mauvaise passerelle, un bouton Re-rattacher le paiement apparaît. Il :
- corrige la passerelle enregistrée et l'identifiant de transaction du paiement sur la bonne passerelle ;
- déplace la ligne bancaire vers le compte associé à la bonne passerelle (si un compte est configuré, voir ci-dessous) ;
- ajoute une note d'audit horodatée sur le paiement ;
- marque l'incohérence comme résolue.
Aucun montant n'est déplacé et aucun paiement n'est supprimé : seul le lien vers la passerelle et, le cas échéant, le compte bancaire de la ligne sont corrigés. La correction nécessite le droit dédié Corriger un paiement mal rattaché.
Une banque par prestataire
Si vous utilisez un compte bancaire distinct par prestataire de paiement, renseignez le compte bancaire associé à chaque passerelle dans la configuration (voir ci-dessous). Lors de la correction, capPatrol déplace alors automatiquement la ligne bancaire du paiement (llx_bank) vers le compte de la passerelle réelle. Si aucun compte n'est configuré pour la passerelle cible, ou si le paiement n'a pas de ligne bancaire, la partie banque est laissée intacte.
Les types Paiement orphelin et Double encaissement ne proposent pas de correction automatique : ils demandent une revue manuelle, car corriger un paiement orphelin ou un double encaissement peut changer le statut payé de la facture.
Le bouton Ignorer permet d'écarter un signalement que vous avez vérifié et jugé normal. Les signalements ignorés ou résolus sont conservés et ne réapparaissent pas aux analyses suivantes.
Configuration
Les réglages se trouvent dans Configuration -> Réconciliation des paiements :
- Activer la réconciliation des passerelles de paiement : active ou désactive la famille v3.
- Profondeur historique (mois) : nombre de mois de factures vérifiées (12 par défaut).
- Re-vérifier via les API des passerelles : active l'appel API en tâche de fond (désactivé par défaut).
- Tolérance de rapprochement des montants : écart absolu toléré entre le montant d'une transaction et celui de la facture (0.01 par défaut).
- Compte bancaire pour Stancer / Mollie / Stripe : compte bancaire Dolibarr associé à chaque passerelle. Utilisé pour déplacer la ligne bancaire lors d'une correction. Laissez vide pour ne pas toucher à la banque.