États d’abonnement récupérables pour un SaaS

Un prestataire de paiement peut confirmer un paiement avec retard, envoyer le même événement plus d’une fois ou laisser une opération partiellement traitée. Par conséquent, « payé » et « avec accès » ne sont pas équivalents. Si l’autorisation d’un compte dépend directement de la dernière réponse reçue d’une API de paiement, une défaillance transitoire peut bloquer un client qui a bien payé ou activer un autre dont le paiement a finalement échoué.

Dans les états d’abonnement dans un SaaS PHP, l’objectif n’est pas de stocker une étiquette unique dans une table. Il s’agit de construire un processus récupérable : chaque décision doit disposer d’une preuve, d’un responsable, d’une transition valide et d’un moyen de se réconcilier lorsque de nouvelles données arrivent.

Définir les règles produit avant le modèle technique

Le modèle de données ne résout pas les ambiguïtés commerciales. Avant de concevoir des entités ou des webhooks, les équipes produit, finance et opérations doivent convenir de ce qui se passe dans chaque situation pertinente.

• Souscription : l’accès est-il accordé avant que le premier paiement soit confirmé, après une autorisation ou seulement après le règlement ?
• Renouvellement : quand la période de grâce commence-t-elle et quelles capacités sont conservées pendant celle-ci ?
• Impayé : y a-t-il des tentatives automatiques, des notifications, des restrictions partielles ou une suspension complète ?
• Résiliation : l’accès prend-il fin immédiatement ou à la fin de la période déjà souscrite ?
• Remboursement ou contestation : cela exige-t-il un blocage immédiat, une revue manuelle ou une révocation lorsqu’un résultat est confirmé ?
• Réactivation : restaure-t-elle exactement le plan précédent, crée-t-elle un nouveau cycle commercial ou exige-t-elle une validation opérationnelle ?

Il convient également de distinguer une résiliation demandée par le client d’une résiliation effective. La première exprime une intention ; la seconde modifie le droit d’accès futur. Les mélanger entraîne des interfaces confuses et des automatisations difficiles à corriger.

Séparer contrat, facturation et accès effectif

Une architecture maintenable représente au moins quatre concepts. Le compte identifie le titulaire et ses membres. Le contrat commercial décrit le plan, le prix convenu, la date de renouvellement et la décision de résilier. Le cycle de facturation représente une obligation concrète pour une période, son montant et son résultat. Enfin, les capacités activées matérialisent ce que le compte peut faire au sein du produit.

Cette séparation évite de transformer un prestataire de paiement en source unique de vérité pour l’ensemble du SaaS. Un cycle peut être en attente alors que le contrat reste valide grâce à une période de grâce. Parallèlement, un compte peut conserver un accès en lecture, sans pouvoir créer de nouvelles ressources. Les capacités permettent d’exprimer cette décision sans imposer une fausse opposition binaire entre actif et inactif.

En PHP, une application peut exposer un service d’autorisation qui consulte une projection locale des capacités, par exemple canCreateProject ou canExportData. Cette projection est mise à jour lorsque les faits commerciaux ou de facturation changent ; elle n’a pas besoin d’appeler le prestataire à chaque requête. Cela réduit la latence, la dépendance externe et la dispersion des conditions dans les contrôleurs, les files d’attente et les tâches planifiées.

Modéliser les transitions, les responsables et les preuves

Évitez un unique champ status avec des valeurs ajoutées au fur et à mesure que des incidents surviennent. Il est préférable de déclarer des états par agrégat et des transitions autorisées. Par exemple, un cycle de facturation peut passer de open à payment_pending, paid, failed, refunded ou disputed. Toute transition n’est pas réversible et n’importe quel acteur ne peut pas l’exécuter.

Chaque changement doit enregistrer la date, l’origine, l’identifiant externe lorsqu’il existe et la preuve. L’origine peut être un ordre interne, un webhook validé, une requête de rapprochement ou une action manuelle autorisée. Une correction du support ne doit pas écraser silencieusement l’historique : elle doit être enregistrée comme une décision distincte, avec un motif et l’opérateur responsable.

Priorité face à des informations contradictoires

Définissez quelle preuve prévaut. Un écran de redirection après le paiement ne devrait pas confirmer un cycle : il sert à informer l’utilisateur, et non à servir de preuve finale. Un webhook signé et vérifié apporte généralement un meilleur signal, mais il peut arriver tardivement. Une requête authentifiée auprès du prestataire lors du rapprochement peut clarifier des événements absents. Si deux sources divergent, le système doit être placé en révision ou dans un état en attente défini, et non choisir arbitrairement la donnée la plus récente.

Traiter les événements tardifs, dupliqués et incomplets

La réception d’un événement doit être idempotente. Enregistrez un identifiant stable de l’événement externe et un hash ou une référence de la charge utile pertinente. S’il est reçu à nouveau, répondez sans répéter l’effet métier. Cela est particulièrement important si un événement de paiement déclenche l’émission d’un document, l’extension de la période ou une notification.

Le traitement doit séparer la réception et l’application. D’abord, validez la signature, le schéma et la provenance ; ensuite, stockez durablement l’événement reçu ; enfin, traitez une tâche qui tente d’appliquer la transition. Si le processus s’arrête après la persistance de l’événement, une file d’attente ou un processus de récupération peut le reprendre. S’il échoue avant la persistance, le rapprochement devra découvrir l’écart en comparant les cycles internes avec la source externe.

événement reçu → validation → enregistrement durable → application idempotente
                                      ↓
                              nouvelle tentative ou rapprochement

Ne supposez pas d’ordre de livraison. Un remboursement peut arriver avant une confirmation tardive du paiement initial. Les règles doivent évaluer l’état actuel, les références d’opération et la séquence connue, en laissant les cas impossibles ou ambigus dans une file de revue. Appliquer aveuglément « le dernier événement reçu » est une cause fréquente d’autorisations erronées.

Rapprochement et autorisations comme projection contrôlée

Le rapprochement périodique n’est pas un correctif ; il fait partie de la conception. Il doit repérer les cycles ouverts depuis trop longtemps, les paiements confirmés hors du système, les événements enregistrés sans être traités, les références externes dupliquées et les capacités qui ne correspondent pas au contrat en vigueur. Lorsqu’un écart est détecté, enregistrez le constat et appliquez une transition traçable, au lieu de mettre directement à jour les champs.

La projection des capacités doit comporter des règles explicites. Par exemple, un contrat en vigueur avec un cycle arrivé à échéance mais encore dans la période de grâce peut maintenir les fonctions essentielles ; à la fin de la période de grâce, il peut retirer les opérations d’écriture. Lorsqu’un paiement tardif est confirmé, le système réactive les capacités prévues pour le plan et conserve l’historique de la restriction antérieure.

Un cache des autorisations peut être utile, mais il nécessite une invalidation lorsque la projection change et une limite de validité. L’autorisation critique ne doit pas non plus reposer uniquement sur des données stockées dans le navigateur. Le serveur doit décider à partir de la capacité en vigueur et du bon périmètre de compte, d’utilisateur et de ressource.

Backoffice, audit et tests de récupération

L’équipe de support doit pouvoir voir, sans modifier des enregistrements de base de données, le contrat, les cycles, les événements externes, les transitions appliquées, les capacités actuelles et les actions manuelles. Elle doit pouvoir demander un rapprochement, réessayer le traitement d’un événement en toute sécurité et ouvrir une revue. Les corrections qui modifient l’accès ou le solde requièrent des autorisations différenciées, un motif obligatoire et un journal d’audit.

Testez le flux comme une séquence de défaillances, et non seulement comme un paiement correct. Incluez un renouvellement confirmé, un paiement incertain, des doublons, des événements hors ordre, un remboursement, une résiliation en fin de période et une réactivation. Vérifiez à la fois le résultat final et qu’aucune nouvelle tentative ne crée deux périodes, deux documents ou une double extension des autorisations.

Un cas hypothétique : un cycle arrive à échéance, le paiement reste en attente et le compte entre en période de grâce avec des capacités limitées. Le webhook de confirmation n’est pas traité en raison d’une interruption temporaire, mais l’événement reste enregistré. Une nouvelle tentative idempotente confirme le cycle, prolonge le contrat et recompose les capacités. Si l’événement n’était pas arrivé, le rapprochement trouverait l’opération externe confirmée et générerait la même transition avec sa propre preuve.

Signaux d’alerte et liste de vérification

Mesurez les comptes dont le contrat et les capacités sont incohérents, les cycles échus sans décision, les événements non traités, les nouvelles tentatives épuisées, les écarts détectés par rapprochement et la fréquence des changements manuels. Une hausse des corrections manuelles indique généralement des règles insuffisantes, et pas seulement un problème opérationnel.

• Le contrat, le cycle de facturation et les capacités sont-ils des entités séparées ?
• Chaque transition a-t-elle un acteur, une preuve, une date et un motif ?
• Les événements externes sont-ils idempotents et enregistrés avant d’être appliqués ?
• Existe-t-il un rapprochement capable de récupérer des opérations incomplètes ?
• Les autorisations sont-elles calculées à partir d’une projection locale, et non d’une réponse de paiement en temps réel ?
• Le support peut-il enquêter et corriger avec un audit, sans changements directs en production ?
• Les tests couvrent-ils les retards, les doublons, le désordre et les contradictions ?

Un modèle récupérable n’élimine pas les défaillances externes. Il les rend détectables, circonscrites et corrigeables sans transformer un incident de facturation en perte de contrôle sur l’accès au produit.