Documentation d’Architecture — Flux de Paiement Zorni
1. Vue d’ensemble
Cette architecture décrit le processus complet de gestion des paiements au sein de l’écosystème Zorni, en intégrant :
- le portail client (
zorni-portal) - les APIs de contrôle (
controllerApi) - les services métiers internes
- l’intégration avec la plateforme de paiement externe NAPS
- la gestion batch de trésorerie
- l’envoi de communications client
- l’orchestration événementielle via Kafka
Architecture de Flux de Paiement
L’architecture est divisée en deux grandes zones :
- Public : composants exposés aux utilisateurs et aux partenaires externes
- Privé : composants internes de traitement métier et de gestion financière
2. Composants de l’architecture
2.1 Zone Public
IAM
Le composant IAM gère :
- l’authentification
- l’autorisation
- la sécurisation des accès utilisateurs
Il garantit que seules les requêtes authentifiées peuvent accéder au portail et aux APIs publiques.
zorni-portal
Le portail utilisateur permet :
- l’initiation d’une transaction de paiement
- la redirection vers le formulaire de paiement NAPS
- le suivi du paiement côté client
C’est le point d’entrée principal du flux.
controllerApi
Cette couche orchestre les appels entre le portail et les services métiers.
Elle contient :
zorni-controller
Responsable de :
- l’initialisation du flux de transaction
- la coordination avec les APIs internes
zorni-business-api
Responsable de :
- la logique métier de paiement
- la gestion des règles de validation
- l’orchestration des transactions
NAPS
Le fournisseur externe de paiement.
Il comprend :
NAPS Forms
Interface de paiement affichée à l’utilisateur pour :
- la saisie des informations bancaires
- la validation du paiement
NAPS API
API utilisée pour :
- l’initialisation de la transaction
- la récupération du token de paiement
- les callbacks / webhooks de confirmation
AWB
Système externe utilisé pour :
- la réception des fichiers CSV de virements
- le traitement des versements périodiques
Le dépôt se fait via SFTP.
2.2 Zone Privée
DataMiddleApi
Couche métier principale contenant :
transactionsApi
Responsable de :
- la création des transactions
- la persistance des paiements
- le suivi des statuts
- la gestion des mises à jour transactionnelles
Base de données dédiée.
travelsApi
Responsable de :
- la récupération des informations de circuit / réservation
- le contexte métier du voyage lié au paiement
Base de données dédiée.
InteractionsApi
Services d’interaction métier :
calculatorApi
Responsable de :
- calcul des montants
- commissions
- frais de service
- répartitions financières
communicationsApi
Responsable de :
- la génération des communications client
- SMS
- notifications diverses
Base de données dédiée.
EngineApis
Couche de traitements batch.
cashManagementBatch
Responsable de :
- la récupération des transactions périodiques
- la génération des fichiers CSV de virement
- le dépôt automatique vers le SFTP AWB
Fonctionnement planifié (batch).
ZorniEventBus
Bus événementiel basé sur :
Kafka
Responsable de :
- la publication des événements métier
- la consommation asynchrone
- le découplage inter-services
Utilisé principalement pour :
- les communications client
- les événements post-paiement
3. Flux de paiement détaillé
Étape 1 — Initialisation de transaction
Le client initie une transaction depuis :
zorni-portal
vers :
zorni-controller
Étape 2 — Transmission vers les services métier
Le contrôleur transmet la demande à :
transactionsApi
pour créer et enregistrer la transaction.
Étape 3 — Calcul des montants
transactionsApi appelle :
calculatorApi
pour calculer :
- montant total
- commissions
- frais
- répartitions financières
Étape 4 — Récupération des informations du circuit
Le système appelle :
travelsApi
afin de récupérer :
- informations du voyage
- réservation
- contexte métier
Étape 5 — Initialisation NAPS + récupération du Token
Le système appelle :
NAPS API
pour :
- créer la transaction côté PSP
- récupérer le token sécurisé de paiement
Étape 6 — Redirection utilisateur
Le portail redirige l’utilisateur vers :
NAPS Forms
avec le token de paiement.
L’utilisateur effectue alors son paiement.
Étape 7 — Demande de Token côté NAPS Forms
Le formulaire NAPS utilise le token fourni pour :
- afficher le formulaire sécurisé
- exécuter la transaction bancaire
Étape 8 — Callback Webhook
Après traitement :
NAPS API
envoie les mises à jour de transaction via :
Webhook
vers :
zorni-business-api
Étape 9 — Mise à jour de transaction
Le système met à jour :
transactionsApi
avec :
- succès
- échec
- annulation
- remboursement éventuel
Étape 10 — Publication d’un événement de communication
Le système publie une demande de communication client dans :
Kafka
via :
ZorniEventBus
Étape 11 — Consommation et envoi client
communicationsApi
consomme l’événement et déclenche :
- SMS
- notification client
4. Gestion batch de trésorerie
En parallèle du paiement instantané :
cashManagementBatch
exécute périodiquement :
- récupération des transactions validées
- génération d’un fichier CSV de virement
- dépôt du fichier sur le SFTP AWB
Objectif :
assurer les versements financiers automatisés.
5. Avantages de cette architecture
Cette architecture permet :
Séparation claire des responsabilités
Chaque service a un rôle précis.
Scalabilité
Les composants peuvent évoluer indépendamment.
Résilience
Kafka permet la gestion asynchrone robuste.
Intégration PSP sécurisée
Le paiement est externalisé via NAPS.
Automatisation financière
Les batches réduisent les opérations manuelles.
Maintenabilité
Architecture modulaire et facilement extensible.
6. Conclusion
Cette architecture fournit une solution complète de gestion des paiements :
- initiation client
- traitement PSP
- orchestration métier
- communication client
- gestion financière batch
- intégration événementielle
Elle garantit :
- robustesse
- sécurité
- scalabilité
- traçabilité
- automatisation des flux financiers