Le client a obtenu son remboursement, mais le back-office affiche encore « échec ». Le vendeur avait déjà reçu sa part ; la tentative de récupération sur son compte connecté a été refusée. Un opérateur relance alors le bouton global « rembourser ». Ce défaut de lecture peut transformer une difficulté de recouvrement vendeur en second remboursement acheteur, avec une perte supplémentaire et une charge support difficile à expliquer.
La vraie question est de savoir quelle opération a échoué. Avec Stripe Connect et des encaissements suivis de transferts séparés, la restitution au client et la reprise des fonds vendeur sont deux objets différents. Leur suivi doit rester distinct jusque dans les écrans, les alertes et la clôture financière. Un statut unique ne suffit pas à représenter cette situation.
Le scénario fictif suit une commande de 100 euros, deux vendeurs et un remboursement partiel de 20 euros. Il montre pourquoi la somme à reprendre au vendeur peut être de 18 euros, comment traiter une réponse perdue et quelles preuves permettent de fermer le dossier. Un programme local fournit 26 contrôles et trois témoins incorrects, sans exécuter de paiement ni appeler Stripe.
Cette conception fait partie de la création d’une marketplace opérateur. Le cadrage des paiements, du PSP et de la sécurité marketplace doit relier la décision commerciale, les mouvements externes et les outils des équipes qui traitent réellement les exceptions.
Pour qui : un retour client après le transfert au vendeur
Identifier le montage de paiement avant le diagnostic
Ce parcours concerne une plateforme qui encaisse sur son compte puis effectue des transferts vers des comptes connectés. Il ne décrit pas indifféremment tous les montages Connect. La documentation sur les remboursements via une plateforme distingue les paiements directs, qui débitent le compte connecté, des destination charges et des encaissements avec transferts séparés, qui débitent la plateforme.
Relevez donc le type de charge, le compte propriétaire du paiement, les transferts liés et la devise. Le fait qu’un vendeur utilise Stripe ne permet pas de déduire ces relations. Un diagnostic fondé sur le mauvais montage risque de rechercher le remboursement dans le mauvais compte ou de proposer une option qui ne correspond pas au paiement initial.
Conserver le périmètre commercial déjà validé
Le dossier commence après une décision de remboursement qualifiée : ligne concernée, motif accepté, montant acheteur et traitement de la commission. Les règles de rétractation, de taxe, de livraison et de documents comptables doivent avoir été validées pour votre activité. Notre exercice les simplifie volontairement afin d’étudier la séparation des opérations, pas de fournir une règle fiscale ou contractuelle universelle.
Le problème apparaît notamment avec un retour tardif, un service partiellement annulé ou une correction après le cycle de versement. Il touche le support acheteur, les opérations vendeurs, la finance et l’équipe paiement. Chacun doit lire la même commande tout en conservant une prochaine action propre à son domaine ; personne ne devrait reconstruire le montant à partir d’un message d’erreur.
Séparer remboursement, reprise de transfert et virement bancaire
La documentation des encaissements et transferts séparés précise qu’un remboursement de la charge ne modifie pas automatiquement les transferts associés. La plateforme organise le rapprochement des sommes à récupérer. Cette indépendance explique pourquoi le client peut être remboursé alors que le volet vendeur reste ouvert.
| Objet | Ce qu’il établit | Ce qu’il ne prouve pas |
|---|---|---|
| Refund | Le montant et l’état de la restitution acheteur. | La récupération sur le vendeur. |
| Transfer reversal | La reprise d’une part du transfert concerné. | La réception du remboursement par l’acheteur. |
| Payout | Le virement depuis un solde Stripe vers un compte bancaire. | L’annulation d’un transfert Connect antérieur. |
Relier les objets sans leur donner le même statut
Dans le back-office proposé, un dossier de retour possède deux volets : « remboursement acheteur » et « récupération vendeur ». Chaque volet conserve son identifiant externe, son montant, sa devise et sa dernière preuve. Une corrélation interne les relie à la sous-commande concernée. Le paiement global et le transfert du second vendeur restent visibles, mais ne deviennent pas des cibles de correction par proximité.
La référence Refund expose notamment les états pending, requires_action, succeeded, failed et canceled. Ils ne constituent pas les états de notre dossier de récupération. Les libellés internes « reprise à examiner » ou « réponse à rapprocher » sont des choix de conception ; ils ne doivent pas être présentés comme des statuts officiels de l’API.
Exemple : 20 euros remboursés, 18 euros à récupérer
Reconstituer les montants avant le retour
La commande fictive C100 vaut 100 euros : 65 euros pour le vendeur A et 35 euros pour B. Notre convention pédagogique retient une commission de 10 % et la restitue proportionnellement sur la partie annulée. Les transferts sont donc de 58,50 euros pour A et de 31,50 euros pour B. L’opérateur conserve 10 euros avant frais de paiement et autres coûts.
Nous supposons tous les fonds initiaux disponibles et une trésorerie de départ de 50 euros appartenant à la plateforme, en plus de cette commande. Après encaissement et transferts, cette trésorerie simplifiée vaut 60 euros. Elle permet de financer le remboursement sans supposer que Stripe accepte une sortie non provisionnée. Les taxes, frais PSP, autres commandes et éventuelles réserves sont exclus du calcul pédagogique.
Réduire la part du bon vendeur
Le retour concerne 20 euros chez A. La convention retenue annule 2 euros de commission ; la part vendeur à récupérer est donc de 18 euros. Après la correction, la vente nette de A vaut 45 euros, sa commission 4,50 euros et sa part finale 40,50 euros. B conserve ses 31,50 euros : sa ligne n’a pas été retournée.
Le contrôle économique retrouve 80 euros de vente nette, 72 euros de parts vendeurs et 8 euros de commission brute. Reprendre 20 euros à A tout en annulant 2 euros de commission créerait une sur-récupération. À l’inverse, afficher seulement la vente nette de 80 euros masquerait les 18 euros encore dus si la reprise échoue. Le calcul et la disponibilité des fonds sont deux questions distinctes.
| Moment | Contribution de C100 | Trésorerie simplifiée |
|---|---|---|
| Après transferts | 100 − 90 = 10 € | 50 + 10 = 60 € |
| Client remboursé | 100 − 90 − 20 = −10 € | 50 − 10 = 40 € |
| Après reprise | 100 − 90 − 20 + 18 = 8 € | 50 + 8 = 58 € |
La contribution de −10 euros n’est pas un solde Stripe négatif : le compte simplifié dispose encore de 40 euros. C’est l’effet isolé de cette commande avant récupération. Les 8 euros finaux ne sont pas un bénéfice net ; les coûts exclus doivent rejoindre le rapprochement réel. Cette distinction évite de présenter une marge théorique comme une somme immédiatement disponible.
Traiter un refus de reprise sans relancer le remboursement
Vérifier la preuve de chaque côté
La référence des reprises de transfert indique qu’une reprise de transfert de groupe exige un solde suffisant sur le compte destinataire. Dans notre cas, aucune facilité particulière de réserve n’est supposée. Le vendeur A n’a plus les fonds disponibles nécessaires ; la récupération des 18 euros échoue, tandis que le Refund de 20 euros est observé succeeded.
L’écran doit alors conserver « remboursement réussi côté PSP » et ouvrir « récupération vendeur à traiter : 18 euros ». Il ne doit ni marquer l’ensemble comme échoué ni inventer un crédit bancaire déjà vu par le client. La référence du remboursement et son état servent au support acheteur ; le refus de reprise, le transfert initial et le montant restant servent à la finance vendeur.
Attribuer la décision de financement et de récupération
Un refus technique ne décide pas du contrat vendeur. La finance qualifie les moyens autorisés pour récupérer le montant, par exemple une compensation documentée sur un versement futur lorsque le cadre applicable le permet. L’application ne doit pas prélever un autre vendeur, contourner les restrictions du PSP ou lancer un débit externe parce que le premier mouvement a échoué.
Le responsable fixe une échéance de revue et conserve le montant ouvert. Dans le scénario, une alerte interne après un jour ouvré sans décision est un seuil d’exploitation proposé, pas un délai Stripe ni une obligation générale. Le risque est de croire qu’une nouvelle vente règlera forcément le problème : tant qu’aucun mouvement qualifié n’a soldé les 18 euros, le dossier reste à rapprocher.
Distinguer un refus connu d’une réponse de reprise perdue
Conserver la même intention lorsqu’une réponse manque
Une coupure réseau après l’envoi d’une reprise ne prouve pas son refus. La demande a peut-être été exécutée, mais sa réponse n’est pas revenue. Le support ne peut pas utiliser le même bouton que pour un échec certain. Le dossier doit afficher l’incertitude, la tentative concernée et l’action de rapprochement, sans annoncer immédiatement que les fonds restent intégralement à reprendre.
Les requêtes idempotentes Stripe protègent les reprises d’un même appel. Pour l’API v1, la première réponse enregistrée est rejouée avec la même clé, y compris une erreur 500 ; des paramètres différents sont refusés. La rétention de ces clés n’est pas illimitée. Une clé conservée localement ne dispense donc pas de vérifier l’objet externe avant une nouvelle tentative tardive.
Ne pas transformer un retry en nouvelle décision financière
Notre proposition sépare l’identifiant du dossier, l’intention financière et les tentatives techniques. Une nouvelle tentative autorisée après un refus confirmé garde le lien avec la même somme à récupérer ; elle ne crée pas une deuxième dette vendeur. Si la première opération demeure incertaine, l’équipe rapproche les reprises associées au transfert avant de préparer un nouvel envoi.
La création d’une reprise de transfert accepte des reprises partielles, dans la limite du montant encore réversible. Cette limite PSP ne remplace pas notre limite métier de 18 euros : le transfert initial de 58,50 euros pourrait permettre techniquement un montant supérieur à celui du retour. Le système contrôle les deux plafonds séparément.
Recevoir les événements sans écraser une preuve plus récente
Utiliser le webhook comme signal de rapprochement
Stripe précise que les événements ne sont pas livrés dans un ordre garanti. Un événement répété ou tardif ne doit pas remettre le dossier entier en attente. Vérifiez la signature, identifiez le compte et l’objet concernés, puis rapprochez l’état utile. L’heure de création d’un événement n’est pas, à elle seule, un ordre total fiable.
Le worker reçoit des entrées portant les références PSP et produit des sorties limitées au volet concerné. Sa responsabilité est de mettre à jour la preuve, pas de décider un nouveau remboursement. Une file durable, la journalisation des identifiants et un runbook de rapprochement permettent de reprendre après panne sans utiliser la réception d’un événement comme autorisation de mouvement supplémentaire.
Protéger la clôture contre les copies et les écritures concurrentes
Une même reprise reçue deux fois ne vaut pas 36 euros récupérés. Le registre doit conserver une seule preuve par identifiant de reprise et contrôler ses attributs. Deux observations portant le même identifiant avec des montants différents demandent une investigation. Additionner les notifications, même authentiques, mesure les livraisons de messages plutôt que l’argent récupéré.
La clôture possède son propre contrat : montant attendu, reprises qualifiées, incertitudes résolues et validation du dossier client. Le seuil d’écart retenu dans notre exercice est zéro centime. La dépendance au rapprochement PSP reste explicite ; le repli en cas de donnée inconnue maintient une revue ouverte. Un rollback applicatif ne rappelle pas un remboursement déjà exécuté et ne doit jamais effacer sa trace.
Présenter deux actions lisibles dans le back-office
Éviter le bouton « tout recommencer »
La fiche C100 affiche la ligne A retournée, le remboursement de 20 euros et la récupération attendue de 18 euros. Après réussite du Refund, l’action de remboursement correspondant à cette décision n’est plus proposée. Le volet vendeur affiche le refus connu ou l’incertitude de réponse, avec une action adaptée aux droits : consulter les preuves, préparer un rapprochement ou soumettre une décision de récupération.
Le libellé doit expliquer l’effet avant toute validation. « Reprendre 18 euros sur le transfert A » n’a pas le même sens que « rembourser 20 euros au client ». Une interface sur mesure peut rendre cette différence évidente sans exposer tous les noms d’objets API. Elle doit néanmoins conserver les références techniques dans une zone de diagnostic accessible aux personnes habilitées.
Donner une explication cohérente à chaque interlocuteur
L’acheteur reçoit le montant, l’état du remboursement et la référence utile lorsqu’elle est disponible. Le vendeur reçoit la part annulée, le crédit de commission et le montant à récupérer. Le support interne voit les deux volets, sans partager avec l’un les données financières privées de l’autre. Les exports comptables reprennent la même corrélation pour éviter une seconde correction manuelle.
La qualité du parcours se mesure aussi sur mobile et avec une navigation au clavier : montants lisibles, état non porté uniquement par une couleur, action nommée et preuve accessible. Une étiquette verte « terminé » peut être trompeuse si elle concerne seulement le client. La synthèse doit dire « client traité, récupération vendeur ouverte » tant que cette lecture correspond aux observations.
Exécuter 26 contrôles sur les montants et les décisions
Rejouer le scénario sans effectuer de transaction
Le programme remboursement_reprise.py utilise des identifiants fictifs et la bibliothèque standard Python. Il reçoit des observations déjà qualifiées ; ce n’est ni un client Stripe ni un consommateur de webhooks. Il vérifie la contribution de la commande, le reste à récupérer et les décisions affichées lorsque le client est traité, que la reprise manque ou que sa réponse est incertaine.
Les cas incluent une reprise de 18 euros, deux reprises de 10 et 8 euros, la copie d’une même preuve et une preuve contradictoire. Le script refuse un autre vendeur, un autre transfert, une autre devise ou une récupération de 20 euros pour cette décision. Les états pending, requires_action, failed et canceled du Refund restent en revue client ; ils ne sont jamais convertis en réussite par la seule présence d’une reprise.
python3 remboursement_reprise.py
# 26 contrôles réussis ; 3 témoins incorrects détectés
# Reprise absente : 18 EUR restent à examiner
# Reprise de 18 EUR : contribution brute 8 EURConnaître les limites de la démonstration
Trois témoins volontairement incorrects rendent les erreurs visibles. Le premier déclare le client en échec parce qu’aucune reprise n’existe. Le deuxième récupère les 20 euros bruts et produit 10 euros de contribution au lieu de 8. Le troisième additionne deux copies de la même reprise et annonce 36 euros récupérés. Les résultats attendus sont écrits indépendamment de ces variantes fautives.
Ces contrôles ne prouvent pas la disponibilité d’un solde distant, la réception bancaire du client ou l’absence de concurrence dans votre base. Ils ne couvrent pas les taxes, les devises croisées ni la comptabilité générale. La recette d’intégration doit ensuite vérifier les comptes, les droits, la version API, les réponses et les notifications réelles dans un environnement de test autorisé.
Erreurs fréquentes : une somme juste peut rester mal attribuée
- À vérifier : le compte du paiement, la sous-commande, le transfert et la politique de commission avant de calculer le reste vendeur.
- À suspendre : une nouvelle tentative financière lorsque la précédente n’a pas de résultat rapproché.
- À refuser : la clôture automatique sur un simple total, sans identité des preuves ni séparation du volet acheteur.
Confondre le solde global et l’exposition d’une commande
Paradoxalement, un compte Stripe suffisamment approvisionné peut cacher une défaillance de récupération répétée. La plateforme rembourse les clients grâce à d’autres fonds, tandis que les reprises vendeurs restent ouvertes. Le service client paraît fonctionner ; la trésorerie finance pourtant un encours que personne ne mesure correctement. Dans C100, les 40 euros disponibles après remboursement ne suppriment pas les 18 euros à récupérer.
Suivez l’encours par vendeur, son ancienneté et la cause de blocage, puis rapprochez-le des mouvements qualifiés. Un indicateur global de remboursement réussi ne répond pas à cette question. La marge et le coût de support deviennent lisibles lorsque le reporting distingue ce qui a été rendu au client, ce qui a été récupéré et ce qui reste sous décision.
Transformer une correction métier en paramètre magique
Un champ de remboursement de frais applicatifs ne calcule pas votre contrat de commission. Dans le montage simplifié, l’opérateur a conservé sa part en transférant moins aux vendeurs ; le crédit de 2 euros découle de notre convention commerciale. Il doit être relié aux documents et au relevé vendeur selon le modèle retenu, sans être assimilé automatiquement à un objet application fee présent dans tous les paiements.
De même, le rapprochement de deux montants égaux ne suffit pas. Une reprise de 18 euros sur B serait incorrecte même si le total global semblait équilibré. Les identifiants de vendeur, transfert, devise et décision sont des conditions de validité. Cette rigueur protège la confiance des partenaires autant que l’exactitude des chiffres affichés dans le tableau de bord.
Plan d’action : recevoir un retour complet avant d’automatiser
Définir la décision et son périmètre de paiement
Choisissez une commande de test représentative de votre montage réel, avec deux vendeurs et un retour portant sur un seul. Écrivez d’abord les montants attendus : paiement, transferts, commission initiale, crédit de commission, remboursement et récupération. Faites valider cette ventilation par la finance et les responsables du contrat vendeur. La référence de cette décision doit survivre aux tentatives techniques et aux changements d’équipe.
Inventoriez ensuite les objets PSP qui prouvent chaque étape. Vérifiez le compte propriétaire, les devises, le type de charge et le rattachement des transferts. Définissez ce que le support peut lire, proposer et exécuter. Si une preuve manque, documentez l’incertitude au lieu de fabriquer un lien au montant. Le résultat de cette phase est une fiche de réception utilisable par une personne qui n’a pas développé le connecteur.
Éprouver les états qui rendent les actions ambiguës
Exécutez le cas nominal, puis le refus de reprise, la réponse perdue, le message répété et la récupération partielle. Préparez aussi un remboursement client encore en attente : son écran ne doit pas annoncer une réussite parce que le volet vendeur est correctement calculé. Comparez les résultats dans la vue opérateur, le relevé vendeur et l’export de rapprochement. Chaque différence doit avoir une cause attribuée et une prochaine action.
Conservez les preuves des contrôles et les résultats attendus avant d’élargir le périmètre. Testez les protections de concurrence de votre implémentation réelle ; le programme pédagogique ne les fournit pas. Faites rejouer un dossier par une autre personne avec le runbook, sans expliquer oralement quel bouton éviter. Si cette personne peut déclencher un second remboursement pour résoudre un refus vendeur, le parcours n’est pas reçu.
- Support : état du client, référence utile et action autorisée.
- Finance : montant récupéré, reste ouvert et décision de traitement.
- Technique : corrélation, tentatives, preuves externes et reprise sans doublon.
Ouvrir progressivement et surveiller l’encours
Commencez avec un périmètre dont les règles sont stables et les exceptions connues. Mesurez les dossiers sans preuve externe, les tentatives incertaines et les reprises refusées, en séparant leur nombre de leur montant. Attribuez les délais de revue selon le risque et la capacité réelle des équipes. Un seuil doit déclencher une action nommée ; il ne doit pas devenir un objectif qui encourage à masquer les cas difficiles.
Étendez ensuite aux autres motifs, politiques de commission et moyens de paiement avec une recette dédiée. Une variante transfrontalière ou multidevise ne doit pas hériter silencieusement des hypothèses EUR de C100. La maintenance du dispositif comprend les droits, les changements de version, les exports et la lisibilité des relevés. Le critère de réussite reste la capacité à expliquer et reprendre chaque opération, même lorsqu’un seul côté du dossier est terminé.
Approfondir la répartition, les reversements et les blocages
Le dossier sur la répartition d’un remboursement partiel traite les assiettes, les remises et les documents à corriger. Celui sur les commissions, avoirs et réserves dans les reversements replace la récupération dans le cycle financier complet, avant et après sa date de coupe.
Pour qualifier un blocage en amont, consultez le diagnostic Stripe Connect des paiements, transferts et virements. Le dossier sur les litiges Stripe clos et leur résultat couvre une autre erreur de lecture : confondre la fermeture d’un litige avec une issue favorable. Ces parcours partagent le besoin de preuves, mais leurs objets et leurs décisions restent différents.
Conclusion : fermer le bon volet sans effacer l’autre
Un remboursement acheteur réussi et une reprise vendeur refusée peuvent coexister. La marketplace doit montrer cette réalité sans la réduire à une erreur globale. Le dossier garde la preuve du remboursement, le transfert concerné, le montant encore ouvert et la personne chargée de décider la suite.
Dans C100, le client reçoit une restitution de 20 euros côté PSP et la récupération attendue vaut 18 euros selon la commission retenue. Les 26 contrôles locaux distinguent ce calcul de la disponibilité distante et détectent trois méthodes erronées. La clôture devient explicable lorsque les montants, les identifiants et les incertitudes racontent la même opération.
Le parcours de paiement et de sécurité marketplace donne un cadre à cette séparation : droits, preuves, décisions financières et reprise après panne. Le prestataire de paiement fournit ses objets et ses limites ; l’application doit les transformer en actions compréhensibles pour vos équipes.
Dawap accompagne la création de marketplaces sur mesure en reliant commandes, vendeurs, paiements et back-office. Vos équipes peuvent ainsi traiter les exceptions sans rejouer un effet déjà réussi ni perdre la trace de ce qui reste à récupérer.
