Opérations de facturation

Audience

Cet article s'adresse aux opérateurs de la plateforme GCM. Les administrateurs d'église devraient consulter le module Dons propre à leur organisation pour les dons de leur congrégation — cette page concerne les paiements d'abonnement à GCM.

L'onglet Opérations de facturation (/platform/billing-ops) est là où le personnel résout tout ce qui touche à l'argent : une carte refusée ce matin, un client qui veut que sa dernière facture soit remboursée, un renouvellement à reporter d'une semaine, un PDF de facture manquant. Tout ici est conditionné par superadmin ou platform_admin et chaque écriture atterrit dans platform_audit_log avec une raison obligatoire.

La bannière de santé du cron

Si vous voyez un jour une bannière rouge en haut indiquant "La facturation récurrente n'est pas planifiée", arrêtez-vous et corrigez-le avant de faire quoi que ce soit d'autre. Cela signifie que le job charge_recurring n'est pas enregistré dans pg_cron, donc aucun renouvellement ne se déclenchera tant que quelqu'un n'aura pas relancé la migration cron. La bannière ne s'affiche que lorsque le RPC du tableau de bord rapporte cron_health.charge_recurring_scheduled = false — c'est l'alerte la plus importante de la page.

Les cinq cartes récapitulatives

• MRR estimé — le même chiffre que le bandeau KPI des Organisations. Formaté en USD.
• Dû aujourd'hui — organisations avec subscription_status = 'active' et next_billing_date <= today. Elles seront facturées au prochain tic de cron.
• En retard — subscription_status = 'past_due'. Le compteur de relance de chacun est visible dans le tableau.
• Tentatives échouées sur 7j — payment_sessions avec statut d'erreur terminale au cours de la semaine dernière. Un pic ici signifie généralement une panne de passerelle ; vérifiez le statut chez le fournisseur de passerelle.
• Remboursements sur 30j — nombre de lignes payment_history avec status = 'refunded' au cours des 30 derniers jours.

Les quatre sous-onglets

Abonnements

La vue par défaut. Chaque organisation avec des données de facturation, avec son plan, son statut, sa prochaine date de facturation, sa posture de relance, la carte au dossier et le dernier paiement réussi. Les quatre boutons d'action par ligne sont :

• Détails — ouvre la feuille de droite avec une décomposition plus complète, les derniers paiements et les tentatives récentes de la passerelle pour cette organisation seule.
• Roue paramètres — ouvre la boîte de dialogue Modifier l'abonnement (voir ci-dessous).
• Icône d'actualisation — ouvre la boîte de dialogue Renouveler / réessayer.
• Ouvrir — ferme cet onglet et pousse la feuille détaillée standard de l'organisation depuis la page Organisations, pour que vous puissiez basculer en usurpation d'identité ou en gestion du personnel.

Paiements

Le registre des paiements. Chaque ligne dans payment_history à travers la plateforme, du plus récent au plus ancien. Cliquez sur l'icône de fichier pour (re)générer le PDF de facture — cela appelle adminGenerateInvoice qui écrit une URL signée dans la ligne. Cliquez sur l'icône de rotation inverse pour ouvrir la Modale de remboursement standard ; c'est le même composant que le flux de dons par organisation utilise, donc les remboursements partiels / complets / hors plateforme fonctionnent tous de la même manière.

Un remboursement n'est disponible que lorsque le paiement est en statut approved et que le montant est supérieur à zéro. Les paiements remboursés et en attente grisent le bouton.

Tentatives

Une vue caviardée de payment_sessions — chaque tentative de transaction, réussie ou non, avec le code de réponse de la passerelle et le message. C'est le premier endroit où regarder quand "le client dit avoir été facturé deux fois" : chaque tentative a un order_identifier que vous pouvez corréler avec le tableau de bord de la passerelle.

Frise chronologique

Un flux d'audit défilant restreint aux actions de facturation : modifications d'abonnement, renouvellements déclenchés, remboursements traités, factures générées. C'est une tranche filtrée de platform_audit_log jointe aux noms d'organisations — utile quand un client demande "qu'est-ce qui a changé sur notre compte entre mardi et vendredi ?".

Modifier un abonnement

La boîte de dialogue Modifier l'abonnement est le panneau de surcharge. Chaque champ est modifiable mais Raison est obligatoire (minimum 3 caractères) et est ajoutée à la ligne d'audit aux côtés de votre e-mail. Champs :

• Plan et Statut — mêmes valeurs d'énumération que l'onglet Organisations.
• Fin d'essai / Prochaine facturation / Début du cycle de facturation — sélecteurs de date. Utilisés pour pousser ou ramener la prochaine facturation.
• Jour du cycle de facturation — 1-31. Si le jour de renouvellement diffère de la date de début (par exemple inscription le 14 mais facturation le 1er).
• Limite de membres — entier libre. À utiliser quand une montée de plan n'est pas appropriée mais que le client a besoin de marge.
• Nombre de relances / Date de relance — mettez à zéro et effacez la date pour stopper la tempête de relances sur une carte refusée.
• Pause jusqu'à — fixe la date de reprise quand un client demande à suspendre le service.
• Envoyer l'e-mail au client — interrupteur. Désactivé par défaut ; activez-le quand le changement est visible par le client (par exemple rétrogradation de plan).

L'enregistrement appelle adminUpdateSubscription qui écrit à la fois les nouvelles colonnes et insère un événement d'audit.

Renouveler ou réessayer

La boîte de dialogue Renouveler / réessayer a deux modes :

• Aperçu uniquement (par défaut) — exécute la logique de renouvellement en essai à blanc. La passerelle n'est pas appelée ; la réponse montre ce qui se passerait et est déversée dans un bloc <pre> pour inspection. À utiliser chaque fois que vous n'êtes pas sûr de l'état d'une carte.
• Facturer maintenant — invoque réellement la passerelle avec le jeton de paiement stocké. Le bouton devient rouge pour que vous ne puissiez pas mal cliquer. Un champ de raison est obligatoire et est imprimé sur la ligne d'historique de paiement résultante.

La boîte de dialogue appelle adminTriggerRenewal avec un nouveau requestId pour qu'un double-clic ne puisse pas double-facturer — la fonction déduplique côté serveur sur cette clé.

Facturations hors cycle

Facturer en dehors du jour normal de facturation est correct, mais cela décale la cadence de renouvellement : la prochaine next_billing_date sera calculée à partir d'aujourd'hui, et non à partir de la date précédemment planifiée. Si vous voulez garder le cycle aligné, remettez manuellement next_billing_date dans la boîte de dialogue Modifier l'abonnement après la réussite de la facturation.

Remboursements

La Modale de remboursement est partagée avec le flux de dons par organisation mais fonctionne toujours en mode administrateur de plateforme ici. Vous pouvez émettre :

• Remboursement par passerelle — appelle l'endpoint de remboursement de la passerelle avec l'ID de transaction original. Les fonds reviennent sur la carte du client.
• Remboursement hors plateforme — enregistre une ligne de remboursement sans toucher à la passerelle. À utiliser lorsque vous avez déjà remboursé le client par virement / chèque et que vous avez juste besoin que le registre le reflète. Les champs manualMethod et referenceNumber sont obligatoires pour que l'auditeur puisse le tracer.

Un remboursement réussi écrit dans payment_history (statut devient refunded), met à jour la ligne payment_sessions associée et insère une entrée platform_audit_log avec la raison.

Situations courantes

"La carte du client a été refusée trois nuits de suite et il veut savoir pourquoi." Ouvrez Détails sur sa ligne, faites défiler jusqu'aux tentatives récentes et lisez le message de réponse de la passerelle. 99 % du temps, c'est INSUFFICIENT_FUNDS, EXPIRED_CARD ou DO_NOT_HONOR. Ouvrez le compte de l'organisation (usurpation d'identité) et faites-leur mettre à jour la carte via la page de facturation côté client.

"Nous devons repousser le renouvellement d'une semaine pour que le client puisse faire un virement." Modifier l'abonnement -> mettez next_billing_date à aujourd'hui + 7. Remettez billing_retry_count à 0 et effacez billing_retry_at pour que la tempête de relances s'arrête. Raison : "arrangement virement, J-7".

"Le PDF de facture est manquant." Onglet Paiements -> trouvez la ligne -> cliquez sur l'icône de fichier. adminGenerateInvoice re-rend le PDF, le téléverse dans le bucket des factures et imprime l'URL signée sur la ligne.

"Le cron de ce matin n'a pas tourné." Vérifiez d'abord la bannière rouge. Si elle ne s'affiche pas mais que vous le soupçonnez, regardez le chiffre Dû aujourd'hui une heure après l'heure habituelle — s'il n'a pas baissé, le job ne s'est pas déclenché. La solution est de relancer la migration pg_cron ; voir le runbook dans docs/runbooks/.