Système de transactions Nex — Architecture, sécurité et gouvernance
Version : 1.0 — Date de publication : 2026-04-17 Périmètre : plateforme Nex, zone CEMAC (Cameroun, Congo, Gabon, Guinée équatoriale, Tchad, RCA). Devises XAF et XOF. Destinataires : direction, département compliance, organes de régulation (COBAC), équipe plateforme. Statut de validation : document de référence à faire approuver par Tech Lead backend + Responsable Produit/Compliance.
Synthèse exécutive
Nex est une plateforme de paiement mobile opérant dans la zone CEMAC. Son cœur métier est la gestion sécurisée de transactions financières entre utilisateurs, agents et organisations, à travers trois flux principaux : transfert entre particuliers (P2P), dépôt d'argent liquide (cash-in), retrait d'argent liquide (cash-out).
Jusqu'au premier trimestre 2026, un audit interne a révélé l'existence d'écarts comptables silencieux — jusqu'à 317 626 XAF de différence entre le solde affiché d'un compte et la somme des écritures du grand livre. Ces écarts, non frauduleux, résultaient d'un défaut de conception dans la coordination des opérations simultanées (phénomène dit de double-spend).
Un chantier complet de durcissement a été mené (référence interne : ticket NEX-180). Il a livré :
- Une refonte du chemin critique de paiement pour le rendre strictement atomique au niveau de la base de données.
- Des contraintes d'intégrité infalsifiables au niveau du stockage.
- Un mécanisme d'idempotence transversal protégeant contre les rejeux.
- Une piste d'audit enrichie et un contrôle d'intégrité nocturne.
État au 17 avril 2026 :
- Le chemin de paiement canonique (P2P, dépôt, retrait agent) est désormais protégé contre le double-spend et l'altération comptable.
- Les cas résiduels (recharge mobile, paiements en masse, rappels trésorerie) restent à aligner sur le nouveau modèle — tickets de suivi dédiés.
- Le système est conforme, sur son périmètre couvert, aux principes comptables attendus d'un EME : immutabilité du grand livre, double entrée systématique, traçabilité, séparation des comptes techniques.
Hors périmètre NEX-180 : mise en place du cantonnement bancaire et de la réconciliation banque-ledger (chantier distinct, dépend du statut EME officiel — voir Customer Funds Safeguarding).
Cadre réglementaire et enjeux compliance
Réglementation applicable
En zone CEMAC, les émetteurs de monnaie électronique sont soumis aux dispositions COBAC et aux textes BEAC. Exigences structurantes :
- Comptabilité en partie double : toute écriture au crédit est compensée par un débit symétrique.
- Immutabilité du grand livre : une écriture ne peut être ni modifiée ni supprimée. Corrections par écriture inverse.
- Piste d'audit complète : chaque opération est tracée (auteur, horodatage, référence unique, attributs d'origine).
- Séparation des tâches (SoD) : initiateur ≠ approbateur sur les opérations sensibles.
- Cantonnement : fonds clients ségrégués des fonds propres de l'émetteur.
Enjeux opérationnels d'un écart comptable
| Niveau | Risque |
|---|---|
| Financier | Débours supérieur au comptabilisé → perte sèche |
| Compliance | Écart non expliqué = manquement COBAC grave |
| Réputationnel | Perte de confiance régulateur / utilisateur |
| Pénal | Mise en cause des responsables pour défaut de contrôle interne |
NEX-180 ferme la principale porte d'entrée à ce risque.
Plan de la documentation
La référence technique complète est éclatée en trois pages thématiques.
| Page | Contenu |
|---|---|
| Fonctionnement métier et architecture technique | Cycle de vie d'une transaction (intents + state machine), événements d'intent, principes (partie double, immutabilité, idempotence, intégrité concurrente), services et modèle de données, séquence détaillée. |
| Protection contre le double-spend | Quatre couches de défense (SQL SERIALIZABLE, locks ordonnés, idempotence par intent, garanties fournies). |
| Procédures, audit, gouvernance et limites | Procédures d'implémentation, audit et contrôles continus, gouvernance et rôles, limites connues et feuille de route. |
Références
Documents internes
infrastructure/docs/compliance-audit-2026.md— audit compliance détaillé, 5 piliers A1 à A5._bmad-output/implementation-artifacts/NEX-180-ledger-concurrency-hardening.md— spécification de NEX-180._bmad-output/implementation-artifacts/NEX-180-test-plan.md— plan de tests organisé en 11 sections.infrastructure/docs/INTENT_CASHOUT_FLOW.md— flow cash-out avec QR.infrastructure/docs/algo-reporting-historique-compte.md— algorithme rapport d'historique compte (NEX-179).
Code source clé
services/ledger-wallets/src/intents/intents.service.ts— gestion des intents, point d'entrée du chemin atomique.services/ledger-wallets/src/transactions/orchestrators/transaction-creation.orchestrator.ts— orchestrateur SQL.services/ledger-wallets/src/common/utils/lock-accounts-in-order.ts— verrouillage pessimiste ordonné.services/ledger-wallets/src/common/decorators/retry-on-serialization-failure.decorator.ts— rejeu sur erreurs de sérialisation.services/ledger-wallets/src/idempotency/interceptors/idempotency.interceptor.ts— idempotence transversale.services/orchestrator/src/application/use-cases/intents/confirm-intent.use-case.ts— confirmation d'un intent.
Réglementation et standards
- Réglementation COBAC applicable aux Établissements de Monnaie Électronique.
- Directives BEAC sur le safeguarding des fonds clients.
- Pattern d'idempotence Stripe : https://stripe.com/docs/api/idempotent_requests
- Pattern d'outbox transactionnel : https://microservices.io/patterns/data/transactional-outbox.html
- PostgreSQL — Isolation levels : https://www.postgresql.org/docs/current/transaction-iso.html
- PostgreSQL — Explicit locking : https://www.postgresql.org/docs/current/explicit-locking.html
Annexe — Glossaire
- ACID — atomicité, cohérence, isolation, durabilité d'une transaction base.
- Agent — partenaire physique de Nex qui accueille les clients pour cash-in / cash-out.
- Append-only — structure dans laquelle on ne peut qu'ajouter, jamais modifier ni supprimer.
- Cash-in / Cash-out — dépôt / retrait d'argent liquide par un agent.
- Cantonnement (safeguarding) — fonds clients sur compte bancaire ségrégué du patrimoine de l'émetteur.
- COBAC — Commission Bancaire d'Afrique Centrale, régulateur CEMAC.
- Correlation ID — identifiant unique d'une requête traversant plusieurs services.
- Deadlock — situation où deux transactions s'attendent mutuellement.
- Double-entry — partie double, toute écriture débit compensée par crédit équivalent.
- Double-spend — défaut qui permet à deux opérations concurrentes de dépenser les mêmes fonds.
- EME — Établissement de Monnaie Électronique, statut réglementaire.
- Idempotence — propriété d'une opération qui, rejouée plusieurs fois, produit le même résultat qu'une seule fois.
- Intent (TransactionIntent) — objet métier représentant l'intention d'exécuter une transaction.
- Ledger — grand livre comptable, collection d'écritures individuelles de débit et de crédit.
- Lock pessimiste — verrouillage qui retient une ressource pour la durée d'une transaction.
- Maker-checker — séparation des tâches, initiateur ≠ approbateur.
- Master Agent — agent associé à une organisation partenaire, disposant d'un portefeuille corporate.
- OTP — code à usage unique envoyé au client.
- P2P — Peer-to-Peer, transfert d'argent directement entre deux utilisateurs.
- PostgreSQL — SGBD relationnel utilisé par Nex.
- Race condition — résultat d'une opération qui dépend de l'ordre d'exécution de plusieurs processus concurrents.
- SERIALIZABLE — niveau d'isolation transactionnelle le plus strict.
- SERIALIZATION_FAILURE — erreur PostgreSQL levée si deux transactions concurrentes ne peuvent pas être sérialisées sans conflit.
- SoD (Segregation of Duties) — séparation des tâches, principe de gouvernance interne.
- Trésorerie (Treasury) — compte technique de la plateforme, distinct des comptes clients.
- Trigger — procédure automatique exécutée par la base en réaction à un événement.
- XAF / XOF — codes ISO 4217 des devises Franc CFA d'Afrique centrale (XAF) et de l'Ouest (XOF).