From bd7657710d0e3de85513764d4086cd7c80939f48 Mon Sep 17 00:00:00 2001 From: senke Date: Mon, 23 Feb 2026 22:59:07 +0100 Subject: [PATCH] docs(payout): update PAYOUT_MANUAL for v0.603 auto transfer --- docs/PAYOUT_MANUAL.md | 44 ++++++++++++++++++++----------------------- 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/docs/PAYOUT_MANUAL.md b/docs/PAYOUT_MANUAL.md index ffa83d965..b23d76f26 100644 --- a/docs/PAYOUT_MANUAL.md +++ b/docs/PAYOUT_MANUAL.md @@ -1,34 +1,30 @@ -# Payout manuel — Procédure pour v0.603 +# Payout vendeurs — Transfert automatique (v0.603) -**Contexte** : En v0.602, le payout vendeurs inclut Stripe Connect onboarding et l'affichage de la balance. Le **transfert automatique après vente** est reporté en v0.603 pour éviter la complexité d'injection du StripeConnectService dans le flow marketplace (ProcessWebhook). +**Contexte** : Depuis v0.603, le transfert automatique vers les comptes Stripe Connect des vendeurs est opérationnel après chaque paiement réussi. -## État v0.602 +## Implémentation v0.603 + +Le transfert automatique s'exécute à chaque webhook Hyperswitch `payment.succeeded` : + +1. Paiement réussi → licences créées pour l'acheteur +2. Items regroupés par vendeur (`product.seller_id`) +3. Commission plateforme déduite (`PLATFORM_FEE_RATE`, défaut 10 %) +4. Transfer Stripe Connect exécuté vers le compte du vendeur +5. `SellerTransfer` enregistré en DB (table `seller_transfers`) + +Les vendeurs peuvent consulter leur historique via `GET /sell/transfers` et la carte « Transfer History » dans SellerDashboard. + +## État actuel - ✅ Onboarding Stripe Connect (POST /sell/connect/onboard) - ✅ Balance vendeur (GET /sell/balance) -- ✅ Carte balance et bouton "Configurer les paiements" dans SellerDashboard -- ❌ Transfert automatique après paiement réussi (webhook Hyperswitch) - -## Implémentation prévue v0.603 - -1. **Injection StripeConnectService** dans `marketplace.Service` (optionnel) -2. **ProcessWebhook** : après `status == "succeeded"` et création des licences, pour chaque item : - - Récupérer le produit et son `seller_id` - - Vérifier si le vendeur a un compte Stripe Connect actif (`PayoutsEnabled`) - - Calculer le montant vendeur (total - commission plateforme - frais paiement) - - Appeler `stripeConnectService.CreateTransfer(sellerUserID, amount, "eur", orderID)` -3. **Gestion multi-produits** : une commande peut contenir des produits de vendeurs différents → un transfert par vendeur unique -4. **Commission plateforme** : configurable (ex. 10%), à définir dans config - -## Procédure manuelle (en attendant v0.603) - -En production, les vendeurs peuvent : -1. S'onboarder via Stripe Connect (bouton dans SellerDashboard) -2. Consulter leur balance (GET /sell/balance) -3. Les paiements arrivent sur le compte Stripe de la plateforme ; un processus manuel ou cron externe peut initier les transferts vers les comptes Connect des vendeurs +- ✅ Transfert automatique après paiement réussi +- ✅ Historique des transferts (GET /sell/transfers) +- ✅ Commission plateforme configurable (`PLATFORM_FEE_RATE`) ## Références - [Stripe Connect Transfers](https://stripe.com/docs/connect/charges#transfer-availability) +- [V0_603_RELEASE_SCOPE.md](V0_603_RELEASE_SCOPE.md) § 5 — Détail technique - `veza-backend-api/internal/services/stripe_connect_service.go` : `CreateTransfer` -- `veza-backend-api/internal/core/marketplace/service.go` : `ProcessWebhook` (L601-637) +- `veza-backend-api/internal/core/marketplace/service.go` : `processSellerTransfers`