Paiement API

Ce fichier documente les endpoints exposés par le contrôleur PaiementControllerPrivate et PaiementControllerPublique.

Base routes:

• /api/private (endpoints internes)
• /api/publique (endpoints publics)

POST /api/private/create_paiement

Crée un paiement depuis l'interface interne.

Body: PaiementDto (voir backend/src/paiement/dto/create_paiement.dto.ts)

Réponse: résultat de la création (format dépendant du service interne)

GET /api/private/clients-card/:clientId

Récupère les moyens de paiement pour un client. Supprime le CVV et transforme cardNumber en last4.

Path params:

• clientId (nombre)

Réponse: tableau d'objets { id, clientFideliseId, type, details }

DELETE /api/private/clients-card/:id

Supprime un moyen de paiement par son id.

Path params:

• id (nombre)

Réponse: message d'acknowledgement

POST /api/publique/refund

Effectue un remboursement.

Body: RefundDto (clientId, transactionId, source)

POST /api/publique/interface-paiement

Endpoint pour générer / rediriger vers la page de paiement externe.

Body: InterfacePaiementDto (client, amount, currency, orderId?, source)

Réponse: dépend de l'implémentation (généralement un objet contenant l'URL ou le statut)

Gestion d'Erreur et Récupération des Paiements

Le système de paiement dispose d'un mécanisme robuste de gestion d'erreur et de récupération automatique des transactions orphelines.

Architecture de Récupération

1. Traitement Immédiat avec Timeout

• Lors de la création d'un paiement, la transaction est immédiatement sauvegardée avec le statut en_attente
• Un setTimeout de 10 secondes est programmé pour traiter le paiement en arrière-plan
• Si le serveur plante pendant le traitement, le timeout est perdu mais la transaction reste en base

2. Système de Cron Jobs de Récupération

Le service PaymentCleanupService gère deux niveaux de récupération automatique :

Récupération Rapide (toutes les 5 minutes)

@Cron('*/5 * * * *') // Toutes les 5 minutes
async handleOrphanedPayments()

• Recherche les transactions avec statut en_attente créées il y a plus de 2 minutes
• Considère ces transactions comme "orphelines" (timeout perdu)
• Les traite automatiquement en simulant le processus de paiement
• Met à jour le statut vers accepte, refuse ou annule

Nettoyage Quotidien (tous les jours à minuit)

@Cron('0 0 * * *') // Tous les jours à minuit
async handleOldPendingPayments()

• Recherche les transactions en_attente de plus de 24 heures
• Les marque automatiquement comme annule (expirées)
• Évite l'accumulation de transactions en attente

Statuts des Transactions

Statut	Description	Actions Possibles
en_attente	Transaction créée, traitement en cours	Récupération automatique par cron
accepte	Paiement accepté avec succès	Statut final
paye	Paiement effectué et confirmé	Statut final
refuse	Paiement refusé	Statut final
annule	Transaction annulée ou expirée	Statut final

Gestion d'erreur côté client (coupure serveur)

Lorsqu'une coupure du serveur survient après la création d'une transaction :

• La transaction reste en base avec le statut en_attente.
• Si le client revient sur la page de paiement et que la transaction est retrouvée (par polling ou récupération via l'orderId), il peut annuler la transaction (bouton annuler) pour pouvoir relancer un nouveau paiement.
• Si le client ne revient pas ou ne fait rien, la transaction sera automatiquement traitée par le cron :
  • Si le paiement est accepté, le statut passera à accepte (et le client sera redirigé s'il revient plus tard).
  • Si le client revient dans les 5 minutes et annule la transaction, le statut passera à annule et il pourra recommencer un paiement.

Résumé :

• Coupure serveur = transaction en_attente
• Si retour client < 5min et annulation → transaction annulée, nouveau paiement possible
• Si pas d'action client → transaction traitée automatiquement (accepte/refuse) par le cron

---

Flux de Récupération d'Erreur

Configuration des Timeouts

• Détection orpheline : 2 minutes (considéré comme timeout perdu)
• Récupération rapide : 5 minutes (cron de récupération)
• Expiration finale : 24 heures (annulation automatique)

Avantages de cette Architecture

1. Résilience : Aucune transaction n'est perdue même en cas de crash serveur
2. Performance : Traitement immédiat pour les cas normaux
3. Robustesse : Récupération automatique sans intervention manuelle
4. Nettoyage : Évite l'accumulation de données obsolètes

Cette architecture garantit qu'aucun paiement client n'est perdu et que tous les cas d'erreur sont gérés automatiquement par le système.