Stripe Connect pour une marketplace : ce qu’il faut savoir avant de coder

Une marketplace n'est pas un site e-commerce avec plusieurs vendeurs. Le cœur du problème, c'est le paiement à plusieurs : encaisser un acheteur, prélever une commission, reverser le reste au vendeur, le tout en restant conforme. Stripe Connect est conçu pour ça.

Ce que Stripe Connect gère pour vous

Connect ajoute à Stripe la notion de comptes vendeurs et de paiements partagés (split). Concrètement :

• Chaque vendeur a un compte connecté, onboardé et vérifié.
• À chaque transaction, la plateforme prélève sa commission et reverse le solde au bon vendeur.
• Les versements (payouts), les relevés et la gestion des litiges sont pris en charge.

Le choix structurant arrive tout de suite après, et il est difficile à revenir dessus : le type de compte connecté. La documentation Stripe sur les comptes Connect décrit des configurations qui répartissent différemment trois responsabilités, qui prend en charge l’inscription et la vérification du vendeur, qui gère les litiges et les impayés, et qui apparaît sur le relevé bancaire de l’acheteur. Plus la plateforme récupère le contrôle de l’expérience, plus elle récupère aussi la charge du support et le risque financier. Ce n’est donc pas un choix d’interface, c’est un choix de modèle : à trancher au cadrage, avec la personne qui devra répondre aux vendeurs mécontents.

C'est la base d'une marketplace qui tient la conformité dès le premier jour, plutôt que de bricoler des virements à la main.

Le sujet qui fait peur : KYC et conformité

Dès qu'on manipule l'argent d'autrui, on entre dans un cadre réglementé : vérification d'identité (KYC), lutte anti-blanchiment (AML), journaux d'audit. Stripe Identity couvre le KYC, et Connect intègre une partie de la conformité. Mais ça ne s'improvise pas : ça se conçoit dès le départ, pas après le premier contrôle.

Concrètement, ce cadre se traduit par une liste d’informations à collecter avant qu’un vendeur puisse être payé. Stripe documente ces exigences de vérification d’identité : identité et adresse du représentant légal, bénéficiaires effectifs pour une société, coordonnées bancaires, et pièces justificatives demandées au-delà de certains seuils d’encaissement. Deux conséquences pratiques trop souvent découvertes en production. D’abord, un compte peut basculer en « vérification requise » après plusieurs mois d’activité, quand un seuil est franchi : les versements sont alors suspendus tant que les documents ne sont pas fournis. Ensuite, votre interface doit exposer cet état au vendeur, sinon votre support récupère l’appel.

C'est précisément là que les marketplaces se plantent le plus souvent, et l'un des points qu'on remet à plat quand on reprend une marketplace bloquée.

Stripe ou MangoPay ?

Stripe n'est pas la seule option. MangoPay, acteur européen spécialisé marketplace, propose le cantonnement des fonds (wallets) et une approche réglementaire UE qui convient mieux à certains montages.

• Stripe Connect : meilleure expérience développeur et utilisateur, couverture internationale, écosystème complet (Billing, Identity). Notre choix par défaut.
• MangoPay : marketplace européenne, besoin de cantonnement des fonds, contraintes réglementaires UE spécifiques.

Le choix se fait au cadrage, sur votre géographie et votre modèle, jamais imposé d'office.

Le piège technique : les webhooks

En coulisses, tout repose sur les webhooks Stripe : c'est eux qui signalent qu'un paiement a réussi, échoué, ou qu'un litige est ouvert. Mal gérés, ils font perdre des paiements ou les comptent deux fois. On les traite de façon idempotente, avec relance et réconciliation, pour qu'aucune transaction ne passe à la trappe.

Trois règles rendent une intégration de webhooks fiable, et elles sont toutes documentées par Stripe. Vérifier la signature : chaque appel porte un en-tête Stripe-Signature à valider avec la clé secrète de l’endpoint et le corps brut de la requête, un framework qui reformate le corps fait échouer la vérification. Répondre vite : renvoyer un code 2xx avant toute logique lourde, puis traiter en tâche de fond; en production, Stripe réessaie pendant trois jours avec un recul exponentiel, ce qui transforme un traitement lent en avalanche de doublons. Ne rien supposer sur l’ordre : Stripe ne garantit pas la livraison des événements dans l’ordre de création, et un même événement peut arriver deux fois. D’où la troisième règle : déduplication sur l’identifiant d’événement et écritures idempotentes côté API. Une marketplace qui verse deux fois la même commission n’a pas un bug d’affichage, elle a un trou de trésorerie.

Avant de coder

Le modèle économique (commission ? abonnement ? les deux ?), la géographie, le niveau de conformité requis : tout ça se cadre avant la première ligne de code. C'est ce qu'on fait sur nos projets de marketplace sur-mesure, avec une intégration Stripe testée de bout en bout, détail sur notre page Agence Stripe.

Une idée de marketplace, ou une plateforme bloquée sur la conformité ? On en parle.