Module Stancer

Retour index
Documentation développeur

Retour index
Documentation Utilisateur

Informations

Module name	Stancer
Editor / Editeur	CAP-REL - cap-rel.fr
Download or buy page / Page achat ou téléchargement	External module - www.dolistore.com
Status / Statut / Estado	Stable
Prerequisites / Prérequis	PHP 7.4 minimum Dolibarr min version: See on Dolistore    Dolibarr max version: See on Dolistore
Last update date / Date mise à jour fiche / Fecha última actualización	2026-02-24
Note / Nota	Utilisez Stancer comme prestataire de paiement

Qu'est-ce que le module Stancer pour Dolibarr ?

Plus de documentation sur le site de l'éditeur : https://doc.cap-rel.fr/projet_stancer/accueil

Le module Stancer est un module d'intégration de la passerelle de paiement Stancer dans l'ERP Dolibarr. Il permet d'encaisser des paiements par carte bancaire (avec 3D Secure) et par prélèvement SEPA, directement depuis les objets métier de Dolibarr (factures, commandes, devis, dons, cotisations d'adhérents).

Langues supportées : Français, Anglais, Allemand, Espagnol, Italien, Néerlandais

Architecture technique

Tables de base de données

Le module crée trois tables principales dans la base de données Dolibarr :

llx_stancer_stancer_payments

Stocke l'historique de tous les paiements (CB et SEPA).

Champ	Type	Description
rowid	INTEGER (PK)	Identifiant interne auto-incrémenté
stancer_id	VARCHAR(30) NOT NULL	Identifiant unique du paiement chez Stancer
amount	INTEGER	Montant en centimes
fee	INTEGER	Frais de transaction en centimes
currency	VARCHAR(4)	Code devise (EUR, USD, etc.)
description	VARCHAR(64)	Description du paiement
order_id	VARCHAR(36)	Référence de commande du marchand
unique_id	VARCHAR(36) UNIQUE	Identifiant unique / clé d'idempotence (TAG)
method	VARCHAR(4)	Méthode de paiement (card ou sepa)
card	VARCHAR(30)	Identifiant de la carte si paiement CB
sepa	VARCHAR(30)	Identifiant SEPA si prélèvement
customer	VARCHAR(30)	Identifiant client Stancer
refunds	TEXT	Tableau JSON des remboursements associés
response	VARCHAR(4)	Code de réponse bancaire
capture	BOOLEAN	Capture immédiate (oui/non)
created	DATETIME	Date de création chez Stancer
date_bank	TIMESTAMP	Date de traitement bancaire
live_mode	BOOLEAN	Mode production (1) ou test (0)
fk_soc	INTEGER	Clé étrangère vers le tiers Dolibarr
status	INTEGER NOT NULL	Code de statut du paiement
entity	INTEGER	Support multi-entité
date_creation	DATETIME NOT NULL	Date de création locale
tms	TIMESTAMP	Date de dernière modification
fk_user_creat	INTEGER (FK → llx_user)	Utilisateur créateur
fk_user_modif	INTEGER	Utilisateur modificateur

Index : stancer_id, fk_soc, status

llx_stancer_stancer_payouts

Stocke les reversements (virements de Stancer vers le compte bancaire du marchand).

Champ	Type	Description
rowid	INTEGER (PK)	Identifiant interne
payout_id	VARCHAR(30) NOT NULL	Identifiant unique du reversement chez Stancer
amount	INTEGER	Montant total en centimes
fees	INTEGER	Frais de traitement en centimes
amount_net	INTEGER	Montant net (montant - frais)
currency	VARCHAR(4)	Code devise
date_paym	DATETIME	Date des transactions incluses
date_bank	DATETIME	Date de virement effectif
details	TEXT	Détails complémentaires (JSON)
payments	TEXT	JSON des paiements inclus dans ce reversement
refunds	TEXT	JSON des remboursements inclus
disputes	TEXT	JSON des litiges inclus
statement_description	TEXT	Libellé du relevé bancaire
status	INTEGER NOT NULL	Statut du reversement
entity	INTEGER	Support multi-entité
tms	TIMESTAMP	Date de dernière modification

Index : payout_id, status

llx_stancer_stancer_refunds

Stocke les remboursements émis vers les clients.

Champ	Type	Description
rowid	INTEGER (PK)	Identifiant interne
refund_id	VARCHAR(30) NOT NULL	Identifiant unique du remboursement chez Stancer
payment_id	VARCHAR(30) NOT NULL	Identifiant du paiement d'origine
amount	INTEGER	Montant remboursé en centimes
currency	VARCHAR(4)	Code devise
status	INTEGER NOT NULL	Statut du remboursement
created	DATETIME	Date de création chez Stancer
date_refund	TIMESTAMP	Date de traitement du remboursement
date_bank	TIMESTAMP	Date de crédit bancaire
live_mode	BOOLEAN	Mode production ou test
fk_soc	INTEGER	Clé étrangère vers le tiers
entity	INTEGER	Support multi-entité
date_creation	DATETIME NOT NULL	Date de création locale
tms	TIMESTAMP	Date de dernière modification
fk_user_creat	INTEGER (FK → llx_user)	Utilisateur créateur
fk_user_modif	INTEGER	Utilisateur modificateur

Index : refund_id, payment_id, status, fk_soc

Fonctionnalités

1. Paiement par carte bancaire (CB)

1.1 Flux de paiement CB

Le paiement par carte bancaire suit le flux suivant :

1. L'utilisateur Dolibarr clique sur le bouton "Payer avec Stancer" depuis la fiche d'une facture, commande, devis, don ou cotisation
2. Le module valide l'objet (statut, montant restant dû, etc.)
3. Un paiement est créé via l'API Stancer (POST /checkout/)
4. L'enregistrement est sauvegardé dans llx_stancer_stancer_payments
5. Le client est redirigé vers la page hébergée Stancer : https://payment.stancer.com/{pubkey}/{paymentId}
6. Le client saisit ses informations de carte et confirme (avec 3D Secure si nécessaire)
7. Stancer rappelle la page de retour : /public/paymentback.php
8. La page de retour vérifie le statut du paiement via l'API
9. Si le paiement est confirmé : enregistrement du paiement dans Dolibarr, mise à jour de la facture, envoi d'email de confirmation

1.2 Page publique CB

La page public/cb.php permet aux clients d'enregistrer une carte bancaire pour des paiements ultérieurs (sans effectuer de transaction immédiate).

Champs du formulaire :

• Nom de la société (lecture seule)
• Nom du titulaire de la carte
• Numéro de carte (masqué avec auto-formatage)
• Date d'expiration (format MM/AAAA)
• CVC/CVV

Sécurité :

• Protection CSRF via jeton
• Clé sécurisée : hash("CB-{socid}-{nom_société}-{PAYMENT_SECURITY_TOKEN}")
• Détection de rechargement de page pour prévenir les doublons
• Support de la pré-autorisation 3DS (action=preauth)

1.3 Configuration CB

Paramètre	Description
STANCER_ENABLE_CB	Activer/désactiver les paiements CB
STANCER_PUBLIC_CB_PAGE	Activer la page publique d'enregistrement de carte
STANCER_CB_ORDER_PARTIAL_PAY	Pourcentage d'acompte pour les commandes (0 = totalité)
STANCER_CB_PROPAL_PARTIAL_PAY	Pourcentage d'acompte pour les devis
STANCER_AUTO_MAIL_ORDER_CB	Envoi automatique d'email lors de l'initiation d'un paiement CB
STANCER_AUTO_MAIL_INVOICES_CB	Envoi automatique d'email CB pour les factures
STANCER_AUTO_MAIL_INVOICES_CB_MAILTYPE	Modèle d'email à utiliser pour les notifications CB

1.4 Acomptes et paiements partiels

Le module supporte les acomptes sur les commandes et les devis :

• Configurable via STANCER_CB_ORDER_PARTIAL_PAY (pourcentage de 1 à 100)
• Configurable via STANCER_CB_PROPAL_PARTIAL_PAY pour les devis
• Le montant de l'acompte est calculé automatiquement : total_ttc × pourcentage / 100
• Les paiements partiels sont marqués avec un flag partialPayment=1
• Suivi des paiements multiples via un séquenceur (SEQ={compteur} dans le TAG)

2. Paiement par prélèvement SEPA

2.1 Création de mandat SEPA

La page publique public/sepa-iban.php permet aux clients de saisir leur IBAN pour créer un mandat SEPA.

Champs du formulaire :

• Nom de la société (lecture seule)
• Nom du titulaire du compte
• Nom de la banque
• IBAN (avec auto-espacement)
• BIC (optionnel, récupéré automatiquement depuis Stancer si absent)

Processus de création :

1. Validation de l'IBAN via la bibliothèque PHP_IBAN
2. Création du compte client Stancer si nécessaire
3. Création/mise à jour de l'enregistrement societe_rib dans Dolibarr :
   • Label : stancer-sepa-tst (test) ou stancer-sepa (production)
   • RUM auto-généré via BonPrelevement::buildRumNumber()
   • Type FRST/RECUR (premier/récurrent)
4. Enregistrement de l'IBAN chez Stancer via stancerAddSEPAIfNeeded()
5. Génération optionnelle du PDF de mandat SEPA (si STANCER_MANDATE_AUTO activé)
6. Signature électronique optionnelle via UpToSign (si STANCER_MANDATE_AUTO_UPTOSIGN activé)

2.2 Flux de paiement SEPA

1. Le système (ou l'utilisateur) déclenche un prélèvement SEPA via stancerSEPAstartPay()
2. Validation du délai SEPA (configurable, par défaut 5 jours avant l'échéance)
3. Vérification du montant maximum autorisé (STANCER_SWITCH_SEPA_AMOUNT_MAX)
4. Validation de la date de paiement de la facture
5. Création du paiement via l'API Stancer
6. Sauvegarde dans llx_stancer_stancer_payments

2.3 Configuration SEPA

Paramètre	Description
STANCER_PUBLIC_IBAN_PAGE	Activer la page publique de saisie IBAN
STANCER_PUBLIC_IBAN_PAGE_FORCE	Forcer l'affichage de la page IBAN
STANCER_MANDATE_AUTO	Générer automatiquement le PDF du mandat SEPA
STANCER_MANDATE_AUTO_UPTOSIGN	Intégration signature électronique UpToSign
STANCER_MANDATE_AUTO_UPTOSIGN_NOCLICK	Redirection automatique vers la signature
STANCER_DELAY_SEPA	Délai en jours avant prélèvement (défaut : 5)
STANCER_DELAY_SEPA_UPDATE_INVOICES	Mettre à jour les dates de factures selon le délai
STANCER_SWITCH_SEPA_AMOUNT_MAX	Montant maximum pour un prélèvement SEPA
STANCER_SWITCH_SEPA_TO_OTHER_BANK	Basculer vers un autre compte bancaire au-delà du seuil
STANCER_AUTO_MAIL_INVOICES_SEPA	Email automatique pour les prélèvements SEPA
STANCER_AUTO_MAIL_INVOICES_SEPA_MAILTYPE	Modèle d'email SEPA
STANCER_EMAIL_DPO	Email du Délégué à la Protection des Données (RGPD)
PRELEVEMENT_ICS	Identifiant Créancier SEPA (ICS)

2.4 Génération de mandat PDF

Le module inclut un générateur PDF spécifique (pdf_sepamandate_stancer) qui produit :

• La Référence Unique de Mandat (RUM)
• L'Identifiant Créancier SEPA (ICS)
• Les coordonnées du créancier (nom, adresse complète)
• Le formulaire débiteur (nom, adresse, IBAN, BIC)
• La case à cocher FRST/RECUR
• Les textes légaux SEPA relatifs au traitement des données et aux droits
• Les informations du DPO (Délégué à la Protection des Données)
• L'espace de signature (avec support UpToSign pour signature électronique)

3. Gestion des remboursements

3.1 Fonctionnalités

• Création de remboursements via l'API Stancer (POST /refunds/)
• Suivi des remboursements dans la table llx_stancer_stancer_refunds
• Liaison avec le paiement d'origine via payment_id
• Statuts : Brouillon (0), Validé (1), Annulé (9)
• Page de liste dédiée avec filtres et recherche (stancer_refunds_list.php)
• Détection des remboursements déjà effectués pour éviter les doublons

3.2 Statuts de remboursement

Code	Statut	Description
0	Brouillon	Remboursement en attente de traitement
1	Validé	Remboursement effectué
9	Annulé	Remboursement annulé

4. Gestion des reversements (Payouts)

4.1 Fonctionnalités

Les reversements représentent les virements effectués par Stancer vers le compte bancaire du marchand.

• Synchronisation des reversements depuis l'API Stancer (GET /payouts/)
• Détail des reversements : paiements inclus, remboursements, litiges
• Calcul du montant net (montant brut - frais)
• Disponible uniquement en mode production (les reversements n'existent pas en mode test)

4.2 Statuts des reversements

Code	Statut	Description
-10	Erreur	Erreur de traitement
0	Brouillon	En attente
1	En attente	Traitement en cours
2	À payer	Programmé pour paiement
3	Envoyé	Envoyé à la banque
4	Payé	Crédité sur le compte
5	Échoué	Échec du virement
9	Annulé	Reversement annulé
10	Validé	Validé dans le système

4.3 Import de relevés de reversement

La page stancer_import_check_reversements.php permet d'importer et vérifier les relevés mensuels de Stancer au format CSV.

Processus d'import :

1. Téléversement du fichier CSV avec le numéro de relevé
2. Analyse automatique des en-têtes et mapping des colonnes
3. Pour chaque opération (paiement, remboursement, litige) :
   • Vérification de l'existence de l'opération en banque (champ num_chq)
   • Validation des montants
   • Mise à jour du num_releve
4. Pour chaque reversement :
   • Création d'une écriture VIR (virement) vers le compte principal
   • Création d'une écriture PRE (prélèvement) pour les frais
5. Vérification croisée : détection des écritures bancaires absentes du fichier d'import
6. Totalisation des crédits et débits avec comparaison

5. Statuts des paiements

Code	Statut	Description
-10	Erreur	Erreur technique lors du paiement
-1	Masqué	Paiement masqué dans l'interface
0	Brouillon	Paiement initialisé, en attente
1	Autorisé	Autorisé par la banque, pas encore capturé
2	Capturé	Montant crédité sur le compte
3	Capture envoyée	Capture en cours de traitement
4	Contesté	Le client a contesté le paiement (litige)
5	Expiré	Paiement expiré
6	Échoué	Paiement échoué
7	Refusé	Paiement refusé par la banque
8	À capturer	Sera traité dans la journée
9	Annulé	Paiement annulé
10	Validé	Paiement validé dans le système

6. Pages de liste et de gestion

6.1 Liste des paiements (stancer_payments_list.php)

Colonnes affichées :

• Identifiant interne (rowid)
• Identifiant Stancer (stancer_id) — lien cliquable vers le dashboard Stancer
• Montant (converti de centimes en devise)
• Devise
• Description
• Référence commande (order_id) — lien vers la facture/commande Dolibarr
• Identifiant unique (TAG)
• Méthode (card/sepa)
• Identifiant carte / SEPA
• Identifiant client Stancer
• Remboursements associés
• Statut (avec badge coloré)
• Code réponse bancaire
• Statut de capture
• Date de création
• Mode (test/production)
• Tiers (avec résolution automatique depuis le TAG si absent)

Fonctionnalités :

• Filtres individuels par colonne
• Recherche globale
• Tri par colonne
• Pagination configurable
• Bouton Rafraîchir : synchronisation manuelle avec l'API Stancer (déclenche stancerRefreshAllPayments(), stancerRefreshAllPaymentsFromDolibarr() et stancerRemoveOldDraftPayments())
• Basculement vue liste / vue Kanban
• Suppression en masse (si permissions)
• Champs supplémentaires (extrafields) dynamiques
• Résolution automatique du tiers (fk_soc) depuis le TAG si absent

6.2 Liste des reversements (stancer_payouts_list.php)

Colonnes affichées :

• Identifiant interne et Stancer
• Montant brut, frais, montant net (calculé automatiquement)
• Devise
• Description et libellé relevé
• Dates (paiement et virement bancaire)
• Nombre de paiements, remboursements, litiges inclus
• Statut
• Mode (test/production)

Particularités :

• Le rafraîchissement n'est disponible qu'en mode production (message d'avertissement en mode test)
• Bouton "Nouveau" pour créer un enregistrement manuellement (tests)

6.3 Liste des remboursements (stancer_refunds_list.php)

Interface standard de liste Dolibarr avec :

• Colonnes triables et filtrables
• Vue liste et Kanban
• Actions en masse (suppression, email)
• Support des champs supplémentaires (extrafields)

7. Page de retour de paiement (public/paymentback.php)

Page publique appelée par Stancer après que le client a complété son paiement. Aucune authentification requise.

7.1 Flux de traitement

1. Décodage des paramètres : déchiffrement Base64 du paramètre s contenant tag, source, ref, securekey, entity
2. Récupération du paiement depuis la table Stancer par UUID ou session
3. Vérification du statut via l'API Stancer (GET /checkout/{id})
4. Traitement carte bancaire : extraction des données de carte (marque, 4 derniers chiffres, nom, pays), création/mise à jour du mode de paiement
5. Détection de doublons : recherche dans llx_paiement par ext_payment_id — affiche "Rechargement détecté" si doublon
6. Mise à jour de l'enregistrement local via fillDataFromApi()
7. Actions post-paiement : attribution de permissions temporaires, enregistrement du paiement sur l'objet Dolibarr

7.2 Sécurité

• Pas d'authentification requise (page publique)
• CSRF désactivé (callback externe)
• Paramètres encodés en Base64 dans l'URL
• Support multi-entité via le paramètre entity

8. Onglet Tiers (stancer_thirdparty.php)

Ajoute un onglet "Stancer" sur la fiche des tiers dans Dolibarr.

Sections affichées :

• Compte Stancer : nom, date de création, identifiant (lien vers manage.stancer.com), action de suppression
• Mandats SEPA (si compte existant) : tableau avec label, banque, IBAN, BIC, identifiant Stancer, RUM, date RUM, mode de prélèvement, actions (créer/supprimer sur Stancer)
• Cartes bancaires (si carte existante) : tableau avec label, type, numéro masqué, titulaire, expiration, type de carte, pays, actions
• Lien de paiement du solde : bouton "Payer le solde [€X.XX]" pour encaisser directement les factures impayées du tiers
• Liens publics : vers les pages de saisie IBAN et CB si activées
• Intégration UpToSign : avertissement si activé mais aucun signataire configuré

9. Comptabilité et rapprochement

9.1 Gestion des frais

Trois modes de gestion des frais Stancer :

Mode	Paramètre	Description
Aucun	STANCER_ADD_FEES = NONE	Pas d'enregistrement automatique des frais
Par reversement	STANCER_ADD_FEES = PAYOUT	Frais enregistrés au niveau de chaque reversement
Par paiement	STANCER_ADD_FEES = PAYMENT	Frais enregistrés individuellement pour chaque paiement

9.2 Régularisation des écarts comptables (admin/compta.php)

Page dédiée au rapprochement entre les factures fournisseur Stancer et les écritures comptables.

Fonctionnalités :

• Détection automatique des écarts entre débits et crédits
• Seuil configurable (STANCER_COMPTA_SEUIL_ECART, ex. 0.05 EUR)
• Création d'écritures OD (Opérations Diverses) pour régulariser
• Deux lignes par écart :
  1. Ligne compte fournisseur : débit/crédit du solde d'écart
  2. Ligne compte d'écart (658xxx) : contrepartie

Configuration :

Paramètre	Description
STANCER_COMPTA_JOURNAL_OD	Journal pour les écritures OD
STANCER_COMPTA_ACCOUNT_ECART	Compte comptable pour les écarts (ex. 658xxx)
STANCER_COMPTA_SEUIL_ECART	Seuil de régularisation (ex. 0.05 EUR)
STANCER_COMPTA_SUPPLIER_ID	Identifiant du fournisseur Stancer dans Dolibarr

9.3 Enregistrement bancaire

Les paiements sont enregistrés dans le module bancaire de Dolibarr :

• Création d'écritures llx_bank pour chaque paiement confirmé
• Enregistrement des frais en écriture séparée si configuré
• Support des virements inter-comptes pour les reversements
• Détection des doublons bancaires (stancerBankLineDoesNotExists())

10. Automatisation et tâches planifiées

Le module définit trois tâches cron dans Dolibarr :

10.1 StancerCheckPay

Fréquence : quotidienne

Action : Vérifie le statut des paiements et reversements

• Synchronise les paiements depuis l'API Stancer
• Synchronise les paiements locaux non finalisés
• Vérifie les reversements
• Envoie des notifications email si configuré

10.2 StancerCheckTakePayments

Fréquence : quotidienne

Action : Collecte automatique des paiements SEPA

• Recherche les factures avec un mode de paiement SEPA actif
• Vérifie l'existence d'un compte Stancer et d'un mandat SEPA valide
• Initie les prélèvements SEPA pour les factures éligibles
• Gère les acomptes et les échecs de relance
• Génère un rapport HTML/email des actions effectuées

10.3 StancerCheckInvoicesPaid

Fréquence : quotidienne

Action : Vérification du statut "payé" des factures

• Recherche les factures non marquées comme payées
• Vérifie si le montant payé correspond au total TTC
• Marque automatiquement les factures comme payées si le paiement est complet

11. Hooks et intégration Dolibarr

Le module s'intègre dans 14 points d'accroche (hooks) de Dolibarr :

Hook	Contexte d'intégration
newpayment	Création de paiement
paymentlib	Fonctions de la bibliothèque paiement
invoicecard	Fiche facture client
invoicesuppliercard	Fiche facture fournisseur
ordercard	Fiche commande
propalcard	Fiche devis / proposition commerciale
formObjectOptions	Options de formulaire
thirdpartybancard	Onglet compte bancaire du tiers
printFieldListTitle	En-têtes de colonnes dans les listes
printFieldListValue	Valeurs de colonnes dans les listes
subscription	Cotisations d'adhérents
doncard	Fiche don
membercard	Fiche adhérent
bankline	Ligne d'écriture bancaire

Actions principales du hook formConfirm :

• stancerCard : affiche une popup de paiement CB avec QR code et lien de paiement
• stancerSEPA : valide qu'un prélèvement SEPA n'est pas déjà en cours (temporisation de 10 minutes)

12. Variables de substitution

Le module fournit des variables de substitution pour les emails et documents :

Variable	Description
__STANCER_SEPA_RUM__	Référence Unique de Mandat SEPA
__STANCER_SEPA_DELAIS__	Délai de prélèvement SEPA (en jours)
__STANCER_SEPA_URL__	Lien public vers la page de saisie IBAN

13. Modèles d'emails

Six modèles d'emails sont préconfigurés à l'installation :

Modèle	Utilisation
Stancer Facture (SEPA)	Notification de prélèvement SEPA classique
Stancer Facture (SEPA information initiale)	Email d'information initial SEPA (obligation réglementaire)
Stancer Facture (SEPA Succès)	Confirmation de prélèvement SEPA réussi
Stancer Facture (ERREUR)	Notification d'erreur de paiement avec options de récupération
Stancer Facture (CB)	Notification de paiement par carte bancaire
Stancer Commande	Rappel de paiement pour commande

Variables disponibles dans les modèles : __REF__, __MYCOMPANY_NAME__, __MYCOMPANY_ADDRESS__, __MYCOMPANY_ZIP__, __MYCOMPANY_TOWN__, __DAY_TEXT__, __DAY__, __MONTH_TEXT__, __YEAR__, __AMOUNT_EXCL_TAX_FORMATED__, __STANCER_SEPA_DELAIS__, __USER_SIGNATURE__, __ONLINE_PAYMENT_URL__

14. Notifications automatiques

Paramètre	Description
STANCER_AUTO_MAIL_NOTIFICATIONS	Activer les notifications email globales
STANCER_AUTO_MAIL_NOTIFICATIONS_PAYMENT	Notification à chaque paiement reçu
STANCER_AUTO_MAIL_NOTIFICATIONS_PAYOUT	Notification à chaque reversement reçu
STANCER_AUTO_MAIL_NOTIFICATIONS_ON_NEW_CB_AND_SEPA	Notification lors de l'enregistrement d'une nouvelle carte ou d'un nouveau mandat SEPA
STANCER_AUTO_MAIL_INVOICES_ERROR	Notification en cas d'erreur de paiement

Administration

Pages d'administration

Le module fournit 12 pages d'administration accessibles depuis le menu Stancer :

Page	Fichier	Description
Configuration	admin/setup.php	Paramètres généraux, clés API, comptes bancaires, synchronisation
Carte bancaire	admin/cb.php	Configuration des paiements CB, 3DS, emails
SEPA	admin/sepa.php	Configuration des prélèvements SEPA, délais, montants max
Email	admin/mail.php	Configuration des modèles d'emails
Association	admin/asso.php	Activation pour les associations et adhérents
Comptabilité	admin/compta.php	Rapprochement comptable et régularisation des écarts
Test	admin/test.php	Interface de test de l'API (client, paiements, reversements)
À propos	admin/about.php	Informations sur le module
Logs	admin/logs.php	Visualisation des journaux de transactions
Extrafields Paiements	admin/stancer_payments_extrafields.php	Champs personnalisés pour les paiements
Extrafields Reversements	admin/stancer_payouts_extrafields.php	Champs personnalisés pour les reversements
Extrafields Remboursements	admin/stancer_refunds_extrafields.php	Champs personnalisés pour les remboursements

Configuration générale

Clés API

Paramètre	Description
STANCER_IS_PROD	Mode production (1) ou test (0)
STANCER_TEST_PUBLIC_KEY	Clé publique de test
STANCER_TEST_PRIVATE_KEY	Clé privée de test (masquée)
STANCER_PROD_PUBLIC_KEY	Clé publique de production
STANCER_PROD_PRIVATE_KEY	Clé privée de production (masquée)

Comptes et utilisateurs

Paramètre	Description
STANCER_USER_ACCOUNT_FOR_ACTIONS	Utilisateur Dolibarr pour les actions automatisées
STANCER_BANK_ACCOUNT_FOR_PAYMENTS	Compte bancaire pour l'enregistrement des paiements
STANCER_BANK_MAIN_ACCOUNT_FOR_PAYOUTS	Compte bancaire principal pour les reversements

Synchronisation

Paramètre	Description	Défaut
STANCER_NUMBER_OF_ITEMS_TO_SYNC	Nombre d'éléments par appel API	200 (plage : 10-1000)
STANCER_NB_DAYS_TO_SYNC	Nombre de jours d'historique à récupérer	31 (plage : 10-730)

Divers

Paramètre	Description
STANCER_MONTHLY_SUBSCRIPTION_FEE	Abonnement mensuel (frais de TPE, défaut : 18 EUR)
STANCER_AUTO_INVOICE_ON_PROPAL_PAID	Créer automatiquement une facture quand un devis est payé

Interface de test (admin/test.php)

Permet de vérifier le bon fonctionnement de l'API directement depuis Dolibarr :

1. Vérification de la configuration : affiche le mode (PRODUCTION / TEST) et un aperçu de la clé publique
2. Création de client : crée ou récupère un client de test, affiche le lien vers le dashboard Stancer
3. Lecture de client : affiche les détails (identifiant, email, nom, mobile)
4. Liste des paiements récents : affiche les 5 derniers paiements (identifiant, montant, statut, date)
5. Liste des reversements récents : affiche les 5 derniers reversements
6. Détail d'un paiement : informations détaillées incluant le masquage de carte (**** + 4 derniers chiffres)

Support des associations (admin/asso.php)

L'activation de Stancer pour les associations crée automatiquement trois champs supplémentaires sur les adhérents :

Champ	Type	Description
stancer_sepa_ref	VARCHAR(32)	Référence du mandat SEPA de l'adhérent
stancer_cb_ref	VARCHAR(32)	Référence de la carte bancaire de l'adhérent
stancer_account	VARCHAR(32)	Identifiant du compte client Stancer (obligatoire)

API REST Stancer

Le module utilise un client REST intégré (StancerApi) qui communique directement avec l'API Stancer sans dépendance externe.

Synchronisation

Principes

• La synchronisation est exclusivement manuelle (bouton Rafraîchir dans les listes)
• Jamais de rafraîchissement automatique lors de la recherche ou du filtrage
• Les fonctions de synchronisation sont chaînées conditionnellement : si l'une échoue, les suivantes sont ignorées

Flux de synchronisation des paiements

1. stancerRefreshAllPayments() : récupère les nouveaux paiements depuis l'API Stancer depuis la dernière synchronisation
2. stancerRefreshAllPaymentsFromDolibarr() : vérifie le statut des paiements locaux non finalisés via l'API
3. stancerRemoveOldDraftPayments() : supprime les paiements brouillon anciens (> 30 jours), sans appel API

Flux de synchronisation des reversements

1. stancerRefreshAllPayoutsFromStancer() : récupère les reversements depuis l'API (mode production uniquement)
2. Enchaîne avec la vérification locale si la première étape réussit
3. Arrêt immédiat en cas d'erreur

Objets métier supportés

Le module s'intègre avec les objets Dolibarr suivants :

Objet Dolibarr	Paiement CB	Prélèvement SEPA	Remarques
Facture client	Oui	Oui	Calcul automatique du solde restant dû
Commande	Oui	—	Support des acomptes (pourcentage configurable)
Devis / Proposition commerciale	Oui	—	Support des acomptes, page dédiée
Don	Oui	—	Via la page publique de paiement
Cotisation d'adhérent	Oui	Oui	Nécessite l'activation du mode association

Codes de réponse bancaire

Le module interprète les codes de réponse bancaire standards :

Code	Signification
00	Transaction approuvée
02	Contacter l'émetteur de la carte
03	Accepteur invalide
04	Conserver la carte
05	Ne pas honorer
07	Conserver la carte (conditions spéciales)
08	Approuver après identification
12	Transaction invalide
13	Montant invalide
14	Numéro de porteur invalide
15	Émetteur de carte inconnu
30	Erreur de format
31	Identifiant de l'acquéreur inconnu
33	Carte expirée
34	Suspicion de fraude
41	Carte perdue
43	Carte volée
51	Provision insuffisante ou crédit dépassé
54	Carte expirée
56	Carte absente du fichier
57	Transaction non autorisée pour ce porteur
58	Transaction non autorisée pour ce terminal
59	Suspicion de fraude
60	L'accepteur doit contacter l'acquéreur
61	Montant maximal de retrait dépassé
63	Règles de sécurité non respectées
68	Réponse non parvenue ou reçue trop tard
75	Nombre maximal d'essais PIN dépassé
76	Porteur déjà en opposition
90	Arrêt momentané du système
91	Émetteur de carte inaccessible
92	Transaction non trouvée par le réseau
94	Transaction dupliquée
96	Mauvais fonctionnement du système
97	Échéance de la temporisation
98	Serveur indisponible
99	Incident domaine initiateur
7840	Fraude détectée par le réseau CB

Tests

Le module dispose d'une suite complète de tests :

Tests unitaires

Fichier	Couverture
StancerApiTest.php	Client HTTP StancerApi
StancerClassTest.php	Classe principale Stancer
StancerLibTest.php	Fonctions de la bibliothèque partagée
StancerPaymentsTest.php	Modèle Stancer_payments
StancerPayoutsTest.php	Modèle Stancer_payouts
StancerRefundsTest.php	Modèle Stancer_refunds

Tests d'intégration

Fichier	Couverture
StancerClassIntegrationTest.php	Intégration classe principale avec Dolibarr
StancerLibIntegrationTest.php	Intégration fonctions bibliothèque
StancerPaymentsIntegrationTest.php	Intégration paiements
StancerPayoutsIntegrationTest.php	Intégration reversements
StancerRefundsIntegrationTest.php	Intégration remboursements
StancerTriggersIntegrationTest.php	Intégration déclencheurs

Infrastructure de test

• Framework : PHPUnit 9.6+
• Mocks : HttpMock (simulation HTTP), DolibarrMocks (simulation Dolibarr)
• Fixtures : StancerApiFixtures (réponses API pré-enregistrées)
• Base de données : SQLite via cap-rel/dolibarr-integration-sqlite
• Couverture : PCOV avec rapport HTML

Conformité et sécurité

RGPD / Protection des données

• Configuration du DPO (Délégué à la Protection des Données) via STANCER_EMAIL_DPO
• Textes légaux SEPA intégrés dans les mandats PDF
• Informations sur le traitement des données dans les formulaires publics

Sécurité des paiements

• Support 3D Secure pour les paiements par carte
• Clés sécurisées (hachage) pour les pages publiques
• Détection de rechargement de page pour prévenir les paiements en double
• Protection CSRF sur les formulaires (désactivée uniquement sur les callbacks externes)
• Arrêt immédiat sur erreur 401 (authentification) pour éviter les requêtes en boucle
• Masquage des numéros de carte (affichage des 4 derniers chiffres uniquement)

Multi-entité

• Toutes les tables supportent le champ entity pour la gestion multi-société
• Les clés API sont configurables par entité
• Le contexte multi-entité est propagé dans les callbacks publics

Historique des versions

Version	Date	Changements majeurs
1.2.136	2026-01-19	Paiement partiel (acompte) sur les devis
1.2.130	—	Corrections SQL des tâches cron
1.2.124	—	Migration vers getDolGlobalString(), support multi-entité, options d'automatisation SEPA
1.2.117	—	Nettoyage PHPStan, restauration gestion des frais
1.2.109	—	Second mandat SEPA, import de relevés, compatibilité Dolibarr 20
1.2.108	—	Support des remboursements, import CSV de relevés, helpers bancaires
1.2.100	—	Corrections de conditions de course, améliorations des popups
1.2.88	—	Retour bancaire anticipé CB, automatisation statut facture payée
1.2.80	—	Délai SEPA, gestion multi-entité
1.2.52	—	Rétro-portage PHP-IBAN, conformité CNIL/DPO
1.2.0	—	Configuration du délai SEPA, notifications email automatiques
1.0.0	2023-03-12	Publication initiale