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.