Les campagnes de dons (PayPal)

En bref. Les dons passent par ton compte PayPal Business. Une campagne n'encaisse que si elle est ouverte, validée et dans ses dates. Les dons ne dépendent d'aucune licence.

Brancher PayPal #

1. Il te faut un compte PayPal Business (un compte personnel se convertit gratuitement).
2. Sur developer.paypal.com, Apps & Credentials : choisis Live (vrais paiements) ou Sandbox (tests).
3. Create App, type Merchant. Copie le Client ID et le Secret key.
4. Dans Agora : Administration → Configuration → Paiements, colle-les en choisissant le même Environnement, puis Enregistrer.

Aucun webhook à configurer pour encaisser : l'encaissement se fait au retour du donateur. Ces mêmes identifiants servent aussi aux ventes de la concession en argent réel. Pour qu'Agora reprenne un remboursement fait chez PayPal, ajoute le webhook ci-dessous (facultatif, recommandé).

Remboursements faits chez PayPal (webhook) #

Sans webhook, un don remboursé dans le tableau de bord PayPal reste Reçu dans Agora. Pour qu'Agora reprenne un remboursement, une rétrofacturation ou un litige :

1. Sur developer.paypal.com → ton application → Webhooks → Add Webhook.
2. Colle l'adresse https://ton-site/api/paypal/webhook (le « ? » du champ ID du webhook la donne, avec ton adresse).
3. Coche Payment capture refunded, reversed, denied, completed, Customer dispute created et resolved. L'événement completed sert aux ventes de la concession : un paiement PayPal resté « en attente » puis encaissé est livré tout seul (voir Relivrer, rembourser, reprendre un véhicule).
4. Recopie l'ID du webhook dans le champ du même nom de Administration → Configuration → Paiements. Sans cet ID, Agora refuse tout ce qui arrive à cette adresse.

L'ID est propre à un environnement (Sandbox ou Live) : quand tu changes d'environnement, Agora efface l'ancien ID et te le dit. Colle celui du webhook du nouvel environnement. Sous le champ, Agora affiche l'état du webhook : dernier événement valide reçu, ou, en rouge, événements refusés (ID faux ou mauvais environnement).

Chaque événement est vérifié par PayPal lui-même (signature) et traité une seule fois :

• un don remboursé passe à Remboursé et sort des totaux de la campagne (un refus d'un don jamais encaissé le passe à Échoué) ;
• une vente de la concession payée par PayPal est marquée remboursée, le stock revient et le véhicule est repris : voir Relivrer, rembourser, reprendre un véhicule ;
• un remboursement partiel d'un don réduit le montant compté : le don reste Reçu, mais les totaux (page Dons, accueil) n'en comptent plus que la part non rendue, au prorata du montant net encaissé. Plusieurs remboursements partiels s'additionnent, et rembourser le total revient au remboursement complet ci-dessus. La liste des dons affiche Remboursé en partie : … ;
• un remboursement partiel d'une vente de la concession note le montant rendu sur la ligne de la vente et prévient les administrateurs, mais ne reprend jamais le véhicule : voir Relivrer, rembourser, reprendre un véhicule ;
• un litige ouvert ne change rien (l'argent est seulement retenu), mais l'administrateur est prévenu et le geste est consigné au journal d'administration.

Le montant, la devise et la capture d'un remboursement partiel sont relus chez PayPal. Au moindre doute (devise différente, total qui atteint ou dépasse le montant payé, don jamais encaissé…), rien n'est changé et une notification « à vérifier dans PayPal » part. Chaque remboursement n'est compté qu'une fois, même si PayPal le renvoie.

Si rien n'apparaît après un remboursement : Un remboursement fait chez PayPal n'apparaît pas.

Créer une campagne #

Dons → Nouvelle campagne :

La campagne d'exemple #

L'installation crée une campagne « Financer le serveur » à valider : elle n'apparaît pas sur la page Dons et n'accepte aucun paiement tant que tu ne l'as pas relue. Modifie-la puis Enregistrer, ou clique sur Valider telle quelle.

Suivre les dons #

La liste Dons reçus (un volet de la page Dons, réservé aux administrateurs) montre montant, donateur, date et statut (En attente (PayPal), Reçu, Remboursé, Échoué). Le nom d'un don anonyme n'est jamais affiché, même à toi ; un donateur non connecté apparaît comme « Visiteur non connecté ». Les deux listes de filtre (campagne, statut) s'appliquent dès que tu choisis, sans bouton.

Si le serveur exige la 2FA du staff et que la tienne manque, la page Dons te montre l'écran qui t'explique quoi faire au lieu de ces outils d'administration (comme le reste de l'administration) ; le public, lui, voit toujours les campagnes.

L'estimation en autre devise vient des taux de la Banque centrale européenne, gardés une journée. Si la BCE est injoignable depuis ton serveur, l'estimation disparaît et Agora ne réessaie que toutes les 10 minutes.

Exporter en CSV télécharge un fichier dons_AAAA-MM-JJ.csv qui respecte les filtres choisis : date, campagne, montant, devise, statut, donateur, message, référence PayPal, montant compté et devise comptée. Points à savoir :

• l'export est réservé aux administrateurs (avec la 2FA du staff si elle est exigée) et il est consigné au journal d'administration ;
• il s'arrête à 20 000 lignes (les plus récentes d'abord) : un fichier coupé est nommé dons_AAAA-MM-JJ_partiel.csv et la coupure est notée au journal d'administration. Filtre alors par campagne ou par statut pour récupérer le reste ;
• le nom d'un don anonyme n'y figure pas non plus.

Le total d'une campagne (collecté, barre de progression, paliers) n'additionne que les dons reçus, selon le montant encaissé par PayPal dans la devise de la campagne. Un donateur peut payer dans une autre devise proposée par le formulaire : si PayPal convertit le don dans la devise de la campagne, le montant converti est compté (ligne « Compté : … » dans « Dons reçus »). Si PayPal l'encaisse dans une autre devise (par exemple un compte PayPal tenu dans une autre devise), le don est marqué Autre devise, reste dans la liste et l'export, mais n'entre pas dans le total ; la page de remerciement le dit aussi au donateur. Changer la devise d'une campagne qui a déjà des dons ne convertit rien.

Quand PayPal ne répond pas (erreur 5xx, délai dépassé) #

Chaque appel à PayPal est limité à 10 secondes. Une panne de PayPal ne casse jamais la page :

• Au moment de donner : si PayPal ne peut pas ouvrir la commande (panne, erreur 5xx, clés refusées), le donateur lit « Le paiement n'a pas pu être ouvert chez PayPal. Réessaie dans un moment. » sur la page Dons. Rien n'est prélevé et aucun don n'est enregistré. Le détail technique part dans les rapports d'erreurs (page Administration → Erreurs). Si c'est ton cas à chaque essai, vérifie le Client ID, le Secret et l'Environnement dans Administration → Configuration → Paiements.
• Au retour du paiement : si PayPal est en panne au moment où le donateur revient sur Agora, il voit « Paiement non finalisé ». Le don reste En attente (PayPal), il n'est pas marqué Échoué. Quand PayPal répond de nouveau, rouvrir ce même lien de retour (page « Paiement non finalisé » rechargée, ou lien de l'historique du navigateur) relance l'encaissement, sans risque de doublon. Seul un refus définitif de PayPal passe le don à Échoué.
• Pour l'encaissement, il n'y a pas de webhook : c'est Agora qui encaisse (le « capture » de PayPal) au retour du donateur : tant que cette étape n'a pas eu lieu, PayPal n'a rien prélevé. Un donateur qui ferme l'onglet avant la page de remerciement laisse donc un don En attente (PayPal) sans avoir été débité ; s'il veut donner, il recommence.

Autres refus que le donateur peut lire : « Trop de tentatives de don » (10 par heure et par adresse), « Campagne indisponible » (fermée, à valider, hors dates, terminée ou archivée), « Le don minimum est de … » et « Le don maximum est de … » (100 000 par don).

Terminer ou archiver #

• Terminer ferme la campagne aux dons ; Rouvrir la remet en service.
• Archiver la masque du public (accueil et page Dons) et la range dans Archivées ; Désarchiver l'annule à tout moment.
• Une campagne ne se supprime plus, et les dons reçus ne s'effacent jamais : ils font la comptabilité du serveur.
• Les dates se lisent dans le fuseau du serveur : une campagne ouvre à 00:00 le jour de début et ferme à 23:59 le jour de fin. Le fuseau se règle dans MDT → Configuration.

Prévenir un salon Discord #

Aucun événement de webhook n'existe pour les dons. Les campagnes restent visibles sur la page Dons et dans un bloc de l'accueil.