Détection Transaction et Crédit Points

1.1 Objectif du Document

Ce document décrit le diagramme de séquence pour la détection automatique des transactions bancaires et le crédit des points de cashback sur le compte utilisateur REWAPP.

1.2 Contexte Fonctionnel

Lorsqu'un utilisateur REWAPP effectue un achat chez un commerçant partenaire avec sa carte bancaire liée, le système détecte automatiquement la transaction via l'intégration OpenBanking (Budget Insight, Tink ou Plaid). Les points de cashback sont ensuite calculés et crédités sur le compte de l'utilisateur.

1.3 Prérequis

• Utilisateur inscrit et compte actif sur REWAPP
• Au moins une carte bancaire liée via OpenBanking
• Webhooks bancaires configurés et fonctionnels
• Commerçant inscrit et validé comme partenaire REWAPP

2.1 Liste des Acteurs

2.2 Responsabilités des Acteurs

2.2.1 Fournisseur OpenBanking

• Agrège les comptes bancaires via API PSD2
• Détecte les nouvelles transactions en temps réel
• Envoie des webhooks à REWAPP pour chaque transaction
• Fournit les détails : montant, date, nom commerçant, MCC code

2.2.2 Webhook Handler

• Réceptionne les webhooks du fournisseur bancaire
• Vérifie la signature HMAC-SHA256 du webhook
• Valide le format et l'intégrité des données
• Route vers le Transaction Service via Bull Queue

2.2.3 Transaction Service

• Traite les transactions bancaires reçues
• Identifie si le commerçant est un partenaire REWAPP
• Calcule le montant de cashback selon le taux partenaire
• Coordonne le crédit des points avec le Points Service

2.2.4 Points Service

• Gère le solde de points de chaque utilisateur
• Crédite les points selon la méthode FIFO
• Calcule les bonus de palier de fidélité
• Gère l'expiration des points (12 mois)

3.1 Notation PlantUML

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowThickness 2
skinparam roundcorner 10

title Detection Transaction et Credit Points REWAPP

actor "Utilisateur" as User #LightBlue
participant "Terminal Paiement" as TPE #Orange
participant "Banque" as Bank #Yellow
participant "OpenBanking" as OB #Cyan
participant "Webhook Handler" as WH #Pink
participant "Transaction Service" as TS #LightGreen
participant "Merchant Service" as MS #Gold
participant "Points Service" as PS #Plum
participant "Notification" as NS #Coral
database "PostgreSQL" as DB #LightGray
database "Redis" as Redis #Salmon

== Phase 1 Achat Partenaire ==
User -> TPE : Paiement carte 100EUR
TPE -> Bank : Autorisation paiement
Bank --> TPE : Paiement autorise
TPE --> User : Ticket de caisse

== Phase 2 Notification OpenBanking ==
Bank -> OB : Transaction effectuee
OB -> WH : Webhook transaction.created

== Phase 3 Validation Webhook ==
WH -> WH : Verifier signature HMAC
WH -> WH : Verifier timestamp
WH --> OB : HTTP 200 OK
WH -> Redis : Publier job transaction.received

== Phase 4 Traitement Transaction ==
Redis -> TS : Consumer recupere job
TS -> DB : Verifier idempotence

alt #LightYellow Nouvelle transaction
  TS -> DB : Recuperer infos utilisateur
  TS -> MS : GET merchants/match
  
  alt #LightGreen Partenaire trouve
    MS --> TS : merchant_id cashback 4%
    TS -> PS : GET points/user/tier
    PS --> TS : tier GOLD bonus 10%
    TS -> TS : Calcul 44 points
    TS -> DB : INSERT transaction
    TS -> Redis : Publier points.credit
    
    == Phase 5 Credit Points ==
    Redis -> PS : Consumer recupere job
    PS -> DB : BEGIN TRANSACTION
    PS -> DB : INSERT points_ledger 44 pts
    PS -> DB : UPDATE user balance
    PS -> DB : COMMIT
    PS -> Redis : Publier notification.send
    
    == Phase 6 Notification ==
    Redis -> NS : Consumer recupere job
    NS -> User : Push 44 points gagnes
    NS -> DB : INSERT notification
    
  else #Pink Non partenaire
    MS --> TS : matched false
    TS -> DB : INSERT no_cashback
  end
end
@enduml

Le diagramme ci-dessus illustre le flux complet de détection d'une transaction et crédit des points, décomposé en 6 phases distinctes.

4.1 Phase 1 : Achat chez le Partenaire

4.2 Phase 2 : Notification OpenBanking

4.2.1 Payload du Webhook (Exemple)

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

4.3 Phase 3 : Validation du Webhook

4.3.1 Validation de la Signature

La signature est vérifiée selon l'algorithme suivant :

expected_signature = HMAC-SHA256(webhook_secret, timestamp + "." + payload_body)
if (expected_signature !== received_signature) {
  return HTTP 401 Unauthorized
}

4.4 Phase 4 : Traitement de la Transaction

4.4.1 Algorithme de Matching Commerçant

Le Merchant Service utilise une stratégie de matching en 3 étapes :

1. 1

   Matching par MCC Code

   Le code MCC (Merchant Category Code) est comparé aux catégories des partenaires enregistrés.

2. 2

   Matching par Nom (Fuzzy)

   Si le MCC ne suffit pas, un algorithme de similarité (Levenshtein, Soundex) compare le nom du commerçant avec les noms des partenaires.

3. 3

   Matching par Identifiant Bancaire

   Certains partenaires fournissent leur identifiant bancaire exact pour un matching précis.

4.4.2 Formule de Calcul du Cashback

4.5 Phase 5 : Crédit des Points

4.5.1 Structure de l'Enregistrement Points

4.6 Phase 6 : Notification Utilisateur

4.6.1 Contenu de la Notification Push

{
  "title": "🎉 Points crédités !",
  "body": "Vous avez gagné 44 points chez Restaurant Le Bistrot. Solde : 544 points",
  "data": {
    "type": "points_credited",
    "transaction_id": "txn_abc123xyz",
    "amount": 44,
    "merchant_name": "Restaurant Le Bistrot"
  }
}

5.1 Cas Alternatif 1 : Commerçant Non Partenaire

5.2 Cas Alternatif 2 : Transaction Déjà Traitée (Idempotence)

L'idempotence est garantie par une contrainte UNIQUE sur le champ external_transaction_id.

5.3 Cas d'Erreur 1 : Signature Webhook Invalide

5.4 Cas d'Erreur 2 : Timestamp Expiré (Replay Attack)

Protection contre les attaques par rejeu : les webhooks de plus de 5 minutes sont systématiquement rejetés.

5.5 Cas d'Erreur 3 : Utilisateur Suspendu

5.6 Cas d'Erreur 4 : Carte Bancaire Révoquée

5.7 Cas d'Erreur 5 : Échec du Service Points

Après 3 échecs, le job est placé dans la Dead Letter Queue pour traitement manuel.

5.8 Cas d'Erreur 6 : Transaction de Remboursement

Si le solde est insuffisant, le compte passe en négatif temporairement jusqu'à régularisation.

5.9 Tableau Récapitulatif des Codes d'Erreur

6.1 Règles de Calcul des Points

6.2 Règles des Paliers de Fidélité

6.3 Règles du Taux de Cashback

7.1 Sécurité du Webhook

7.2 Conformité PSD2

7.3 Conformité RGPD

7.4 Audit Trail

Chaque étape du processus génère une entrée d'audit contenant :

• Timestamp précis (millisecondes)
• Identifiant de corrélation (traceId)
• Acteur (service ou utilisateur)
• Action effectuée
• Données avant/après modification
• Résultat (succès/échec)

8.1 Documents de Référence

8.2 Endpoints API Concernés

8.3 Queues Bull Impliquées

9.1 KPIs à Surveiller

9.2 Alertes Configurées

• Slack #alerts-critical : Échec de validation webhook
• Slack #alerts-business : Taux de matching < 70%
• PagerDuty : Service indisponible > 2 minutes
• Email équipe : Rapport quotidien des anomalies