Construire un moteur de reversements et de litiges pour une plateforme wallet

La plupart des plateformes wallet gèrent bien le cas nominal. Un utilisateur initie un transfert, les fonds bougent, les deux soldes se mettent à jour correctement. La complexité d'ingénierie qui s'accumule silencieusement au fil du temps est le cas non-nominal : que se passe-t-il quand une transaction doit être reversée, quand un utilisateur conteste un débit, quand un marchand revendique des fonds qu'il n'a jamais reçus, ou quand une ordonnance réglementaire exige un gel puis un retour de fonds.

Ces scénarios sont traités de façon incohérente sur la plupart des plateformes wallet parce qu'ils n'ont pas été conçus dès le départ. Le résultat est une collection de processus manuels, de corrections de bases de données ad hoc, et d'exceptions de réconciliation qui deviennent de plus en plus coûteuses à gérer à mesure que le volume augmente.

Cet article couvre l'architecture d'un moteur de reversements et de litiges qui traite ces cas correctement, de façon cohérente, et à grande échelle.

Pourquoi les reversements ne sont pas l'inverse de la transaction originale

L'erreur la plus courante dans la conception des reversements est de traiter un reversement comme le miroir de la transaction originale. La transaction originale a débité le wallet A et crédité le wallet B, donc le reversement crédite le wallet A et débite le wallet B. Simple.

Cela échoue en pratique pour plusieurs raisons.

Le délai entre la transaction originale et le reversement n'est pas nul. Dans cet intervalle, le destinataire a pu dépenser les fonds. Débiter le wallet B pour le montant du reversement quand le wallet B ne détient plus ces fonds crée un solde négatif. Si la plateforme prévient les soldes négatifs - ce qu'elle devrait faire - le reversement échoue. L'émetteur original attend des fonds qui ne peuvent pas être retournés parce que le système ne peut pas traiter le débit.

Le bon modèle est de traiter un reversement comme une nouvelle transaction à part entière, pas comme un undo de l'originale. Le reversement crée de nouvelles entrées de ledger avec leurs propres horodatages, leurs propres clés d'idempotence, et leur propre machine d'états. Le lien entre le reversement et la transaction originale est une référence, pas un inverse mécanique. La logique métier pour ce qui se passe quand un reversement ne peut pas se compléter - parce que le destinataire n'a pas de fonds suffisants - est une préoccupation distincte de la transaction de reversement elle-même.

La machine d'états du reversement

Un reversement n'est pas binaire. Il n'est pas simplement initié puis soit complété soit échoué. Un moteur de reversement en production doit gérer des états intermédiaires qui surviennent de la nature distribuée de la plateforme.

Les états par lesquels un reversement transite :

Demandé - le reversement a été initié mais aucun fonds n'a bougé. C'est le point d'entrée pour tous les reversements quelle que soit leur source.

Débit destinataire en attente - une tentative de débiter le wallet du destinataire est en cours. Le système maintient une entrée de débit en attente sur le ledger du destinataire.

Débit destinataire échoué - le destinataire n'a pas de fonds suffisants. Le reversement ne peut pas procéder automatiquement. Une révision humaine ou un chemin de résolution alternatif est requis.

Débit destinataire complété - les fonds ont été retirés du wallet du destinataire et sont détenus dans un compte de transit.

Crédit émetteur complété - les fonds ont été crédités au wallet de l'émetteur depuis le compte de transit. Le reversement est complet.

Annulé - le reversement a été demandé mais annulé avant complétion, typiquement parce que les parties ont atteint une résolution alternative.

Chaque transition d'état doit être enregistrée comme un événement de ledger. L'état courant est dérivé du journal d'événements, pas stocké comme un champ de statut mutable. Cela garantit que l'historique du reversement est complet et auditable quelle que soit la défaillance qui survient pendant le traitement.

Les litiges ne sont pas des reversements

Un litige est une réclamation qu'une transaction était non autorisée, incorrecte, ou non exécutée. Un reversement est le mécanisme de résolution qui peut ou non suivre un litige. Ce sont des processus distincts avec des machines d'états distinctes, et les confondre crée une plateforme qui ne peut gérer aucun des deux correctement.

Le processus de litige :

Un utilisateur ou un marchand soulève un litige contre une transaction spécifique. Le litige est enregistré avec un horodatage, la partie contestante, le montant contesté, et le code de motif. Les fonds contestés peuvent être gelés - retirés du solde disponible d'une ou des deux parties - pendant que le litige est examiné. L'investigation produit un constat : le litige est confirmé, partiellement confirmé, ou rejeté. La résolution déclenche un reversement, un reversement partiel, ou aucune action.

Ce processus nécessite plusieurs capacités fréquemment absentes des plateformes wallet construites sans conception explicite des litiges :

Gel de fonds sans modification du ledger. Geler des fonds contestés signifie qu'ils sont indisponibles à la dépense mais pas encore déplacés. L'erreur d'implémentation courante est de déplacer les fonds vers un compte de retenue à l'initiation du litige. Cela crée des entrées de ledger qui doivent être reversées si le litige est rejeté, multipliant la complexité de réconciliation. L'approche correcte est un indicateur de gel sur l'entrée de ledger ou un solde fantôme qui réduit le solde disponible sans créer une transaction.

Résolution partielle. Un litige pour 500 XOF peut être partiellement confirmé pour 300 XOF. Le moteur de résolution doit être capable de fractionner la transaction originale à des fins de résolution, créant un reversement pour 300 XOF et libérant le gel sur les 200 XOF restants.

Suivi des codes de motif. Le reporting réglementaire auprès de la BCEAO, de la CBN, et d'autres autorités de régulation requiert des codes de motif de litige et des résultats de résolution à rapporter. Le moteur de litiges doit capturer et stocker les codes de motif dans un format qui correspond aux exigences de reporting de l'autorité réglementaire compétente.

Lié : Architecture du ledger pour les plateformes wallet

Le patron du compte de transit

Tous les reversements et résolutions de litiges doivent déplacer les fonds via un compte de transit plutôt que directement entre wallets. Le compte de transit est un compte de ledger contrôlé par la plateforme qui agit comme intermédiaire dans chaque déplacement de fonds en plusieurs étapes.

La séquence pour un reversement :

1. Débiter le wallet du destinataire, créditer le compte de transit
2. Débiter le compte de transit, créditer le wallet de l'émetteur

Si l'étape 1 se complète et que l'étape 2 échoue, les fonds sont détenus dans le compte de transit. Ils ne sont pas perdus. La plateforme peut réessayer l'étape 2, escalader pour une résolution manuelle, ou initier un chemin de résolution différent - mais les fonds sont à un emplacement connu avec une piste d'audit claire.

Sans compte de transit, une complétion partielle laisse les fonds dans un état ambigu : débités d'un wallet mais non crédités à un autre. La seule façon de les retrouver est de comparer les débits totaux du ledger aux crédits totaux du ledger et d'identifier l'écart - ce qui est exactement le type de travail de réconciliation qui évolue mal à mesure que le volume augmente.

Le solde du compte de transit doit être zéro à la fin de chaque journée ouvrable dans des conditions normales. Tout solde non nul du compte de transit en fin de journée est un signal qu'un ou plusieurs reversements ou résolutions de litiges sont dans un état incomplet et nécessitent attention.

Les ordonnances de gel réglementaires

Une catégorie de gel de fonds que les plateformes wallet en MENA et en Afrique doivent de plus en plus gérer est l'ordonnance de gel réglementaire : une directive d'une banque centrale, d'une cellule de renseignement financier, ou d'un tribunal pour geler les fonds dans un wallet spécifique en attendant une investigation.

C'est distinct d'un gel de litige. Un gel réglementaire peut couvrir l'intégralité du solde du wallet, peut avoir une durée spécifiée, et peut nécessiter un reporting spécifique à l'autorité émettrice. Il ne peut pas être annulé par le titulaire du compte et peut ne pas lui être visible selon la juridiction.

L'exigence architecturale est un mécanisme de gel qui opère au niveau du wallet plutôt qu'au niveau de la transaction, qui s'intègre au pipeline de reporting de conformité de la plateforme, et qui maintient une piste d'audit complète de quand le gel a été appliqué, par qui, sous quelle autorité, et quand il a été levé.

Les plateformes qui gèrent les gels réglementaires par intervention manuelle en base de données - plutôt que par un workflow d'opérations de conformité conçu - accumulent une exposition à l'audit à chaque événement de gel. Quand l'autorité réglementaire demande un rapport de toutes les ordonnances de gel et de leur résolution, la plateforme qui les a gérées manuellement ne peut pas en produire un proprement.

L'idempotence dans le moteur de reversements

Le moteur de reversements a les mêmes exigences d'idempotence que la couche de traitement des transactions originales, mais les modes de défaillance sont plus dommageables. Un paiement en double est un problème de service client. Un reversement en double - créditer l'émetteur deux fois - est une perte financière et un problème de réconciliation qui peut ne pas être détecté avant la clôture mensuelle.

Chaque demande de reversement doit porter une clé d'idempotence. Le moteur doit insérer la clé avant que le traitement commence. Les réessais sur la même clé doivent retourner l'état courant du reversement, pas en initier un nouveau. La clé d'idempotence doit être scopée à l'action de reversement spécifique, pas à la transaction originale - une transaction peut avoir plusieurs reversements partiels, et chacun doit être idempotent indépendamment.

Lié : Pourquoi les transferts wallet-à-wallet tombent en panne à grande échelle

Intégration à la réconciliation

Le moteur de reversements et de litiges n'est pas complet sans intégration au processus de réconciliation de la plateforme. Chaque reversement et résolution de litige crée des entrées de ledger qui doivent être prises en compte dans la réconciliation de fin de journée.

Le processus de réconciliation doit :

• Tenir compte des reversements en cours - des reversements initiés avant la fermeture de la période de réconciliation mais non complétés avant
• Réconcilier les soldes du compte de transit contre les éléments de reversement ouverts
• Produire un rapport des fonds contestés gelés en fin de période
• Faire correspondre les ordonnances de gel réglementaires à leurs entrées de ledger correspondantes

Les plateformes qui construisent des reversements sans intégration explicite à la réconciliation découvrent le manque en fin de mois quand le ledger ne s'équilibre pas et que la seule façon de trouver l'écart est d'auditer des transactions individuelles.

Lié : Les coûts cachés de la réconciliation manuelle

---

Un moteur de reversements et de litiges bien construit est invisible pour les équipes opérations - les cas se résolvent via des workflows automatisés, le ledger s'équilibre en fin de journée, et le reporting réglementaire est disponible à la demande. Mal construit, il devient la source du travail manuel le plus coûteux de la plateforme. Commencez par un audit d'architecture ciblé si votre plateforme gère les reversements ou litiges via des processus manuels.

Notre service d'ingénierie wallet et ledger couvre la conception du moteur de reversements, l'architecture des workflows de litiges, et l'intégration à la réconciliation pour les plateformes wallet à tout stade de maturité.