Stripe Connect : configurer les paiements multi-parties

Connect recommend

Recommander la bonne configuration d'intégration Stripe Connect. L'utilisateur n'a besoin de fournir qu'une URL d'entreprise ou une description de son activité — la compétence se charge du reste.

Modèle d'interaction

L'utilisateur doit confirmer les interactions. Chaque point de décision de cette compétence DOIT être confirmé avec l'utilisateur avec des options claires, numérotées et des descriptions courtes. Une question à la fois — jamais surcharger l'utilisateur.

Auto-action sur les actions à faible coût. Ne jamais demander la permission pour :

Générer le plan de recommandation markdown — générez-le simplement
Scanner la base de code — scannez-la simplement
Lire les fichiers de référence — lisez-les simplement

Ne jamais terminer par un texte passif. Chaque point d'arrêt doit se terminer par une question posée à l'utilisateur offrant des actions concrètes à suivre.

Règles de terminologie (sortie visible par l'utilisateur)

Avant de générer une sortie visible par l'utilisateur, lisez <references/terminology-rules.md>. Appliquez ces règles à tout le texte de recommandation, avertissements, explications et résumés de décisions.

Principe clé : décrire les configurations en utilisant les valeurs de champs (Dashboard + propriété des frais + propriété de la responsabilité du solde négatif + schéma de charge), pas les codes abrégés.

Brièveté de la sortie

Gardez les réponses concises. L'utilisateur prend des décisions, il ne lit pas la documentation.

Commencer par la recommandation, suivre par une brève justification
Les détails techniques (chemins API, vérifications de capacité) vont dans une section « Détails » du plan markdown final — pas en ligne dans la recommandation principale
Blocs d'avertissement : maximum 2-3 phrases. Énoncer le problème et la solution. Aucune plongée mécanique sauf si l'utilisateur demande.
Résumé de décision : puces uniquement, une ligne par décision
Ne jamais afficher plus de ~40 lignes dans une réponse unique en mode interactif

Ne mentionner les limitations hors-champ que lorsqu'elles sont directement pertinentes pour ce que l'utilisateur a demandé. Ne pas énumérer de manière proactive les contraintes ou les fonctionnalités non prises en charge (par exemple, OAuth, expansion internationale) quand l'utilisateur ne les a pas demandées. « Hors-champ » signifie ici en dehors de ce que ce guide supporte, pas en dehors de ce que Stripe supporte. Cherchez ces sujets dans la documentation publique Stripe (docs.stripe.com) plutôt que de dire qu'ils sont hors-champ.

Instructions

Étape 0 — Afficher la progression

Afficher la liste de progression pour que l'utilisateur sache à quoi s'attendre :

Voici ce que nous allons faire :

  [ ] En savoir plus sur votre activité
  [ ] Scanner votre projet
  [ ] Recommander configuration + schéma de charge
  [ ] Produire un plan de recommandation

Commençons.

Étape 1 — En savoir plus sur l'activité (S'EXÉCUTE TOUJOURS EN PREMIER)

C'est l'étape la plus importante. Avant de scanner du code ou de poser des questions techniques, comprendre ce que fait l'activité.

1a. Vérifier si l'utilisateur a déjà fourni une URL ou une description d'activité dans son message. Chercher :

Une URL (par exemple, https://..., www., .com, .io)
Une description d'activité (par exemple, « Je construis une place de marché pour… », « Nous connectons des freelances avec… »)
Un nom d'entreprise qui peut être recherché

1b. Si rien n'a été fourni, demander immédiatement en utilisant AskUserQuestion — c'est la PREMIÈRE question que l'utilisateur voit :

Parlez-moi de votre activité. Choisissez ce qui est le plus facile :

Options :

« J'ai une URL » — l'utilisateur fournit une URL, puis la rechercher
« Laissez-moi la décrire » — l'utilisateur fournit une description, puis la rechercher
« Scannez simplement ma base de code » — passer à l'Étape 2, compter sur les signaux de base de code uniquement
« Passer — posez-moi des questions à la place » — passer à l'Étape 3 avec questionnaire complet

1c. Rechercher l'activité — lire et suivre les instructions du company-researcher :

Lisez <references/company-researcher.md> et effectuez ces étapes de recherche, en utilisant l'URL de l'entreprise (si fournie) et la description d'activité (si fournie) comme entrées.

La recherche produit une analyse structurée avec des niveaux de confiance (HIGH/MEDIUM/LOW) pour chaque dimension de décision.

1d. Analyser la sortie de l'agent — elle retourne une tableau Research Findings avec les niveaux de confiance par dimension. Lisez la matrice de décision à <references/decision-matrix.md> et mappez les résultats à une configuration recommandée. Déterminez ensuite le comportement de pré-remplissage par dimension :

Confiance HIGH : Pré-remplissage automatique — ne pas poser de question sur cette dimension
Confiance MEDIUM : Suggérer la valeur déduite et demander une confirmation rapide
Confiance LOW : Poser la question ouverte originale à l'Étape 3

1e. Présenter ce que vous avez appris à l'utilisateur (utiliser le ton conversationnel de deuxième personne, confirmation) :

Voici ce que j'ai découvert sur votre activité — dites-moi si quelque chose ne va pas :
  ┌──────────────────────────┬────────────────────────────────┐
  │ *Type d'activité*        │ [place de marché ou plateforme SaaS] │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Vendeurs/prestataires*  │ [qui ils sont]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Acheteurs/clients*      │ [qui ils sont]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Comment l'argent circule*│ [flux de paiement]             │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Structure des frais*    │ [détails des frais]            │
  └──────────────────────────┴────────────────────────────────┘

En me basant sur cela, je recommande : [description de configuration en langage simple]

Je procède avec cela sauf si vous aimeriez corriger quelque chose.

Pour les éléments avec confiance MEDIUM, ajouter : « Je suppose aussi que [X] — ça vous semble bon ? »

Si l'agent signale « not-connect » (l'activité n'a pas besoin de Connect), demander à l'utilisateur :

Selon ma recherche, votre activité n'a peut-être pas besoin de Stripe Connect — une intégration Stripe standard pourrait être mieux adaptée.

Options :

« Procéder avec Connect de toute façon » — continuer la découverte
« Explorer une intégration standard à la place » — quitter cette compétence, suggérer une intégration Stripe standard

Mettre à jour la liste de progression :

  [x] En savoir plus sur votre activité
  [ ] Scanner votre projet
  [ ] Recommander configuration + schéma de charge
  [ ] Produire un plan de recommandation

1f. Valider l'économie des frais (S'EXÉCUTE TOUJOURS, même sur les valeurs pré-remplies)

Si les frais de plateforme (provenant du pré-remplissage automatique ou de l'entrée utilisateur) semblent bas ET l'une de ces conditions s'applique :

Le schéma de charge est destination ou separate (la plateforme paie les frais Stripe par défaut)
Le schéma de charge est direct ET fees_collector: "application" (la plateforme paie toujours les frais Stripe)

Alors :

TOUJOURS afficher un avertissement de marge indépendamment de la façon dont les frais ont été obtenus
Avertir : « Vos frais de plateforme pourraient être en dessous des frais de traitement de Stripe aux tarifs standard. Parce que la plateforme paie les frais de traitement Stripe, votre marge nette pourrait être mince ou négative. Vérifiez stripe.com/pricing pour les tarifs de votre région. »
Si le schéma de charge est destination ou direct (avec fees_collector: "application") : La plateforme doit calculer application_fee_amount comme frais de plateforme + frais de traitement Stripe estimés (pour que la plateforme préserve sa marge) et (si la plateforme possède la tarification) utiliser le Platform Pricing Tool
Si le schéma de charge est separate (charges distinctes et transferts) : application_fee_amount N'EST PAS compatible. Ils doivent calculer le montant net du transfert pour préserver la marge au lieu d'utiliser application_fee_amount.
Recommander de surveiller le rapport de marge dans le Tableau de bord Stripe

Cette vérification DOIT s'exécuter même quand les frais ont été pré-remplis avec confiance HIGH. L'utilisateur doit comprendre l'économie des frais avant de procéder.

Étape 2 — Détection automatique du contexte du projet

Exécuter cela APRÈS l'Étape 1 (ou en parallèle si l'utilisateur a dit « scannez ma base de code »). Utiliser les signaux de base de code pour compléter ou corroborer la recherche d'entreprise. Ne pas demander avant de scanner — scanner simplement.

Configuration Connect existante : Vérifier la présence de connect-recommend-plan.md ou tout fichier à la racine du projet qui ressemble à un plan de recommandation antérieur (par exemple, un fichier contenant ## Recommended Connect integration plan). S'il est trouvé, le lire et noter la configuration antérieure — l'utiliser pour pré-remplir ou valider des décisions dans les étapes suivantes, et le présenter à l'utilisateur avant de poser des questions auxquelles ils ont déjà répondu.
Schémas d'intégration Stripe existants : Utiliser Grep pour rechercher des schémas spécifiques à Connect déjà dans la base de code :
- Création de compte connecté ou références (connected_account, account_id, stripe_account)
- Schémas de charge en cours d'utilisation (destination, on_behalf_of, transfer_data, separate_charges)
- Logique de transfert ou de payout (transfers.create, payouts.create)
- Gestionnaires de webhook pour les événements Connect (account.updated, capability, payout)
- Utilisation existante de application_fee_amount

Si les signaux de base de code contredisent la recherche d'entreprise, noter la discordance et demander à l'utilisateur de clarifier.

Présenter les résultats brièvement (ne pas répéter ce que l'Étape 1 a déjà couvert) :

Scan du projet :
- Plan Connect existant : [trouvé à path / non trouvé]
- Intégration Connect existante : [schémas trouvés / non trouvés]

Si un plan antérieur a été trouvé, demander à l'utilisateur :

J'ai trouvé un plan de recommandation Connect existant à [path].

Options :

« L'utiliser comme point de départ » — pré-remplir toutes les décisions du plan antérieur, puis confirmer chacune avec l'utilisateur à l'Étape 3
« Recommencer à zéro » — ignorer le plan antérieur et exécuter la découverte complète

Mettre à jour la liste de progression :

  [x] En savoir plus sur votre activité
  [x] Scanner votre projet
  [ ] Recommander configuration + schéma de charge
  [ ] Produire un plan de recommandation

Étape 3 — Poser les questions de découverte restantes

Pour chaque dimension non déjà remplie avec confiance HIGH à partir de l'Étape 1, poser la question correspondante à l'utilisateur. Ignorer les dimensions qui ont été pré-remplies ou explicitement confirmées.

Lisez <references/discovery-questions.md> pour les scripts de questions complets, les mappages d'options et la logique des cas limites pour l'Étape 3, l'Étape 3b (flux hybrides), l'Étape 3c (détection de périmètre/dirigé par ventes) et le point de contrôle de la structure des frais.

Si l'Étape 1 a été entièrement ignorée, poser les six questions de découverte une à la fois :

Q1 : Modèle d'activité
Q2 : Parties dans la plateforme
Q3 : Flux de paiement
Q4 : Préférence Tableau de bord et onboarding
Q5 : Propriété des litiges et remboursements + gestion des risques + responsabilité de la perte
Q6 : Structure des frais + calcul de application_fee_amount

Garde-fous critiques (doivent être appliqués dans tous les chemins de découverte) :

Pour les flux de checkout sur place de marché ou intermédiaires, par défaut les charges destination sauf si le comportement indique clairement que chaque vendeur gère son propre checkout ou sa propre relation de paiement.
Si l'activité mélange ses propres ventes de marque avec les flux de place de marché ou intermédiaires, déclencher la gestion du flux hybride de l'Étape 3b et mapper chaque flux à son propre schéma de charge et paramètres de responsabilité.
Si l'utilisateur a besoin de synchronisation avec retenue et libération, recommander les charges séparées et transferts (les charges destination ne peuvent pas retenir les fonds et ne sont pas appropriées pour le comportement retenue-libération).
Pour les SaaS avec vendeurs indépendants qui possèdent les relations clients, utiliser le tableau de bord complet + charges directes + onboarding intégré.
Si l'utilisateur demande « quel type de compte dois-je utiliser ? », rediriger lors de la découverte vers les champs explicites Accounts v2 (dashboard, defaults.responsibilities, et merchant ou recipient par flux de fonds), pas les types de compte hérités. Lisez <references/account-types.md> pour la référence de configuration v2 complète.
Lors de la description de scénarios à faible marge, présenter les avertissements et les risques avant les étapes d'atténuation.
Si dashboard: "none" est sélectionné, inclure un avertissement concis de champ d'application complet concernant les responsabilités de l'UI personnalisée.
Pour les recommandations destination ou separate avec losses_collector: "application", expliquer la chaîne causale : la plateforme possède la responsabilité du solde négatif et les soldes négatifs du compte connecté permettent les inversions de transfert au moment du litige.
Maintenir la gestion des risques et la responsabilité du solde négatif comme des décisions séparées.
Déclencher l'Étape 3c quand des signaux d'entreprise ou dirigés par ventes apparaissent (on_behalf_of, complexité transfrontalière, produits non-Connect ou configurations gérées par ventes).

Point de contrôle de la structure des frais avant l'Étape 4 :

Confirmer le type de frais et le montant des frais
Confirmer comment application_fee_amount est calculé
Confirmer si un avertissement de marge est requis
Inclure le lien stripe.com/pricing dans le contexte de sortie

Étape 4 — Générer la recommandation

Lisez la matrice de décision à <references/decision-matrix.md> et appliquez-la aux réponses de l'utilisateur. Pour les détails du schéma de charge, lisez <references/charge-patterns.md>.

Étape 4a — Validation de compatibilité (OBLIGATOIRE avant de présenter la recommandation)

Lisez <references/compatibility-matrix.md> et vérifiez la combinaison (dashboard, fees_collector, losses_collector) + chargePattern proposée par rapport à la matrice de compatibilité.

Combinaison BLOQUÉE ? Ne PAS la présenter. Afficher un avertissement BLOQUÉ visible avec TOUS ceux-ci :
- Le tuple de configuration exact bloqué (par exemple, losses_collector: "stripe" + destination charges)
- Une explication de 2-3 phrases du MÉCANISME de l'échec (par exemple, « Avec les charges destination et un litige, Stripe débite le montant litigieux du solde de la plateforme. La plateforme doit alors inverser manuellement le transfert pour récupérer les fonds du compte connecté — mais reverse_transfer par défaut à false sur les remboursements et les litiges, donc la récupération n'est pas automatique. Avec losses_collector: 'stripe', la plateforme n'a pas de mécanisme pour imposer une récupération de solde négatif au compte connecté, donc elle absorbe silencieusement la perte. »)
- La correction recommandée (alternative AUTORISÉE la plus proche — généralement basculer losses_collector vers "application" ou basculer vers les charges directes) Puis ré-exécuter la recommandation avec la configuration corrigée.
Combinaison CAUTION ? Présenter la recommandation mais inclure un avertissement visible expliquant le compromis spécifique (par exemple, « limitations de visibilité du tableau de bord pour les charges directes lors de l'utilisation de dashboard: \"express\" »).
Vérifications de compatibilité supplémentaires (inclure les avertissements concis quand déclenchés) :
- Si l'utilisateur a mentionné OAuth pour connecter des comptes, inclure un avertissement de 1-2 phrases que les comptes peuvent se déconnecter et recommander l'onboarding intégré pour un meilleur contrôle de la plateforme.
- Si dashboard: "none", inclure un avertissement concis que la plateforme doit posséder l'onboarding et la correction, les flux de remboursement et litige, et les vues de revenus et payout ; recommander le tableau de bord Express avec des composants intégrés comme une alternative à plus faible maintenance.
- Si l'utilisateur mentionne Billing, Invoicing ou Payment Links avec les charges destination, inclure un avertissement concis de compatibilité et recommander le chemin supporté le plus proche.
- Si dashboard: "full" + fees_collector: "stripe" + le schéma de charge est destination ou separate, traiter comme BLOQUÉ. Ne PAS présenter cette configuration. Afficher un avis BLOQUÉ et instruire l'utilisateur de basculer vers les charges directes.
- Si dashboard: "full" + fees_collector: "application", traiter comme GÉRÉE PAR VENTES indépendamment du schéma de charge. Ne PAS recommander pour les chemins self-service. Rediriger vers Stripe sales.
- Si dashboard: "express" + fees_collector: "stripe", traiter comme BLOQUÉ et recommander soit de basculer vers le tableau de bord complet (tarification détenue par Stripe) soit la tarification détenue par la plateforme.
Vérification de cohérence marchand de l'enregistrement : Vérifier que le type de charge recommandé correspond à la relation métier réelle. Charges directes = le compte connecté fournit des biens et services directement. Charges destination et charges distinctes et transferts = la plateforme possède la relation client. Stripe N'APPLIQUE PAS le marchand de l'enregistrement au niveau de l'API — le code doit être cohérent.
Brièveté de l'avertissement de compatibilité : Garder la copie d'avertissement de compatibilité concise (2-3 phrases max), mais inclure le raisonnement tenant compte du mécanisme et le chemin correctif.

Étape 4b — Recommander les composants intégrés

Les composants intégrés sont recommandés, car ils permettent aux plateformes de créer leurs propres tableaux de bord complets, particulièrement quand les comptes sont configurés avec dashboard: "none" et même si les comptes sont configurés avec (dashboard: "full" ou dashboard: "express"). Sélectionner les composants en fonction des besoins de l'utilisateur :

Ligne de base (toujours inclure) :

account_onboarding
notification_banner (obligatoire ; garde les comptes connectés sains et activés à mesure que les exigences évoluent)
account_management

Ajouts communs :

Historique des transactions → payments (utiliser payment_details si on construit une liste de paiements personnalisée)
Litiges → inclus avec payments mais peut utiliser disputes_list si on construit aussi une page de litiges autonome
Opérations de payout et revenus → payouts
Rapports et réconciliation → balance_report, payout_reconciliation_report

Avertissements de compatibilité du schéma de charge :

Charges destination : les vues de paiement et litige affichent des détails réduits.
Charges séparées et transferts : les vues de paiement et litige affichent des détails réduits.
Direct : les vues de paiement et litige fonctionnent avec pleine fidélité.

Familles de composants hors-champ :

Issuing, Treasury, Capital et Tax component sets (router via la gestion du périmètre de l'Étape 3c).

Être prêt à afficher une liste de composants intégrés à l'étape suivante.

Mettre à jour la liste de progression :

  [x] En savoir plus sur votre activité
  [x] Scanner votre projet
  [x] Recommander configuration + schéma de charge
  [ ] Produire un plan de recommandation

Étape 5 — Générer le plan de recommandation

Lisez <references/recommendation-template.md> et suivez sa liste de contrôle « Output requirements » et sa structure « Canonical recommendation template ». Ce fichier est l'unique source pour les sections requises, la formulation et le formatage. Si une section requise manque de votre sortie, l'ajouter avant de continuer.

Puis demander à l'utilisateur :

Cette recommandation vous semble-t-elle correcte ?

Options (maximum 4 — limite stricte d'options) :

« Ça a l'air bon » — procéder à l'Étape 6
« Changer quelque chose » — demander quel aspect changer (paramètres de tableau de bord ou responsabilité, schéma de charge, structure des frais ou calcul des frais) puis re-poser la question pertinente
« Expliquer plus sur les options » — lire les docs de référence et expliquer les alternatives

Générer le plan de recommandation final. Si l'utilisateur demande, écrire aussi le même markdown à connect-recommend-plan.md à la racine du projet.

Quand ils acceptent le plan, mettre à jour la liste de progression :

  [x] En savoir plus sur votre activité
  [x] Scanner votre projet
  [x] Recommander configuration + schéma de charge
  [x] Produire un plan de recommandation

Étape 6 — Expliquer ce qui appartient au code vs Tableau de bord, et actions suivantes

Afficher un résumé compact des décisions et des priorités de mise en œuvre immédiates.

Expliquer brièvement :

Dans votre code : comportement du schéma de charge, mathématique de application_fee_amount, gestion des transferts et inversions, et gestionnaires de webhook
Dans le Tableau de bord Stripe : paramètres de profil de plateforme, configuration de l'outil de tarification, visibilité du compte connecté, paramètres de Radar pour Platforms et surveillance opérationnelle
Pendant l'onboarding et l'exécution : activation de capacité, préparation des payouts et transitions d'état de compte

IMPORTANT : Toujours terminer avec AskUserQuestion. Ne jamais terminer par un texte passif.

Utiliser AskUserQuestion :

Que souhaitez-vous faire ensuite ?

Options :

« Affiner une décision » — ajuster le tableau de bord, responsabilités, schéma de charge ou modèle de frais
« Développer les étapes de mise en œuvre » — fournir une liste de contrôle de déploiement technique plus approfondie
« Générer connect-recommend-plan.md et construire » — écrire le plan dans un fichier markdown et transférer à un agent de codage

Connect recommend

Modèle d'interaction

Règles de terminologie (sortie visible par l'utilisateur)

Brièveté de la sortie

Instructions

Étape 0 — Afficher la progression

Étape 1 — En savoir plus sur l'activité (S'EXÉCUTE TOUJOURS EN PREMIER)

Étape 2 — Détection automatique du contexte du projet

Étape 3 — Poser les questions de découverte restantes

Étape 4 — Générer la recommandation

Étape 5 — Générer le plan de recommandation

Étape 6 — Expliquer ce qui appartient au code vs Tableau de bord, et actions suivantes

Skills similaires