Schéma Technique
Flux Bancaire

1.1 Objectif du Document

Ce document présente le schéma technique complet de l'intégration bancaire REWAPP. Il décrit l'architecture, les composants, les flux de données et les mécanismes de sécurité permettant la détection automatique des transactions bancaires et le crédit des points de cashback.

1.2 Contexte Fonctionnel

Le flux bancaire constitue le cœur technologique de REWAPP, permettant :

• La liaison sécurisée des cartes bancaires via OpenBanking (PSD2)
• La détection automatique des achats chez les partenaires
• Le calcul et le crédit instantané des points de cashback
• L'initiation des virements SEPA pour le cashback bancaire

1.3 Fournisseur OpenBanking Recommandé

• Agrément ACPR (Autorité de Contrôle Prudentiel et de Résolution)
• Couverture de plus de 350 banques françaises
• SDK natif compatible Capacitor
• Conformité PSD2 et RGPD
• Webhooks temps réel pour détection des transactions

Alternatives supportées : Tink, Plaid

1.4 Prérequis Techniques

• Infrastructure CapRover déployée (Docker Containers, PostgreSQL, Redis)
• API Gateway Kong configuré
• Services backend NestJS opérationnels
• Certificats SSL/TLS 1.3 actifs
• Contrat signé avec le fournisseur OpenBanking

2.1 Vue d'Ensemble de l'Architecture

L'architecture du flux bancaire repose sur une approche microservices avec communication asynchrone via Bull Queue (Redis). Cette architecture garantit :

2.2 Schéma d'Architecture Globale

@startuml
skinparam backgroundColor #FFFFFF
skinparam componentStyle rectangle
skinparam roundcorner 10
skinparam handwritten false

title Architecture Technique - Flux Bancaire REWAPP

package "Applications Clientes" #LightBlue {
  [App Mobile iOS Android] as MobileApp #LightGreen
  [Dashboard Partenaire PWA] as MerchantDash #LightCyan
}

package "Infrastructure Cloud CapRover" #LightYellow {
  package "API Gateway Layer" #Orange {
    [Kong API Gateway] as Gateway #Gold
  }
  
  package "Services Backend ECS" #LightGreen {
    [Auth Service] as AuthSvc #LightCyan
    [Banking Service] as BankingSvc #Yellow
    [Transaction Service] as TransactionSvc #Pink
    [Points Service] as PointsSvc #Plum
    [Merchant Service] as MerchantSvc #LightGray
    [Notification Service] as NotifSvc #Aqua
    [Webhook Handler] as WebhookHandler #Coral
  }
  
  package "Data Layer" #LightGray {
    database "PostgreSQL Docker" as PostgreSQL #Pink
    database "Redis Docker" as Redis #Salmon
  }
  
  package "Queues Bull" #Lavender {
    queue "transactions" as QueueTx
    queue "points" as QueuePoints
    queue "notifications" as QueueNotif
    queue "withdrawals" as QueueWithdraw
  }
}

cloud "Services Externes" #LightCoral {
  [Budget Insight API] as BudgetInsight #LightGreen
  [Banques Francaises 350+] as Banks #LightBlue
  [Firebase FCM] as FCM #Orange
  [SendGrid Emails] as SendGrid #Yellow
}

MobileApp --> Gateway : HTTPS TLS
MerchantDash --> Gateway : HTTPS TLS
Gateway --> AuthSvc
Gateway --> BankingSvc
Gateway --> TransactionSvc
Gateway --> PointsSvc
Gateway --> MerchantSvc

BudgetInsight --> WebhookHandler : Webhooks
Banks <--> BudgetInsight : API PSD2

AuthSvc --> PostgreSQL
BankingSvc --> PostgreSQL
TransactionSvc --> PostgreSQL
PointsSvc --> PostgreSQL
MerchantSvc --> PostgreSQL

BankingSvc --> Redis : Cache
TransactionSvc --> Redis : Sessions
WebhookHandler --> Redis : Publish

Redis --> QueueTx
QueueTx --> TransactionSvc
QueuePoints --> PointsSvc
QueueNotif --> NotifSvc
QueueWithdraw --> BankingSvc

NotifSvc --> FCM
NotifSvc --> SendGrid

BankingSvc --> BudgetInsight : API REST

@enduml

3.1 Composants Internes

3.2 Composants Externes

3.3 Description Détaillée du Banking Service

Le Banking Service est le composant central de l'intégration bancaire. Ses responsabilités incluent :

4.1 Diagramme de Flux Principal

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceMessageAlign center

title Schéma Technique - Flux Bancaire Complet

participant "Application
Mobile" as App #LightBlue
participant "API
Gateway" as GW #Orange
participant "Banking
Service" as BankSvc #Yellow
participant "Webhook
Handler" as WH #Pink
participant "Transaction
Service" as TxSvc #LightGreen
participant "Merchant
Service" as MerchSvc #Cyan
participant "Points
Service" as PtsSvc #Gold
participant "Notification
Service" as NotifSvc #Violet
database "PostgreSQL" as DB #LightGray
database "Redis" as Cache #Red
participant "Budget Insight
API" as BI #Green
participant "Banque
Utilisateur" as Bank #Purple

== PHASE A : Card Linking (Une seule fois) ==
App -> GW : POST /api/v1/banking/cards/link
GW -> BankSvc : Initier liaison
BankSvc -> Cache : Créer session (TTL 10min)
BankSvc -> BI : POST /auth/init
BI --> BankSvc : {authUrl, stateToken}
BankSvc --> App : {sessionId, authUrl}
App -> BI : Lancer SDK Budget Insight
BI -> Bank : Redirection OAuth2
Bank -> Bank : Authentification SCA (2FA)
Bank --> BI : authorization_code
BI -> BI : Échanger tokens
BI --> App : {connectionId}
App -> GW : POST /api/v1/banking/complete-link
GW -> BankSvc : Finaliser liaison
BankSvc -> BI : GET /connections/{id}
BI --> BankSvc : {tokens, accounts}
BankSvc -> BankSvc : Chiffrer tokens (AES-256-GCM)
BankSvc -> DB : INSERT bank_connections
BankSvc -> BI : POST /webhooks/register
BI --> BankSvc : {webhookId}
BankSvc --> App : Succès

== PHASE B : Détection Transaction (Automatique) ==
Bank -> BI : Nouvelle transaction détectée
BI -> WH : POST /webhooks/banking
{event: transaction.created}
WH -> WH : Vérifier signature HMAC-SHA256
WH -> WH : Vérifier timestamp (<5 min)
WH --> BI : HTTP 200 OK
WH -> Cache : PUBLISH job "transaction.received"
Cache -> TxSvc : Consumer job
TxSvc -> DB : Vérifier idempotence
TxSvc -> MerchSvc : GET /internal/merchants/match
MerchSvc -> MerchSvc : Matching (MCC, nom, ID)
MerchSvc --> TxSvc : {merchant_id, cashback_rate}

== PHASE C : Calcul et Crédit Points ==
TxSvc -> PtsSvc : GET /internal/points/tier
PtsSvc --> TxSvc : {tier, bonus}
TxSvc -> TxSvc : Calculer points
note right of TxSvc
  Points = (Montant × Taux × (1+Bonus)) / 0.10
  Ex: (100€ × 4% × 1.10) / 0.10 = 44 points
end note
TxSvc -> DB : INSERT transaction
TxSvc -> Cache : PUBLISH job "points.credit"
Cache -> PtsSvc : Consumer job
PtsSvc -> DB : BEGIN TRANSACTION
PtsSvc -> DB : INSERT points_ledger
PtsSvc -> DB : UPDATE user.points_balance
PtsSvc -> DB : COMMIT
PtsSvc -> Cache : PUBLISH job "notification.send"

== PHASE D : Notification Utilisateur ==
Cache -> NotifSvc : Consumer job
NotifSvc -> App : Push "Vous avez gagné 44 points!"
NotifSvc -> DB : INSERT notification

== PHASE E : Virement Bancaire (Sur demande) ==
App -> GW : POST /api/v1/banking/withdrawals
GW -> BankSvc : Demande virement
BankSvc -> PtsSvc : Vérifier solde (≥100 points)
PtsSvc --> BankSvc : {available: 500}
BankSvc -> PtsSvc : Bloquer points
BankSvc -> DB : INSERT withdrawal (pending)
BankSvc -> Cache : PUBLISH job "withdrawal.process"
Cache -> BankSvc : Consumer job
BankSvc -> BankSvc : Calculer montant (×0.095)
BankSvc -> BI : POST /payments/initiate
note right of BI
  Montant = 100 points × 0.095 = 9.50€
  Délai: 2-3 semaines
end note
BI -> Bank : Ordre virement SEPA
BI --> BankSvc : {payment_id, status}
BankSvc -> DB : UPDATE withdrawal (processing)
BankSvc --> App : {status: processing}

@enduml

5.1 Flux 1 : Liaison de Carte Bancaire

Ce flux est exécuté une seule fois par carte lors de l'onboarding ou depuis le profil utilisateur.

5.2 Flux 2 : Détection et Crédit de Points

Ce flux est déclenché automatiquement à chaque transaction détectée.

5.3 Flux 3 : Demande de Virement Bancaire

6.1 Architecture de l'Intégration Budget Insight

6.2 Endpoints Budget Insight Utilisés

6.3 Configuration des Webhooks

6.4 Conformité PSD2

Directive PSD2 (Payment Services Directive 2) - Exigences respectées :

7.1 Architecture de Réception des Webhooks

7.2 Validation des Webhooks

7.2.1 Vérification de la Signature

La signature HMAC-SHA256 est calculée ainsi :

expected = HMAC-SHA256(
  key: webhook_secret,
  data: timestamp + "." + raw_body
)

if (expected !== header['X-Webhook-Signature']) {
  return HTTP 401 WEBHOOK_SIGNATURE_INVALID
}

7.2.2 Protection Anti-Replay

webhook_timestamp = header['X-Webhook-Timestamp']
current_timestamp = Date.now()

if (current_timestamp - webhook_timestamp > 300000) { // 5 minutes
  return HTTP 401 WEBHOOK_TIMESTAMP_EXPIRED
}

7.3 Format du Payload Webhook

7.3.1 Événement transaction.created

{
  "event": "transaction.created",
  "timestamp": "2025-11-24T14:30:00.000Z",
  "data": {
    "transaction_id": "txn_abc123xyz",
    "connection_id": "conn_user456",
    "account_id": "acc_789",
    "amount": 100.00,
    "currency": "EUR",
    "direction": "DEBIT",
    "date": "2025-11-24",
    "merchant": {
      "name": "RESTAURANT LE BISTROT",
      "mcc_code": "5812",
      "city": "PARIS",
      "country": "FR"
    }
  },
  "signature": "sha256=7d38cdd689735b008..."
}

7.3.2 Événement payment.completed

{
  "event": "payment.completed",
  "timestamp": "2025-11-24T15:45:00.000Z",
  "data": {
    "payment_id": "pay_xyz789",
    "withdrawal_id": "wd_abc123",
    "amount": 9.50,
    "currency": "EUR",
    "status": "COMPLETED",
    "reference": "REWAPP-WD-2025-11-24-001",
    "beneficiary_iban": "FR76****1234"
  }
}

8.1 Mesures de Sécurité par Couche

8.2 Données Sensibles et Protection

8.3 Conformité RGPD

8.4 Conformité PCI DSS

9.1 Stratégie de Retry

9.2 Dead Letter Queue (DLQ)

Les jobs échoués après 3 tentatives sont placés dans la DLQ pour analyse manuelle :

9.3 Circuit Breaker

Protection contre les cascades de pannes :

9.4 Codes d'Erreur Bancaires

10.1 Métriques Clés (Prometheus / Grafana)

10.2 Alertes Configurées

10.3 Logs et Traces

10.4 Dashboard de Supervision

Tableaux de bord Grafana configurés :

• Banking Overview : Webhooks/min, latence, erreurs
• Card Linking : Taux succès liaison, durée moyenne, abandons
• Transactions : Volume détecté, taux matching, points crédités
• Withdrawals : Demandes/jour, statuts, délais moyens
• Security : Tentatives invalides, IP suspectes, alertes

11.1 Points Clés de l'Architecture

11.2 Composants Critiques

11.3 Checklist d'Implémentation

• Contrat Budget Insight signé (agrément ACPR)
• Clés API et secrets configurés (variables CapRover)
• Webhook Handler déployé avec IP whitelisting
• Banking Service avec chiffrement AES-256
• Queues Bull configurées (transactions, points, notifications, withdrawals)
• Circuit breakers configurés
• Monitoring Prometheus/Grafana actif
• Alertes Slack/PagerDuty configurées
• Tests de bout en bout validés (sandbox Budget Insight)
• Documentation API interne à jour

11.4 Références Documentaires