# Documentation des flux de paiement

Ce document décrit les différents flux de paiement au sein de l'application Wego.

# 1. Flux de paiement en ligne (via QR Code)

Ce flux est destiné aux utilisateurs non authentifiés qui paient pour une session de recharge unique via une carte de crédit.

### Étapes du flux

1.  **Initiation** : L'utilisateur scanne un QR code sur une borne de recharge, ce qui le redirige vers une page web dédiée à cette borne.

2.  **Création d'une intention de paiement** :
    *   Le frontend appelle l'API pour créer une intention de paiement : `GET /api/payments/evse/:slug/with-capture`.
    *   Le backend crée une intention de paiement (Payment Intent) auprès de Stripe avec la méthode de capture manuelle (`capture_method: 'manual'`). Cela autorise un montant pré-défini sans le débiter immédiatement.
    *   Un enregistrement est créé dans la table `payments` avec le statut `PAYMENT_CREATED` et un `tagId` temporaire est généré.
    *   L'API retourne un `client_secret` au frontend.

3.  **Confirmation du paiement par l'utilisateur** :
    *   Le frontend utilise le `client_secret` pour afficher le formulaire de paiement Stripe.
    *   L'utilisateur saisit ses informations de carte bancaire et valide le paiement.

4.  **Démarrage de la transaction** :
    *   Une fois le paiement confirmé côté client, le frontend appelle l'API : `POST /api/payments/remote-start-after-payment-confirmed`.
    *   Le backend vérifie la validité du paiement, met à jour le statut de l'enregistrement `payments` à `PAYMENT_CONFIRMED`.
    *   Le backend envoie une commande `RemoteStartTransaction` à la borne via le protocole OCPP, en utilisant le `tagId` temporaire.
5.  **Session de recharge** : La session de recharge est active. Un enregistrement est créé dans la table `transactions` et lié à l'enregistrement `payments`.

6.  **Arrêt de la transaction** :
    *   L'utilisateur arrête la recharge depuis la page web, ce qui déclenche un appel à `POST /api/payments/transaction/:idOrSlug/stop`.
    *   La borne envoie une notification `StopTransaction` au backend.

7.  **Capture du paiement** :
    *   La notification `StopTransaction` déclenche un événement `transaction-payment-capture`.
    *   Un service écoute cet événement et appelle la méthode `paymentsService.capturePaymentWithCapture()`.
    *   Cette méthode finalise la transaction Stripe en capturant le montant final de la recharge (le coût réel de l'énergie consommée).
    *   Le statut de l'enregistrement `payments` est mis à jour à `PAYMENT_CAPTURED`.

# 2. Flux de paiement par badge RFID (Utilisateur Wego)

Ce flux est destiné aux utilisateurs enregistrés sur la plateforme Wego et qui utilisent un badge RFID fourni par Wego.

### Étapes du flux

1.  **Authentification** : L'utilisateur présente son badge RFID Wego à la borne.
2.  **Autorisation** : La borne envoie une requête `Authorize` au backend avec le `tagId` du badge. Le backend vérifie dans sa base de données locale que le badge est valide et actif.
3.  **Démarrage de la transaction** :
    *   La borne envoie une notification `StartTransaction` au backend.
    *   Le backend crée un enregistrement dans la table `transactions` lié au `tagId` de l'utilisateur.
4.  **Session de recharge** : La session est active.
5.  **Arrêt de la transaction** : L'utilisateur arrête la recharge. La borne envoie une notification `StopTransaction` au backend.
6.  **Facturation** :
    *   Le coût de la transaction n'est pas payé immédiatement.
    *   La transaction est associée à l'utilisateur et à son groupe de facturation (`invoicedGroup`).
    *   Le processus de facturation se fait via un processus périodique (batch) qui agrège les transactions par groupe de facturation.
    *   Le module `emat` gère un cas spécifique de facturation pour le groupe Eiffage.

# 3. Flux de paiement via EMSP

Ce flux s'applique lorsqu'un utilisateur d'un partenaire de roaming (un EMSP) utilise une borne du réseau Wego. La communication se fait via le protocole OCPI.

### Étapes du flux

1.  **Autorisation (OCPI)** :
    *   L'utilisateur présente le badge de son EMSP à la borne Wego.
    *   La borne envoie une requête `Authorize` au backend Wego.
    *   Le backend Wego, ne reconnaissant pas le badge localement, identifie qu'il s'agit d'un badge de roaming et interroge l'EMSP partenaire via l'endpoint OCPI `Tokens` (`POST /ocpi/2.1.1/tokens/{token_uid}/authorize`).
    *   L'EMSP partenaire valide le badge et retourne une réponse positive.
    *   Le backend Wego crée un enregistrement local `Authorization` qui lie le `tagId` à l' `idEmsp` du partenaire.
2.  **Démarrage de la transaction** :
    *   La borne envoie une notification `StartTransaction`.
    *   Le backend Wego crée une transaction et l'associe à l'`idEmsp` grâce à l'autorisation préalablement enregistrée.
3.  **Session de recharge** : La session est active.
4.  **Arrêt de la transaction** : L'utilisateur arrête la recharge. La borne envoie une notification `StopTransaction` au backend Wego.
5.  **Génération et Envoi du CDR (Charge Detail Record)** :
    *   À la fin de la transaction, le backend Wego génère un CDR. Ce document est un "ticket de caisse" détaillé de la session de recharge (énergie consommée, durée, coût, etc.).
    *   Le backend Wego envoie ce CDR à l'EMSP partenaire via son endpoint OCPI `CDRs` (`POST /ocpi/cpo/2.1.1/cdrs`).
    *   L'URL du CDR sur le système de l'EMSP est enregistrée dans le champ `emspCdrUrl` de la transaction, servant de confirmation.
6.  **Facturation** :
    *   La facturation finale de l'utilisateur est gérée entièrement par l'EMSP partenaire, sur la base du CDR reçu.
    *   Le règlement financier entre Wego (le CPO) et l'EMSP se fait en dehors de l'application, selon les accords de roaming établis, en utilisant les CDRs comme preuve de service.