Imaginez un paiement validé à la caisse, mais dont la mise à jour de la commande échoue. Le client voit une erreur et réessaie. Pendant ce temps, le support dispose d'un enregistrement de transaction, l'entrepôt n'a aucune commande confirmée, et la finance doit savoir si le client doit quelque chose.

Quel système devrait résoudre la situation ? Ce type d'incident est celui où les décisions d'architecture deviennent visibles : lorsque la responsabilité n'est pas définie, chaque occurrence reçoit un correctif improvisé, et ces correctifs ont tendance à s'accumuler là où ils sont les plus faciles à écrire.

Une architecture devrait répondre à cette question avant que la première transaction n'atteigne la production. Sinon, le code de paiement absorbe progressivement la récupération des commandes, les règles d'abonnement, les ajustements de facture et les décisions d'exécution.

Le modèle de responsabilité décrit ci-dessous offre un point de départ pratique : garder le gateway concentré sur la communication avec le prestataire, donner aux opérations de paiement leur propre foyer, et laisser les décisions commerciales à la facturation et aux commandes.

Commencer par quatre responsabilités, pas trois

Pour cette conception, distinguez le gateway de paiement du service de paiement au sens plus large. Le modèle utilise quatre frontières logiques couvrant le gateway, le service de paiement, la facturation et les commandes.

Traitez-les comme des frontières de responsabilité, et non comme une instruction de déployer quatre microservices. Commencer par des modules au sein d'une même application convient parfaitement si cela correspond à l'équipe. Dans tous les cas les responsabilités doivent être rendues explicites.

Lors de la revue d'une architecture de gateway de paiement, associez le diagramme de composants à une carte des décisions : qui décide du montant, qui demande l'encaissement, qui enregistre le résultat, et qui autorise l'action métier suivante ?

Garder le gateway proche du prestataire

Donnez au gateway un contrat étroit. Il doit accepter une opération de paiement prise en charge, la traduire dans le format du prestataire et renvoyer un résultat que le service de paiement peut interpréter.

Cette isolation a une motivation pratique : les prestataires de paiement diffèrent par leurs API, leurs schémas d'authentification, leurs formats de champs et leurs mécanismes de notification, et la consolidation de cette variation dans une seule couche protège le reste du système des spécificités du prestataire.

Confiez-lui des responsabilités telles que :

• La validation de la requête destinée au prestataire
• L'authentification de la communication avec le prestataire
• La traduction des champs internes en champs spécifiques au prestataire
• La vérification des notifications entrantes du prestataire
• Le mappage des réponses tout en conservant les détails utiles du prestataire

La connaissance produit reste hors de ce contrat. Le gateway n'a pas besoin de comprendre les niveaux de fidélité, l'éligibilité à la livraison, les périodes de grâce des abonnements ni les offres groupées promotionnelles. Transmettez-lui le montant approuvé, la devise, la référence de paiement et les informations requises sur le moyen de paiement — pas les règles qui ont produit ces éléments.

Une question de revue utile : modifier la politique de retour nécessiterait-il de modifier le code du gateway ? Si oui, repensez la frontière.

Donner aux opérations de paiement un responsable distinct

Les tentatives de paiement et leurs résultats appartiennent au service de paiement. Pour chaque tentative, enregistrez un identifiant interne, les références pertinentes du prestataire, le montant demandé, la devise, le type d'opération et l'état. Conservez suffisamment d'historique pour examiner ce qui a été demandé et ce qui a réellement été confirmé.

Évitez de réduire le modèle à un simple indicateur « payé ». Définissez plutôt les distinctions dont vos workflows ont besoin, y compris les résultats non résolus. La communication avec le prestataire est parfois réellement incertaine — les dépassements de délai, les notifications tardives et les mises à jour hors ordre sont courants — le modèle d'état doit donc laisser place à l'ambiguïté plutôt que de réduire chaque résultat à un succès ou un échec.

Concevez explicitement pour cette séquence hypothétique : le service de paiement demande une autorisation, la requête atteint le prestataire, et la réponse est perdue. L'application doit alors décider de la suite. Un dépassement de délai ne doit jamais déclencher automatiquement un nouveau prélèvement. Exigez que le service de paiement résolve ou gère en toute sécurité la tentative initiale avant qu'une autre opération ne soit autorisée.

Deux types de relance doivent également être distingués :

• Relance technique : répétition de la communication pour la même opération prévue, selon des règles de sécurité définies.
• Relance d'encaissement : nouvelle tentative de recouvrement d'un solde impayé.

Confiez la gestion des relances techniques à la conception de l'intégration de paiement. La facturation détermine le calendrier et l'éligibilité de l'encaissement, le service de paiement exécutant la tentative approuvée.

Laisser la facturation décider de ce qui est dû

La facturation possède l'obligation financière : le calcul des frais, la facture, les avoirs et le solde restant. Pour un produit par abonnement, les règles de changement de formule, de proratisation, de périodes de facturation et de calendriers d'encaissement appartiennent ici.

Exigez que la facturation émette chaque demande d'encaissement avec un montant explicite, une devise et une référence à l'obligation en cours de recouvrement. Le service de paiement rapporte le résultat, et la facturation détermine ensuite comment ce résultat affecte le solde.

Prenons une facture hypothétique de 100 $ assortie d'un avoir de 30 $. La facturation devrait demander les 70 $ restants. On ne devrait jamais demander au gateway de reconstituer ce calcul à partir des métadonnées d'abonnement.

L'enjeu croît avec la complexité tarifaire : chaque calcul qui atterrit dans le mauvais composant devient une logique qui devra ensuite être trouvée, migrée et réconciliée entre les systèmes.

La même discipline s'applique après un remboursement. Les enregistrements de paiement établissent ce qui a été retourné via le prestataire ; la facturation détermine quelle facture ou quel ajustement de solde correspond à ce retour.

Laisser les commandes décider du sort de l'achat

Les décisions d'exécution et de cycle de vie de l'achat restent dans le domaine des commandes. Le service de paiement doit publier un résultat de paiement, pas une instruction d'entrepôt, et le workflow de commande doit interpréter ce résultat avec ses autres exigences. Interpréter le résultat est un jugement métier autant que technique, car un même paiement confirmé peut avoir un poids différent selon les modèles d'exécution.

Un exemple de règle d'exécution explicite : ne libérer la commande que lorsque la condition de paiement requise est satisfaite, le stock est alloué et toute revue nécessaire est terminée. La condition de paiement doit être choisie en fonction du modèle économique et jamais enfouie dans un gestionnaire de réponses du prestataire.

Les annulations méritent la même séparation. Les commandes décident si l'annulation est permise et ce qu'il advient de l'achat, puis demandent l'opération de paiement appropriée via le service de paiement. Évitez une commande « annuler » surchargée qui pourrait signifier annuler la commande, libérer une autorisation, rembourser un paiement ou résilier un abonnement. Nommez chaque action avec précision.

Coordonner les remboursements sans donner à un système toutes les tâches

Un workflow de remboursement est un bon test de la solidité des frontières. Supposons qu'un client retourne un article d'une commande de trois articles. Structurez le workflow de sorte que :

• Le composant des retours ou des commandes approuve le retour.
• Le responsable désigné du calcul commercial détermine le montant remboursable.
• Le service de paiement vérifie l'historique des paiements et les limites d'opération applicables.
• Le gateway soumet la requête au prestataire.
• Le service de paiement enregistre le résultat confirmé ou non résolu.
• La facturation et les commandes mettent à jour leurs propres enregistrements en conséquence.

Attribuez un responsable unique à chaque calcul. La facturation et les commandes ne devraient pas calculer indépendamment des montants de remboursement différents et laisser les paiements choisir entre eux.

Gardez « remboursement demandé » distinct de « remboursement confirmé ». Si le résultat du prestataire est non résolu, conservez cette incertitude et offrez une voie d'investigation plutôt que de marquer l'ensemble du workflow comme terminé.

Faire de la récupération une partie du contrat

Chaque opération transalière devrait spécifier davantage que la réponse en cas de succès. Documentez :

• Comment les requêtes répétées sont identifiées
• Quel composant possède l'état faisant autorité
• Comment les notifications tardives ou dupliquées sont gérées
• Ce qui se passe lorsque le composant suivant est indisponible
• Comment le personnel enquête sur les résultats non résolus
• Quelles actions peuvent être relancées en toute sécurité

Pour les requêtes répétées en particulier, les prestataires proposent généralement des mécanismes d'idempotence conçus précisément à cet effet, permettant de soumettre à nouveau la même opération sans qu'elle soit exécutée deux fois.

Donnez à chaque domaine ses propres identifiants et reliez-les explicitement : ID de commande, ID de facture, ID de paiement, ID de tentative et référence du prestataire. N'obligez pas un seul identifiant à représenter toutes les relations.

Le personnel de support peut recevoir une chronologie combinée, mais les corrections doivent rester sous le contrôle du composant responsable. Un tableau de bord pratique ne doit pas devenir une permission d'écraser l'historique des paiements ou de modifier silencieusement les soldes des factures.

Tester les frontières avec les changements métier

Avant d'approuver la conception, parcourez plusieurs changements :

• Ajouter un prestataire de paiement sans modifier les règles tarifaires.
• Modifier le calendrier d'encaissement des abonnements sans toucher aux adaptateurs du gateway.
• Introduire des retours partiels sans réécrire la gestion des notifications du prestataire.
• Modifier la politique d'exécution sans altérer les définitions d'état des paiements.

Traitez les changements inter-composants inattendus comme des signaux de revue. Une certaine coordination est légitime ; un couplage inexpliqué mérite de l'attention.

La dérive des responsabilités ne s'annonce presque jamais ; elle s'accumule un changement opportuniste à la fois. Relire ces parcours chaque fois qu'un nouveau prestataire, un nouveau moyen de paiement ou un nouveau modèle tarifaire est introduit maintient les frontières explicites bien après la revue de conception initiale.

Le gateway doit s'arrêter à la communication de paiement avec le prestataire. Le service de paiement doit posséder l'exécution et les preuves des paiements. La facturation doit posséder les obligations et les soldes. Les commandes doivent posséder l'achat et son exécution.

Inscrivez ces responsabilités dans les interfaces, les procédures de récupération et la responsabilité des équipes. Un diagramme, à lui seul, ne les maintiendra pas séparées.