Module Stancer: Difference between revisions

Jump to navigation Jump to search

Module Stancer (view source)

Revision as of 15:48, 24 February 2026

37,318 bytes added ,  8 months ago
full presentation - stancer module
VisualWikitext
m (Eldy moved page Stancer to Module Stancer)
(full presentation - stancer module)
Tag: 2017 source edit
Line 11: Line 11:
|webbuy={{LinkToPluginDownloadDoliStore|keyword=stancer}}
|webbuy={{LinkToPluginDownloadDoliStore|keyword=stancer}}
|status=stable
|status=stable
|prerequisites=
|prerequisites=PHP 7.4 minimum
|minversion=11.0.0
|minversion=15.0.0
|note= Utilisez Stancer comme prestataire de paiement
|note= Utilisez Stancer comme prestataire de paiement
}}
}}
Line 19: Line 19:
=Qu'est-ce que le module Stancer pour Dolibarr ?=
=Qu'est-ce que le module Stancer pour Dolibarr ?=


Le module Stancer vous permet d'utiliser ce prestataire comme plate-forme de paiement CB / SEPA.
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 [https://www.stancer.com Stancer] dans l'ERP [https://www.dolibarr.org 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).
 
{| class="wikitable"
! Champ !! Type !! Description
|-
| <code>rowid</code> || INTEGER (PK) || Identifiant interne auto-incrémenté
|-
| <code>stancer_id</code> || VARCHAR(30) NOT NULL || Identifiant unique du paiement chez Stancer
|-
| <code>amount</code> || INTEGER || Montant en centimes
|-
| <code>fee</code> || INTEGER || Frais de transaction en centimes
|-
| <code>currency</code> || VARCHAR(4) || Code devise (EUR, USD, etc.)
|-
| <code>description</code> || VARCHAR(64) || Description du paiement
|-
| <code>order_id</code> || VARCHAR(36) || Référence de commande du marchand
|-
| <code>unique_id</code> || VARCHAR(36) UNIQUE || Identifiant unique / clé d'idempotence (TAG)
|-
| <code>method</code> || VARCHAR(4) || Méthode de paiement (<code>card</code> ou <code>sepa</code>)
|-
| <code>card</code> || VARCHAR(30) || Identifiant de la carte si paiement CB
|-
| <code>sepa</code> || VARCHAR(30) || Identifiant SEPA si prélèvement
|-
| <code>customer</code> || VARCHAR(30) || Identifiant client Stancer
|-
| <code>refunds</code> || TEXT || Tableau JSON des remboursements associés
|-
| <code>response</code> || VARCHAR(4) || Code de réponse bancaire
|-
| <code>capture</code> || BOOLEAN || Capture immédiate (oui/non)
|-
| <code>created</code> || DATETIME || Date de création chez Stancer
|-
| <code>date_bank</code> || TIMESTAMP || Date de traitement bancaire
|-
| <code>live_mode</code> || BOOLEAN || Mode production (1) ou test (0)
|-
| <code>fk_soc</code> || INTEGER || Clé étrangère vers le tiers Dolibarr
|-
| <code>status</code> || INTEGER NOT NULL || Code de statut du paiement
|-
| <code>entity</code> || INTEGER || Support multi-entité
|-
| <code>date_creation</code> || DATETIME NOT NULL || Date de création locale
|-
| <code>tms</code> || TIMESTAMP || Date de dernière modification
|-
| <code>fk_user_creat</code> || INTEGER (FK → llx_user) || Utilisateur créateur
|-
| <code>fk_user_modif</code> || 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).
 
{| class="wikitable"
! Champ !! Type !! Description
|-
| <code>rowid</code> || INTEGER (PK) || Identifiant interne
|-
| <code>payout_id</code> || VARCHAR(30) NOT NULL || Identifiant unique du reversement chez Stancer
|-
| <code>amount</code> || INTEGER || Montant total en centimes
|-
| <code>fees</code> || INTEGER || Frais de traitement en centimes
|-
| <code>amount_net</code> || INTEGER || Montant net (montant - frais)
|-
| <code>currency</code> || VARCHAR(4) || Code devise
|-
| <code>date_paym</code> || DATETIME || Date des transactions incluses
|-
| <code>date_bank</code> || DATETIME || Date de virement effectif
|-
| <code>details</code> || TEXT || Détails complémentaires (JSON)
|-
| <code>payments</code> || TEXT || JSON des paiements inclus dans ce reversement
|-
| <code>refunds</code> || TEXT || JSON des remboursements inclus
|-
| <code>disputes</code> || TEXT || JSON des litiges inclus
|-
| <code>statement_description</code> || TEXT || Libellé du relevé bancaire
|-
| <code>status</code> || INTEGER NOT NULL || Statut du reversement
|-
| <code>entity</code> || INTEGER || Support multi-entité
|-
| <code>tms</code> || TIMESTAMP || Date de dernière modification
|}
 
'''Index :''' payout_id, status
 
==== llx_stancer_stancer_refunds ====
 
Stocke les remboursements émis vers les clients.
 
{| class="wikitable"
! Champ !! Type !! Description
|-
| <code>rowid</code> || INTEGER (PK) || Identifiant interne
|-
| <code>refund_id</code> || VARCHAR(30) NOT NULL || Identifiant unique du remboursement chez Stancer
|-
| <code>payment_id</code> || VARCHAR(30) NOT NULL || Identifiant du paiement d'origine
|-
| <code>amount</code> || INTEGER || Montant remboursé en centimes
|-
| <code>currency</code> || VARCHAR(4) || Code devise
|-
| <code>status</code> || INTEGER NOT NULL || Statut du remboursement
|-
| <code>created</code> || DATETIME || Date de création chez Stancer
|-
| <code>date_refund</code> || TIMESTAMP || Date de traitement du remboursement
|-
| <code>date_bank</code> || TIMESTAMP || Date de crédit bancaire
|-
| <code>live_mode</code> || BOOLEAN || Mode production ou test
|-
| <code>fk_soc</code> || INTEGER || Clé étrangère vers le tiers
|-
| <code>entity</code> || INTEGER || Support multi-entité
|-
| <code>date_creation</code> || DATETIME NOT NULL || Date de création locale
|-
| <code>tms</code> || TIMESTAMP || Date de dernière modification
|-
| <code>fk_user_creat</code> || INTEGER (FK → llx_user) || Utilisateur créateur
|-
| <code>fk_user_modif</code> || 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 :
 
# L'utilisateur Dolibarr clique sur le bouton "Payer avec Stancer" depuis la fiche d'une facture, commande, devis, don ou cotisation
# Le module valide l'objet (statut, montant restant dû, etc.)
# Un paiement est créé via l'API Stancer (<code>POST /checkout/</code>)
# L'enregistrement est sauvegardé dans <code>llx_stancer_stancer_payments</code>
# Le client est redirigé vers la page hébergée Stancer : <code>https://payment.stancer.com/{pubkey}/{paymentId}</code>
# Le client saisit ses informations de carte et confirme (avec 3D Secure si nécessaire)
# Stancer rappelle la page de retour : <code>/public/paymentback.php</code>
# La page de retour vérifie le statut du paiement via l'API
# 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 ====


Plus de documentation sur le site de l'éditeur : https://doc.cap-rel.fr/projet_stancer/accueil
La page <code>public/cb.php</code> 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 : <code>hash("CB-{socid}-{nom_société}-{PAYMENT_SECURITY_TOKEN}")</code>
* Détection de rechargement de page pour prévenir les doublons
* Support de la pré-autorisation 3DS (<code>action=preauth</code>)
 
==== 1.3 Configuration CB ====
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_ENABLE_CB</code> || Activer/désactiver les paiements CB
|-
| <code>STANCER_PUBLIC_CB_PAGE</code> || Activer la page publique d'enregistrement de carte
|-
| <code>STANCER_CB_ORDER_PARTIAL_PAY</code> || Pourcentage d'acompte pour les commandes (0 = totalité)
|-
| <code>STANCER_CB_PROPAL_PARTIAL_PAY</code> || Pourcentage d'acompte pour les devis
|-
| <code>STANCER_AUTO_MAIL_ORDER_CB</code> || Envoi automatique d'email lors de l'initiation d'un paiement CB
|-
| <code>STANCER_AUTO_MAIL_INVOICES_CB</code> || Envoi automatique d'email CB pour les factures
|-
| <code>STANCER_AUTO_MAIL_INVOICES_CB_MAILTYPE</code> || 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 <code>STANCER_CB_ORDER_PARTIAL_PAY</code> (pourcentage de 1 à 100)
* Configurable via <code>STANCER_CB_PROPAL_PARTIAL_PAY</code> pour les devis
* Le montant de l'acompte est calculé automatiquement : <code>total_ttc × pourcentage / 100</code>
* Les paiements partiels sont marqués avec un flag <code>partialPayment=1</code>
* Suivi des paiements multiples via un séquenceur (<code>SEQ={compteur}</code> dans le TAG)
 
=== 2. Paiement par prélèvement SEPA ===
 
==== 2.1 Création de mandat SEPA ====
 
La page publique <code>public/sepa-iban.php</code> 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 :'''
# Validation de l'IBAN via la bibliothèque <code>PHP_IBAN</code>
# Création du compte client Stancer si nécessaire
# Création/mise à jour de l'enregistrement <code>societe_rib</code> dans Dolibarr :
#* Label : <code>stancer-sepa-tst</code> (test) ou <code>stancer-sepa</code> (production)
#* RUM auto-généré via <code>BonPrelevement::buildRumNumber()</code>
#* Type FRST/RECUR (premier/récurrent)
# Enregistrement de l'IBAN chez Stancer via <code>stancerAddSEPAIfNeeded()</code>
# Génération optionnelle du PDF de mandat SEPA (si <code>STANCER_MANDATE_AUTO</code> activé)
# Signature électronique optionnelle via UpToSign (si <code>STANCER_MANDATE_AUTO_UPTOSIGN</code> activé)
 
==== 2.2 Flux de paiement SEPA ====
 
# Le système (ou l'utilisateur) déclenche un prélèvement SEPA via <code>stancerSEPAstartPay()</code>
# Validation du délai SEPA (configurable, par défaut 5 jours avant l'échéance)
# Vérification du montant maximum autorisé (<code>STANCER_SWITCH_SEPA_AMOUNT_MAX</code>)
# Validation de la date de paiement de la facture
# Création du paiement via l'API Stancer
# Sauvegarde dans <code>llx_stancer_stancer_payments</code>
 
==== 2.3 Configuration SEPA ====
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_PUBLIC_IBAN_PAGE</code> || Activer la page publique de saisie IBAN
|-
| <code>STANCER_PUBLIC_IBAN_PAGE_FORCE</code> || Forcer l'affichage de la page IBAN
|-
| <code>STANCER_MANDATE_AUTO</code> || Générer automatiquement le PDF du mandat SEPA
|-
| <code>STANCER_MANDATE_AUTO_UPTOSIGN</code> || Intégration signature électronique UpToSign
|-
| <code>STANCER_MANDATE_AUTO_UPTOSIGN_NOCLICK</code> || Redirection automatique vers la signature
|-
| <code>STANCER_DELAY_SEPA</code> || Délai en jours avant prélèvement (défaut : 5)
|-
| <code>STANCER_DELAY_SEPA_UPDATE_INVOICES</code> || Mettre à jour les dates de factures selon le délai
|-
| <code>STANCER_SWITCH_SEPA_AMOUNT_MAX</code> || Montant maximum pour un prélèvement SEPA
|-
| <code>STANCER_SWITCH_SEPA_TO_OTHER_BANK</code> || Basculer vers un autre compte bancaire au-delà du seuil
|-
| <code>STANCER_AUTO_MAIL_INVOICES_SEPA</code> || Email automatique pour les prélèvements SEPA
|-
| <code>STANCER_AUTO_MAIL_INVOICES_SEPA_MAILTYPE</code> || Modèle d'email SEPA
|-
| <code>STANCER_EMAIL_DPO</code> || Email du Délégué à la Protection des Données (RGPD)
|-
| <code>PRELEVEMENT_ICS</code> || Identifiant Créancier SEPA (ICS)
|}
 
==== 2.4 Génération de mandat PDF ====
 
Le module inclut un générateur PDF spécifique (<code>pdf_sepamandate_stancer</code>) 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 (<code>POST /refunds/</code>)
* Suivi des remboursements dans la table <code>llx_stancer_stancer_refunds</code>
* Liaison avec le paiement d'origine via <code>payment_id</code>
* Statuts : Brouillon (0), Validé (1), Annulé (9)
* Page de liste dédiée avec filtres et recherche (<code>stancer_refunds_list.php</code>)
* Détection des remboursements déjà effectués pour éviter les doublons
 
==== 3.2 Statuts de remboursement ====
 
{| class="wikitable"
! 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 (<code>GET /payouts/</code>)
* 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 ====
 
{| class="wikitable"
! 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 <code>stancer_import_check_reversements.php</code> permet d'importer et vérifier les relevés mensuels de Stancer au format CSV.
 
'''Processus d'import :'''
# Téléversement du fichier CSV avec le numéro de relevé
# Analyse automatique des en-têtes et mapping des colonnes
# Pour chaque opération (paiement, remboursement, litige) :
#* Vérification de l'existence de l'opération en banque (champ <code>num_chq</code>)
#* Validation des montants
#* Mise à jour du <code>num_releve</code>
# 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
# Vérification croisée : détection des écritures bancaires absentes du fichier d'import
# Totalisation des crédits et débits avec comparaison
 
=== 5. Statuts des paiements ===
 
{| class="wikitable"
! 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 (<code>stancer_payments_list.php</code>) ====
 
'''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 <code>stancerRefreshAllPayments()</code>, <code>stancerRefreshAllPaymentsFromDolibarr()</code> et <code>stancerRemoveOldDraftPayments()</code>)
* 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 (<code>stancer_payouts_list.php</code>) ====
 
'''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 (<code>stancer_refunds_list.php</code>) ====
 
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 (<code>public/paymentback.php</code>) ===
 
Page publique appelée par Stancer après que le client a complété son paiement. Aucune authentification requise.
 
==== 7.1 Flux de traitement ====
 
# '''Décodage des paramètres''' : déchiffrement Base64 du paramètre <code>s</code> contenant tag, source, ref, securekey, entity
# '''Récupération du paiement''' depuis la table Stancer par UUID ou session
# '''Vérification du statut''' via l'API Stancer (<code>GET /checkout/{id}</code>)
# '''Traitement carte bancaire''' : extraction des données de carte (marque, 4 derniers chiffres, nom, pays), création/mise à jour du mode de paiement
# '''Détection de doublons''' : recherche dans <code>llx_paiement</code> par <code>ext_payment_id</code> — affiche "Rechargement détecté" si doublon
# '''Mise à jour de l'enregistrement''' local via <code>fillDataFromApi()</code>
# '''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 (<code>stancer_thirdparty.php</code>) ===
 
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 :
 
{| class="wikitable"
! Mode !! Paramètre !! Description
|-
| Aucun || <code>STANCER_ADD_FEES = NONE</code> || Pas d'enregistrement automatique des frais
|-
| Par reversement || <code>STANCER_ADD_FEES = PAYOUT</code> || Frais enregistrés au niveau de chaque reversement
|-
| Par paiement || <code>STANCER_ADD_FEES = PAYMENT</code> || Frais enregistrés individuellement pour chaque paiement
|}
 
==== 9.2 Régularisation des écarts comptables (<code>admin/compta.php</code>) ====
 
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 (<code>STANCER_COMPTA_SEUIL_ECART</code>, ex. 0.05 EUR)
* Création d'écritures OD (Opérations Diverses) pour régulariser
* Deux lignes par écart :
*# Ligne compte fournisseur : débit/crédit du solde d'écart
*# Ligne compte d'écart (658xxx) : contrepartie
 
'''Configuration :'''
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_COMPTA_JOURNAL_OD</code> || Journal pour les écritures OD
|-
| <code>STANCER_COMPTA_ACCOUNT_ECART</code> || Compte comptable pour les écarts (ex. 658xxx)
|-
| <code>STANCER_COMPTA_SEUIL_ECART</code> || Seuil de régularisation (ex. 0.05 EUR)
|-
| <code>STANCER_COMPTA_SUPPLIER_ID</code> || 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 <code>llx_bank</code> 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 (<code>stancerBankLineDoesNotExists()</code>)
 
=== 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 :
 
{| class="wikitable"
! Hook !! Contexte d'intégration
|-
| <code>newpayment</code> || Création de paiement
|-
| <code>paymentlib</code> || Fonctions de la bibliothèque paiement
|-
| <code>invoicecard</code> || Fiche facture client
|-
| <code>invoicesuppliercard</code> || Fiche facture fournisseur
|-
| <code>ordercard</code> || Fiche commande
|-
| <code>propalcard</code> || Fiche devis / proposition commerciale
|-
| <code>formObjectOptions</code> || Options de formulaire
|-
| <code>thirdpartybancard</code> || Onglet compte bancaire du tiers
|-
| <code>printFieldListTitle</code> || En-têtes de colonnes dans les listes
|-
| <code>printFieldListValue</code> || Valeurs de colonnes dans les listes
|-
| <code>subscription</code> || Cotisations d'adhérents
|-
| <code>doncard</code> || Fiche don
|-
| <code>membercard</code> || Fiche adhérent
|-
| <code>bankline</code> || Ligne d'écriture bancaire
|}
 
'''Actions principales du hook <code>formConfirm</code> :'''
* <code>stancerCard</code> : affiche une popup de paiement CB avec QR code et lien de paiement
* <code>stancerSEPA</code> : 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 :
 
{| class="wikitable"
! Variable !! Description
|-
| <code>__STANCER_SEPA_RUM__</code> || Référence Unique de Mandat SEPA
|-
| <code>__STANCER_SEPA_DELAIS__</code> || Délai de prélèvement SEPA (en jours)
|-
| <code>__STANCER_SEPA_URL__</code> || Lien public vers la page de saisie IBAN
|}
 
=== 13. Modèles d'emails ===
 
Six modèles d'emails sont préconfigurés à l'installation :
 
{| class="wikitable"
! 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 :'''
<code>__REF__</code>, <code>__MYCOMPANY_NAME__</code>, <code>__MYCOMPANY_ADDRESS__</code>, <code>__MYCOMPANY_ZIP__</code>, <code>__MYCOMPANY_TOWN__</code>, <code>__DAY_TEXT__</code>, <code>__DAY__</code>, <code>__MONTH_TEXT__</code>, <code>__YEAR__</code>, <code>__AMOUNT_EXCL_TAX_FORMATED__</code>, <code>__STANCER_SEPA_DELAIS__</code>, <code>__USER_SIGNATURE__</code>, <code>__ONLINE_PAYMENT_URL__</code>
 
=== 14. Notifications automatiques ===
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_AUTO_MAIL_NOTIFICATIONS</code> || Activer les notifications email globales
|-
| <code>STANCER_AUTO_MAIL_NOTIFICATIONS_PAYMENT</code> || Notification à chaque paiement reçu
|-
| <code>STANCER_AUTO_MAIL_NOTIFICATIONS_PAYOUT</code> || Notification à chaque reversement reçu
|-
| <code>STANCER_AUTO_MAIL_NOTIFICATIONS_ON_NEW_CB_AND_SEPA</code> || Notification lors de l'enregistrement d'une nouvelle carte ou d'un nouveau mandat SEPA
|-
| <code>STANCER_AUTO_MAIL_INVOICES_ERROR</code> || Notification en cas d'erreur de paiement
|}
 
== Administration ==
 
=== Pages d'administration ===
 
Le module fournit 12 pages d'administration accessibles depuis le menu Stancer :
 
{| class="wikitable"
! Page !! Fichier !! Description
|-
| Configuration || <code>admin/setup.php</code> || Paramètres généraux, clés API, comptes bancaires, synchronisation
|-
| Carte bancaire || <code>admin/cb.php</code> || Configuration des paiements CB, 3DS, emails
|-
| SEPA || <code>admin/sepa.php</code> || Configuration des prélèvements SEPA, délais, montants max
|-
| Email || <code>admin/mail.php</code> || Configuration des modèles d'emails
|-
| Association || <code>admin/asso.php</code> || Activation pour les associations et adhérents
|-
| Comptabilité || <code>admin/compta.php</code> || Rapprochement comptable et régularisation des écarts
|-
| Test || <code>admin/test.php</code> || Interface de test de l'API (client, paiements, reversements)
|-
| À propos || <code>admin/about.php</code> || Informations sur le module
|-
| Logs || <code>admin/logs.php</code> || Visualisation des journaux de transactions
|-
| Extrafields Paiements || <code>admin/stancer_payments_extrafields.php</code> || Champs personnalisés pour les paiements
|-
| Extrafields Reversements || <code>admin/stancer_payouts_extrafields.php</code> || Champs personnalisés pour les reversements
|-
| Extrafields Remboursements || <code>admin/stancer_refunds_extrafields.php</code> || Champs personnalisés pour les remboursements
|}
 
=== Configuration générale ===
 
==== Clés API ====
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_IS_PROD</code> || Mode production (1) ou test (0)
|-
| <code>STANCER_TEST_PUBLIC_KEY</code> || Clé publique de test
|-
| <code>STANCER_TEST_PRIVATE_KEY</code> || Clé privée de test (masquée)
|-
| <code>STANCER_PROD_PUBLIC_KEY</code> || Clé publique de production
|-
| <code>STANCER_PROD_PRIVATE_KEY</code> || Clé privée de production (masquée)
|}
 
==== Comptes et utilisateurs ====
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_USER_ACCOUNT_FOR_ACTIONS</code> || Utilisateur Dolibarr pour les actions automatisées
|-
| <code>STANCER_BANK_ACCOUNT_FOR_PAYMENTS</code> || Compte bancaire pour l'enregistrement des paiements
|-
| <code>STANCER_BANK_MAIN_ACCOUNT_FOR_PAYOUTS</code> || Compte bancaire principal pour les reversements
|}
 
==== Synchronisation ====
 
{| class="wikitable"
! Paramètre !! Description !! Défaut
|-
| <code>STANCER_NUMBER_OF_ITEMS_TO_SYNC</code> || Nombre d'éléments par appel API || 200 (plage : 10-1000)
|-
| <code>STANCER_NB_DAYS_TO_SYNC</code> || Nombre de jours d'historique à récupérer || 31 (plage : 10-730)
|}
 
==== Divers ====
 
{| class="wikitable"
! Paramètre !! Description
|-
| <code>STANCER_MONTHLY_SUBSCRIPTION_FEE</code> || Abonnement mensuel (frais de TPE, défaut : 18 EUR)
|-
| <code>STANCER_AUTO_INVOICE_ON_PROPAL_PAID</code> || Créer automatiquement une facture quand un devis est payé
|}
 
=== Interface de test (<code>admin/test.php</code>) ===
 
Permet de vérifier le bon fonctionnement de l'API directement depuis Dolibarr :
 
# '''Vérification de la configuration''' : affiche le mode (PRODUCTION / TEST) et un aperçu de la clé publique
# '''Création de client''' : crée ou récupère un client de test, affiche le lien vers le dashboard Stancer
# '''Lecture de client''' : affiche les détails (identifiant, email, nom, mobile)
# '''Liste des paiements récents''' : affiche les 5 derniers paiements (identifiant, montant, statut, date)
# '''Liste des reversements récents''' : affiche les 5 derniers reversements
# '''Détail d'un paiement''' : informations détaillées incluant le masquage de carte (**** + 4 derniers chiffres)
 
=== Support des associations (<code>admin/asso.php</code>) ===
 
L'activation de Stancer pour les associations crée automatiquement trois champs supplémentaires sur les adhérents :
 
{| class="wikitable"
! Champ !! Type !! Description
|-
| <code>stancer_sepa_ref</code> || VARCHAR(32) || Référence du mandat SEPA de l'adhérent
|-
| <code>stancer_cb_ref</code> || VARCHAR(32) || Référence de la carte bancaire de l'adhérent
|-
| <code>stancer_account</code> || VARCHAR(32) || Identifiant du compte client Stancer (obligatoire)
|}
 
== API REST Stancer ==
 
Le module utilise un client REST intégré (<code>StancerApi</code>) 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 ===
 
# <code>stancerRefreshAllPayments()</code> : récupère les '''nouveaux''' paiements depuis l'API Stancer depuis la dernière synchronisation
# <code>stancerRefreshAllPaymentsFromDolibarr()</code> : vérifie le statut des paiements locaux '''non finalisés''' via l'API
# <code>stancerRemoveOldDraftPayments()</code> : supprime les paiements brouillon anciens (> 30 jours), sans appel API
 
=== Flux de synchronisation des reversements ===
 
# <code>stancerRefreshAllPayoutsFromStancer()</code> : récupère les reversements depuis l'API (mode production uniquement)
# Enchaîne avec la vérification locale si la première étape réussit
# Arrêt immédiat en cas d'erreur
 
== Objets métier supportés ==
 
Le module s'intègre avec les objets Dolibarr suivants :
 
{| class="wikitable"
! 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 :
 
{| class="wikitable"
! 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 ===
 
{| class="wikitable"
! Fichier !! Couverture
|-
| <code>StancerApiTest.php</code> || Client HTTP StancerApi
|-
| <code>StancerClassTest.php</code> || Classe principale Stancer
|-
| <code>StancerLibTest.php</code> || Fonctions de la bibliothèque partagée
|-
| <code>StancerPaymentsTest.php</code> || Modèle Stancer_payments
|-
| <code>StancerPayoutsTest.php</code> || Modèle Stancer_payouts
|-
| <code>StancerRefundsTest.php</code> || Modèle Stancer_refunds
|}
 
=== Tests d'intégration ===
 
{| class="wikitable"
! Fichier !! Couverture
|-
| <code>StancerClassIntegrationTest.php</code> || Intégration classe principale avec Dolibarr
|-
| <code>StancerLibIntegrationTest.php</code> || Intégration fonctions bibliothèque
|-
| <code>StancerPaymentsIntegrationTest.php</code> || Intégration paiements
|-
| <code>StancerPayoutsIntegrationTest.php</code> || Intégration reversements
|-
| <code>StancerRefundsIntegrationTest.php</code> || Intégration remboursements
|-
| <code>StancerTriggersIntegrationTest.php</code> || 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 <code>cap-rel/dolibarr-integration-sqlite</code>
* '''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 <code>STANCER_EMAIL_DPO</code>
* 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 <code>entity</code> 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 ==
 
{| class="wikitable"
! 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
|}
Eric.seigne
417

edits

Retrieved from "https://wiki.dolibarr.org/index.php/Special:MobileDiff/65459"

Navigation menu