Créer une marketplace sur mesure avec Stripe Connect

Créer une marketplace transactionnelle demande de concevoir un système financier autant qu’un produit numérique. Avant le premier écran de paiement, les décisions portent sur l’entité qui encaisse, le merchant of record, le moment où la part du vendeur change de solde et la prise en charge d’un remboursement ou d’un litige.

Stripe Connect fournit les comptes connectés, les flux de paiement, les transferts et l’onboarding réglementaire. Il ne décide pas du contrat commercial ni de la politique de risque. Une marketplace sur mesure doit traduire ces décisions dans son checkout, ses données, son back-office et ses procédures. Aucune configuration Stripe ne convient à tous les projets.

Créer une marketplace commence par qualifier chaque flux

Une marketplace collecte le paiement du client dans son propre parcours puis distribue les fonds aux vendeurs. Une SaaS platform équipe des entreprises indépendantes qui encaissent leurs propres clients. Cette distinction, décrite dans la documentation Stripe sur les marketplaces et SaaS platforms, se vérifie transaction par transaction.

Le merchant of record est l’entreprise que le client paie pour une transaction. Son nom apparaît normalement sur le reçu ou le relevé, et le client s’attend à ce qu’elle traite les problèmes de paiement, remboursements compris. Le contrat, les CGV, le checkout, le descripteur bancaire et le support doivent désigner la même relation commerciale.

Une direct charge place le paiement sur le compte connecté, qui est alors merchant of record. Une charge créée sur la plateforme la place généralement dans ce rôle, sauf usage de on_behalf_of. Cette option modifie aussi le règlement et le descripteur. Elle mérite une validation avec Stripe et un juriste, surtout si plusieurs pays entrent dans le flux.

Le test tient en quatre questions :

• Identifiez le nom affiché pendant le paiement et sur le relevé du client.
• Désignez l’entité qui fournit ou assume contractuellement le bien ou le service.
• Attribuez les remboursements, les litiges et le support paiement.
• Vérifiez qui conserve les preuves et répond au client en cas de contestation.

Une même entreprise peut avoir plusieurs réponses. Un logiciel peut facturer son abonnement pour son propre compte et, sur un autre flux, laisser ses utilisateurs encaisser leurs clients. Cette architecture hybride exige deux modèles explicites. Le sujet des rôles, du matching et de la modération est traité à part dans notre guide pour concevoir une plateforme de mise en relation.

Accounts v2 sépare le Dashboard, les frais et les soldes négatifs

Pour une nouvelle intégration, le choix « Standard, Express ou Custom » est une terminologie historique trop grossière. Accounts v2 sépare les décisions qui étaient auparavant regroupées.

L’accès vendeur vient d’abord. Un Dashboard Express (dashboard: "express") donne une vue Stripe limitée et cobrandée. Le Dashboard complet (dashboard: "full") correspond mieux à un marchand indépendant. Sans Dashboard (dashboard: "none"), la plateforme doit construire les vues de paiement, de remboursement, de litige, de solde, de payout et de remédiation KYC. Ce dernier choix engage l’équipe pendant toute la vie du produit. Il ne devrait jamais être motivé par la seule envie d’effacer la marque Stripe.

Deux responsabilités suivent :

• La collecte des frais indique si la plateforme gère la tarification (fees_collector: "application") ou si Stripe facture le compte connecté (fees_collector: "stripe") pour les direct charges concernées.
• La responsabilité des soldes négatifs indique si la plateforme (losses_collector: "application") ou Stripe (losses_collector: "stripe") absorbe les soldes négatifs non recouvrés des comptes connectés.

Ces valeurs ont des contraintes de compatibilité. Le Dashboard Express impose actuellement une collecte des frais et une responsabilité des soldes négatifs côté plateforme. Le Dashboard complet impose les deux responsabilités côté Stripe. Pour les destination charges et les separate charges and transfers, les frais de paiement sont débités à la plateforme.

La configuration du compte dépend ensuite de son rôle. configuration.recipient suffit à un vendeur qui reçoit des transferts. La plateforme demande alors la capacité configuration.recipient.capabilities.stripe_balance.stripe_transfers et vérifie son statut active avant chaque transfert. configuration.merchant et sa capacité card_payments servent au marchand qui accepte directement les paiements. configuration.customer couvre une autre relation, par exemple quand la plateforme facture aussi un abonnement au même compte.

Demander toutes les capacités « au cas où » rallonge l’onboarding et peut ajouter des pièces à fournir. On demande le minimum lié au flux lancé.

Le KYC continue après l’inscription. L’onboarding hébergé ou intégré prend en charge la collecte et suit les évolutions réglementaires, mais le produit doit encore afficher les restrictions, relancer le vendeur et bloquer une opération incompatible avec l’état du compte. Une collecte initiale de currently_due et eventually_due réduit les demandes ultérieures. Une collecte progressive raccourcit l’entrée, au prix de nouvelles remédiations plus tard. Le bon choix dépend du coût métier d’une interruption.

Pourquoi on ne choisirait jamais un flux Stripe avant le merchant of record

Le charge pattern est la conséquence d’une relation commerciale. Le choisir d’abord pousse le contrat et le support à s’adapter à une décision technique déjà codée.

On voit alors une marketplace retenir les direct charges parce que « l’argent va au vendeur », même si la plateforme contrôle le checkout, le reçu et les remboursements. Ou une équipe choisir les destination charges alors que le vendeur ne doit recevoir sa part qu’après une validation de livraison. Dans le premier cas, la propriété des objets Stripe et la relation comprise par le client se contredisent. Dans le second, le transfert automatique part trop tôt.

Notre position est simple : on rédige d’abord une fiche par flux avec le merchant of record, le bénéficiaire, le moment du transfert, la politique de remboursement et la responsabilité des soldes négatifs. Le tableau Stripe vient après. Ce travail paraît administratif jusqu’au premier litige. À ce moment-là, il détermine quel solde est débité et quelle équipe doit agir.

Les anciens types de comptes ne corrigent pas ce défaut de conception. Accounts v2 rend les responsabilités plus visibles, sans les choisir à la place de l’entreprise.

Comparer direct, destination et separate charges and transfers

Les trois modèles de charges Connect répondent à des flux différents. Ce tableau donne des configurations de travail, pas des prescriptions.

Les direct charges conviennent quand chaque marchand possède sa relation de paiement. Le PaymentIntent, la charge et les événements vivent dans le contexte du compte connecté. La plateforme peut prélever une application fee, mais elle doit aussi gérer cette séparation dans ses webhooks et ses rapports.

Les destination charges servent un paiement créé sur la plateforme avec un seul destinataire connu. transfer_data.destination déclenche le transfert après la capture. Elles ne servent pas à attendre une livraison avant de transférer.

Les separate charges and transfers dissocient le paiement et le transfert. La plateforme peut répartir un paiement entre plusieurs comptes, choisir le bénéficiaire plus tard ou déclencher le transfert après une étape métier. La commission est la différence entre le montant encaissé et la somme transférée. application_fee_amount ne s’applique pas à ce modèle.

sequenceDiagram
    participant A as Acheteur
    participant P as Marketplace
    participant S as Stripe
    participant C as Compte connecté
    participant B as Banque du vendeur

    A->>P: Confirme la commande
    P->>S: Crée et confirme le paiement
    S-->>P: Événement de paiement
    P->>P: Écrit le ledger et valide l’étape métier
    P->>S: Crée le transfert si le flux l’exige
    S->>C: Crédite le solde Stripe
    S->>B: Exécute le payout selon le calendrier
    S-->>P: Envoie les événements de transfert et payout
    P->>P: Réconcilie les mouvements

Un transfer déplace des fonds du solde Stripe de la plateforme vers celui du compte connecté. Un payout envoie le solde Stripe du compte connecté vers sa banque ou une carte éligible. Retarder le payout ne retarde pas le transfer. De même, différer un transfert avec separate charges and transfers ne crée pas un séquestre juridique.

Commissions et remboursements doivent partager la même règle

La commission ne se limite pas à un pourcentage affiché dans le back-office. Son calcul doit préciser l’assiette HT ou TTC, les arrondis, la devise, les frais de paiement, la TVA sur la commission et son traitement lors d’un remboursement partiel.

Sur une destination charge, la marge avant coûts internes peut s’écrire :

application_fee_amount − frais Stripe − commission remboursée − pertes non récupérées

La plateforme peut aussi fixer la part vendeur avec transfer_data.amount. Sur separate charges and transfers, elle conserve la différence entre le paiement et la somme des transferts, puis déduit les frais et mouvements négatifs. Les tarifs varient selon le pays, la devise et le moyen de paiement. La tarification Stripe du pays concerné et le ledger donnent la marge réelle. Le margin report Stripe aide sur les flux pris en charge, mais n’inclut pas les separate charges and transfers.

Le piège du remboursement sans reversal

Symptôme

Le client voit son remboursement. Le vendeur conserve pourtant la somme déjà transférée, tandis que le solde de la plateforme baisse du montant remboursé.

Diagnostic

Le remboursement a annulé tout ou partie de la charge, sans inverser le transfert associé. Sur une destination charge, reverse_transfer vaut faux par défaut. Sur separate charges and transfers, le remboursement ne modifie aucun transfert. Un litige ne crée pas non plus automatiquement le transfer reversal attendu par la règle métier.

Correction

La politique doit décider, pour chaque motif et chaque remboursement partiel, quelle part vendeur récupérer et si l’application fee est remboursée. Sur une destination charge, le remboursement peut utiliser reverse_transfer: true et décider séparément de refund_application_fee. Sur separate charges and transfers, la plateforme inverse explicitement chaque transfert concerné. Elle inscrit remboursement et reversals dans le ledger, contrôle les arrondis puis réconcilie les mouvements. La documentation Stripe sur les remboursements et litiges détaille ces mécanismes.

Un reversal peut rendre le solde connecté négatif. La détection de fraude avec Radar et la responsabilité de ce solde sont deux sujets distincts. Une politique de risque vendeur fixe les plafonds, les délais éventuels, les alertes, les règles de récupération contractuelles et les interventions manuelles. Le webhook transporte l’événement. Il ne finance pas la perte.

Ledger, réconciliation et webhooks forment un seul système

Stripe décrit les mouvements de son infrastructure. Le ledger interne explique la commande. Il relie au minimum les lignes vendeur, le paiement, la charge, la commission, les transferts, les reversals, les remboursements, les litiges, les BalanceTransactions et les payouts.

Les écritures doivent être immuables, en unités monétaires mineures et reliées à une opération métier. Une correction ajoute une écriture, elle ne remplace pas un solde en base. Une architecture en partie double facilite l’explication d’un écart et empêche une somme de disparaître derrière une mise à jour.

La réconciliation rapproche chaque jour :

• les commandes payées avec les PaymentIntents et Charges ;
• les parts vendeurs attendues avec les Transfers et TransferReversals ;
• les remboursements, litiges et application fees avec les écritures internes ;
• les BalanceTransactions avec le solde calculé ;
• les payouts avec les lots d’écritures vendeurs ;
• les événements en retard ou en erreur avec la file de traitement.

Les webhooks alimentent ce système. La réponse synchrone du checkout ne suffit pas, car certains moyens de paiement sont asynchrones et Stripe réessaie les livraisons. Le point d’entrée vérifie la signature sur le corps brut, impose l’unicité de l’identifiant d’événement, stocke le message puis répond rapidement en 2xx. Un worker applique ensuite une transition idempotente.

Chaque requête POST vers Stripe reçoit une clé d’idempotence liée à l’opération métier. La même clé sert aux nouvelles tentatives de cette opération. Le traitement ne suppose jamais l’ordre des événements et relit l’objet courant en cas d’ambiguïté. Une intégration Accounts v2 doit aussi accepter la coexistence d’événements v2 pour les exigences de compte et d’événements v1 pour certains domaines, dont les payouts. Les bonnes pratiques Stripe pour les webhooks servent de base au plan de reprise.

Le back-office rend ces états lisibles sans ouvrir plusieurs exports Stripe. Un opérateur doit pouvoir expliquer un remboursement, reprendre un événement, voir une capacité restreinte et savoir si une action exige une seconde validation.

Fiscalité et exploitation restent à la charge du produit

Stripe peut collecter des informations KYC, vérifier des comptes et fournir des outils fiscaux. La plateforme garde ses obligations contractuelles, fiscales, de support et de risque. Stripe Tax calcule et collecte des taxes selon une configuration. Il ne détermine pas quelle entité est redevable.

Un fiscaliste doit valider la TVA, la facturation, le lieu de taxation, DAC7 et les obligations liées aux vendeurs. Un juriste doit valider l’encaissement pour compte de tiers, les conditions de transfert et toute promesse de conservation de fonds. Le lancement dans plusieurs pays ajoute les devises, les moyens de paiement, la disponibilité de Connect et les transferts transfrontaliers à cette revue.

Le produit tranche aussi des questions moins visibles : qui émet la facture au client, qui facture la commission au vendeur, qui répond au litige, que deviennent les commandes d’un vendeur restreint et quels droits possède le support. Les mises à jour de compte bancaire, les payouts échoués et les exigences KYC dépassées demandent des parcours de remédiation. Un Dashboard absent reporte toute cette charge sur la marketplace.

Une plateforme de location sur mesure avec Stripe illustre la place du paiement dans un parcours transactionnel. Cette référence ne prouve ni l’usage de Connect ni un flux multi-vendeurs. Le même niveau de prudence s’applique aux références techniques : une intégration de paiement ne suffit pas à déduire son charge pattern.

Checklist pour créer une marketplace avant le développement

Cette checklist transforme le paiement marketplace en décisions vérifiables :

• Classer chaque flux comme marketplace ou SaaS platform.
• Nommer le merchant of record pour chaque transaction.
• Lister les pays de la plateforme, des vendeurs et des acheteurs.
• Indiquer si un paiement rémunère un ou plusieurs vendeurs.
• Définir l’étape métier qui autorise le transfert.
• Choisir l’accès vendeur au Dashboard : Express, complet ou aucun.
• Attribuer la collecte des frais et la responsabilité des soldes négatifs.
• Demander les configurations et capacités Accounts v2 minimales.
• Choisir l’onboarding et écrire le parcours de remédiation KYC.
• Formaliser la commission, son assiette, sa fiscalité et les arrondis.
• Écrire les règles de remboursement, litige et transfer reversal.
• Fixer la politique de risque et les pouvoirs d’intervention.
• Concevoir le ledger, les rapports et la réconciliation quotidienne.
• Définir les webhooks, les clés d’idempotence et le mécanisme de reprise.
• Documenter le support, les permissions et les actions à double validation.

Créer une marketplace sur mesure devient chiffrable quand ces réponses existent. Sans elles, le budget mélange des inconnues produit, juridiques et opérationnelles. Avec elles, le développement d’applications web sur mesure peut partir d’un flux financier testable, avec des états explicables par le support et réconciliables par la finance.

La version d’API et la disponibilité exacte des configurations Accounts v2 doivent être revérifiées dans le Dashboard avant l’implémentation. Plusieurs exemples de la documentation Accounts v2 utilisent encore une version d’API preview. Ce contrôle évite de transformer un schéma éditorial en configuration copiée sans validation.