S'intégrer à Stripe et à son écosystème de partenaires

L'argent est la partie de votre produit que personne ne vous pardonne de rater. Une synchronisation qui perd un enregistrement est agaçante ; un paiement qui passe deux fois est un ticket de support, un remboursement, et une entaille dans la confiance. C'est pourquoi s'intégrer à une plateforme de paiement mérite plus de soin qu'une intégration ordinaire, et pourquoi il est utile de connaître les schémas avant d'écrire la première ligne. Stripe est l'une des plus grandes plateformes de paiement, et la question pour la plupart des équipes n'est pas de savoir s'il faut s'intégrer mais comment : directement dans votre propre produit, en tant qu'application listée que d'autres entreprises installent, ou quelque part dans l'écosystème de partenaires bâti autour.

Voici un manuel indépendant. PartnerMatch n'est pas affilié à Stripe, et rien ici n'est un document officiel de programme. Les fonctionnalités de la plateforme, les règles de la marketplace, les frais et les noms de programmes changent, alors traitez les spécificités comme des choses à confirmer dans la documentation officielle actuelle plutôt que comme des faits figés, et ne supposez rien sur la tarification que vous n'avez pas vérifié. Ce qui ne change pas beaucoup, c'est la forme du travail : choisir votre schéma d'intégration, le construire en toute sécurité, décider s'il faut lister une application, et comprendre l'écosystème de partenaires que vous rejoignez. C'est cette forme que couvre ce guide.

Il s'accompagne de notre guide de stratégie d'intégration SaaS, de nos parcours détaillés des écosystèmes Shopify et HubSpot, et de notre découpage natif vs iPaaS vs embarqué, pour que vous puissiez situer une intégration de paiement dans le contexte de votre roadmap d'intégration plus large.

L'essentiel en 60 secondes

• Choisissez le schéma selon la tâche. Facturer vos propres clients, activer les paiements pour vos utilisateurs, ou construire un outil que d'autres installent sont trois intégrations différentes avec des travaux différents.
• Construisez les paiements de façon défensive. L'idempotence, les webhooks et la réconciliation ne sont pas des extras optionnels. Ce sont eux qui empêchent un paiement de passer deux fois ou de disparaître.
• Les webhooks sont la source de vérité pour l'état. Ne supposez pas qu'un paiement a réussi parce qu'une requête a renvoyé. Écoutez l'événement et vérifiez sa signature.
• Décidez direct ou listé délibérément. Une intégration directe sert votre produit. Une application de marketplace sert d'autres entreprises et est un produit séparé avec son propre entretien.
• L'App Marketplace est un canal de distribution. Elle place un outil devant des entreprises qui utilisent déjà la plateforme, avec la même forme de fiche et de revue que toute marketplace.
• L'écosystème de partenaires est plus large que la marketplace. Les relations technologiques, de solution et d'apport d'affaires sont des démarches différentes avec des valeurs différentes.
• Confirmez les spécificités officiellement. Les fonctionnalités, règles de marketplace et frais changent, alors vérifiez par rapport à la documentation actuelle avant d'engager une roadmap ou de chiffrer un coût.

Étape 1 : choisir votre schéma d'intégration

La source la plus courante d'effort gâché est de construire le mauvais type d'intégration de paiement parce que l'équipe ne s'est pas arrêtée pour nommer celui dont elle avait besoin. Il y a trois grands schémas, et ce sont véritablement des produits différents. Décidez lequel correspond à votre situation avant de concevoir quoi que ce soit.

Facturer vos propres clients. Votre produit a un prix, et vous voulez l'encaisser. C'est le schéma le plus courant : abonnements, prélèvements ponctuels, factures pour vos propres clients. L'intégration vit dans votre facturation et sert votre entreprise, et l'essentiel du travail est de bien gérer le cycle de vie, inscriptions, montées en gamme, descentes en gamme, paiements échoués et annulations, sans perdre la trace de qui doit quoi.

Activer les paiements pour vos utilisateurs. Votre produit aide d'autres entreprises à se faire payer, donc vous devez déplacer de l'argent pour leur compte, souvent en le répartissant ou en l'acheminant vers leurs comptes. C'est un schéma plus lourd parce que vous faites désormais partie du flux d'argent de quelqu'un d'autre, avec des préoccupations d'onboarding, de conformité et de versements que le premier schéma ne touche jamais. Les plateformes exposent un outillage dédié pour cela, et la documentation officielle est l'endroit pour comprendre ce qu'il exige.

Construire un outil que d'autres installent. Votre produit fait quelque chose d'utile autour des données de paiement, reporting, réconciliation, analytique, opérations, et vous voulez le proposer à des entreprises qui utilisent déjà la plateforme. Ici, l'intégration est le produit, et vous décidez s'il faut le lister là où ces entreprises peuvent le trouver, ce qui est la question de la marketplace à l'étape 4.

Une façon rapide de vous situer :

Ceux-ci correspondent aux choix d'intégration plus larges de notre guide natif vs iPaaS vs embarqué. Nommer le schéma en premier signifie que le reste du développement a une cible claire au lieu de dériver entre trois tâches différentes.

Étape 2 : construire les paiements de façon défensive

Quel que soit le schéma choisi, une intégration de paiement porte un risque que les intégrations ordinaires n'ont pas : une erreur peut déplacer de l'argent dans le mauvais sens. Cela change la façon de construire. La posture par défaut est défensive : supposer que le réseau échouera en plein milieu d'une requête, que les requêtes seront relancées, et que les événements arriveront dans le désordre, car tout cela se produit et n'importe lequel peut prélever deux fois un client si vous n'êtes pas prêt.

Trois pratiques portent l'essentiel du poids :

Idempotence. Les appels réseau échouent et les clients relancent, donc une requête de prélèvement peut atteindre la plateforme plus d'une fois. Les clés d'idempotence permettent à la plateforme de reconnaître une relance comme la même opération plutôt qu'un nouveau prélèvement, de sorte qu'une requête relancée ne devienne pas un second paiement. Utilisez-les sur chaque opération qui crée ou modifie de l'argent. C'est l'habitude la plus importante d'une intégration de paiement, car sans elle une connexion instable devient un prélèvement en double.

Les webhooks comme source de vérité. Ne traitez pas une requête qui a renvoyé avec succès comme la preuve qu'un paiement est définitif. L'état d'un paiement peut changer après l'appel initial, et la plateforme vous le dit via des événements de webhook. Écoutez ces événements, vérifiez la signature sur chacun pour savoir qu'il vient réellement de la plateforme, et mettez à jour vos enregistrements à partir de l'événement plutôt que d'hypothèses optimistes dans votre propre code.

Réconciliation. Même avec l'idempotence et les webhooks, vos enregistrements et ceux de la plateforme peuvent diverger, à cause d'un événement manqué, d'un bug ou d'un changement manuel. Réconciliez régulièrement : comparez ce que votre système pense qu'il s'est passé à ce que la plateforme a enregistré, et faites ressortir les différences. Attraper un écart dans un contrôle quotidien est une routine ; le découvrir parce qu'un client s'est plaint est un incendie.

La discipline des webhooks ici est la même que celle que nous couvrons dans webhooks vs polling et gérer les webhooks de façon fiable : livraison au moins une fois, vérification de signature, et gestion idempotente pour qu'un événement rejoué ne provoque pas un second effet. Les paiements sont l'endroit où cette discipline cesse d'être une bonne pratique et devient ce qui se dresse entre vous et une file de remboursements.

Étape 3 : décider direct ou listé

Si votre situation est le troisième schéma, construire un outil que d'autres utilisent, vous faites face à une bifurcation qui façonne tout ce qui suit : une intégration directe ou une application listée. Elles se ressemblent et ce sont des produits différents avec des économies différentes.

Une intégration directe relie la plateforme à votre propre produit pour vos propres clients. Vous la construisez, vous la possédez, et elle sert les utilisateurs que vous avez déjà. L'audience est votre base de clients, et le succès, ce sont vos clients qui utilisent une fonctionnalité que vous avez livrée. Une application listée, en revanche, est un produit que vous proposez à d'autres entreprises sur la plateforme, distribué via la marketplace, installé par des gens qui ne sont pas encore vos clients. L'audience est la base d'utilisateurs de la plateforme, et le succès, ce sont des inconnus qui trouvent, installent et gardent votre application.

La décision se résume à savoir pour qui vous construisez :

Beaucoup d'équipes devraient construire une intégration directe et s'arrêter là, car une application listée est un produit séparé avec sa propre roadmap, son support et ses obligations de revue. Ne listez que lorsqu'il y a une demande authentique de la base d'utilisateurs plus large de la plateforme et que vous êtes prêt à traiter l'application comme un produit, pas un projet annexe. Nous travaillons cette décision construire-ou-distribuer dans construire, acheter ou s'associer et notre guide de stratégie de marketplace.

Étape 4 : lister sur l'App Marketplace

Si vous avez décidé de lister, la Stripe App Marketplace est le canal de distribution, et elle suit la même forme que toute marketplace sérieuse : construire sur le modèle de la plateforme, demander l'accès dont vos fonctionnalités ont besoin, passer une revue, écrire une fiche qui convertit, et générer des installations après le lancement. Si vous avez lu nos manuels Shopify ou HubSpot, le schéma vous semblera familier, car c'est le cas.

Les parties qui se transposent directement :

• Construire sur le modèle de la plateforme. Utilisez les API documentées, authentifiez-vous de façon standard, et ne demandez que l'accès que vos fonctionnalités utilisent réellement. Le moindre privilège est plus facile à approuver et plus facile à faire confiance pour l'entreprise qui installe.
• Traiter la revue comme des critères d'acceptation. Lisez les exigences actuelles avant de concevoir et construisez en fonction d'elles, pour que la revue confirme ce que vous avez déjà fait au lieu de faire surgir une reprise tardive. C'est la même logique que la certification d'application sans douleur.
• Écrire une fiche qui convertit. Mettez en avant le flux de travail et le résultat dans le langage de l'acheteur, montrez l'application faire son travail, et rendez la tarification et le support clairs. Nous couvrons cela dans comment les marketplaces classent les applications.
• Générer des installations après le lancement. Une nouvelle fiche est une tuile parmi tant d'autres. Semez des installations auprès des clients existants, recueillez des avis, et instrumentez l'activation, car la fiche est le début du travail, pas sa fin.

Ce qui est propre à une marketplace de paiement, c'est le sujet. Les entreprises qui parcourent font passer de l'argent réel par la plateforme, donc elles sont prudentes sur ce qu'elles installent à proximité. Un outil qui touche aux données de paiement doit être clair sur exactement ce à quoi il accède et pourquoi, et la barre de confiance est plus haute que pour une marketplace où les enjeux sont moindres. Mettez cette clarté en avant plutôt que de la cacher. Les règles exactes de la marketplace, les critères de revue et tous frais sont à la plateforme de les définir et ils changent, alors confirmez-les dans la documentation officielle actuelle et ne supposez jamais un coût que vous n'avez pas vérifié.

Étape 5 : comprendre l'écosystème de partenaires

Une fiche sur la marketplace est une façon de s'associer à une plateforme, et ce n'est pas la seule. Les plateformes de paiement ont tendance à se situer au centre d'un large écosystème, et les relations qui s'y trouvent sont des démarches différentes avec des valeurs différentes. Savoir laquelle convient vous évite de courir après le mauvais type de partenariat.

Les types de relation courants, en termes simples :

Ceux-ci ne sont pas exclusifs. Une entreprise peut être partenaire technologique avec une application listée et avoir une relation d'apport d'affaires en même temps. Le point est d'être délibéré : une relation d'apport d'affaires est une démarche de mise sur le marché, un partenariat technologique est un engagement d'intégration, et un partenariat de solution est une activité de services. Les traiter comme la même chose conduit à des versions à moitié construites des trois. Notre guide des partenariats technologiques pour le SaaS couvre le volet intégration, et apport d'affaires, revente et vente conjointe couvre les démarches de mise sur le marché, pour que vous puissiez choisir la relation qui correspond à ce que vous voulez réellement.

La leçon plus large, c'est que « s'associer à une plateforme de paiement » n'est pas une seule chose. Décidez si vous voulez une intégration, de la distribution, du revenu de services, ou un flux d'apport d'affaires, car chacun est un engagement différent, et l'écosystème récompense les équipes qui en choisissent un et le font bien plutôt que celles qui touchent à tout.

Erreurs fréquentes, et comment les corriger

Construire le mauvais schéma. La correction : nommez lequel des trois schémas vous voulez, facturer vos clients, activer les paiements pour vos utilisateurs, ou construire un outil installable, avant de concevoir quoi que ce soit. Les schémas sont des produits différents, et construire vers une cible floue gâche le plus de temps.

Sauter l'idempotence. La correction : utilisez des clés d'idempotence sur chaque opération qui modifie de l'argent. Une requête relancée sans elles devient un prélèvement en double, et un réseau instable se transforme en file de remboursements et en confiance perdue.

Faire confiance à la réponse plutôt qu'au webhook. La correction : traitez les événements de webhook vérifiés comme la source de vérité pour l'état du paiement, et mettez à jour vos enregistrements à partir d'eux. Une requête qui a renvoyé n'est pas la preuve qu'un paiement est définitif, et l'état peut changer après l'appel.

Lister une application alors qu'une intégration directe suffisait. La correction : construisez en direct pour vos propres clients et ne listez que lorsqu'il y a une vraie demande de la base d'utilisateurs plus large de la plateforme et que vous êtes prêt à traiter l'application comme un produit. Une application listée est un produit séparé avec sa propre revue, son support et sa roadmap.

Confondre les types de partenariat. La correction : décidez si vous voulez une intégration technologique, de la distribution sur marketplace, du revenu de services, ou un flux d'apport d'affaires, et poursuivez celui qui convient. Ce sont des démarches différentes, et en construire trois à moitié rapporte moins qu'en faire une bien.

FAQ

Est-ce un guide officiel de Stripe ? Non. PartnerMatch est indépendant et non affilié à Stripe, et ceci n'est pas un document officiel de programme. Utilisez-le pour comprendre la forme du travail, et confirmez les fonctionnalités, règles de marketplace et tous frais exacts dans la documentation officielle actuelle, qui peut changer sans préavis. Ne vous fiez à aucun chiffre de coût que vous n'y avez pas vérifié.

De quel schéma d'intégration ai-je besoin ? Cela dépend de ce que vous faites avec l'argent. Si vous encaissez le paiement de votre propre produit, vous facturez vos clients. Si vous déplacez de l'argent pour le compte des entreprises que vous servez, vous activez les paiements pour vos utilisateurs, ce qui est plus lourd. Si vous proposez un outil à des entreprises qui utilisent déjà la plateforme, vous construisez une application installable. Nommez le schéma en premier, car chacun est un développement différent.

Pourquoi l'idempotence et les webhooks sont-ils si importants ? Parce que les paiements sont impitoyables face aux erreurs. Les réseaux échouent et les clients relancent, donc sans clés d'idempotence une requête relancée peut devenir un second prélèvement. Et l'état d'un paiement peut changer après votre appel initial, donc sans écouter les événements de webhook vérifiés vous pouvez enregistrer un paiement comme définitif alors qu'il ne l'était pas. Ensemble, ils empêchent un paiement de passer deux fois ou de disparaître.

Dois-je construire une intégration directe ou lister une application ? Construisez en direct quand l'audience est vos propres clients et que le succès, c'est qu'ils utilisent une fonctionnalité que vous avez livrée. Listez une application quand il y a une demande authentique de la base d'utilisateurs plus large de la plateforme, que vous voulez que des inconnus la trouvent et l'installent, et que vous êtes prêt à traiter l'application comme un produit avec sa propre revue et son support. Beaucoup d'équipes devraient construire en direct et s'arrêter là.

Quelle est la différence entre la marketplace et l'écosystème de partenaires ? La marketplace est un canal : un endroit pour lister une application installable afin que les utilisateurs de la plateforme puissent la trouver. L'écosystème de partenaires est plus large et inclut les partenariats technologiques (intégrer votre produit), les partenariats de solution (des services pour aider les entreprises à adopter la plateforme), et les relations d'apport d'affaires (s'envoyer mutuellement des affaires). Une fiche est une option parmi plusieurs, et ce sont des démarches différentes avec des valeurs différentes.

En quoi s'intégrer à une plateforme de paiement diffère-t-il des autres intégrations ? Le sujet, c'est l'argent, ce qui relève les enjeux d'exactitude et de confiance. Les intégrations ordinaires peuvent tolérer une relance occasionnelle ou une synchronisation retardée ; une intégration de paiement ne peut tolérer ni un prélèvement en double ni un paiement perdu. C'est pourquoi l'idempotence, l'état piloté par webhook et la réconciliation passent d'appréciables à requises, et pourquoi les entreprises sont plus prudentes sur ce qu'elles installent à proximité de leur flux de paiement.

Pour aller plus loin

• Documentation Stripe pour comprendre les API actuelles, les schémas d'intégration, et ce que chacun exige.
• Documentation Stripe Connect pour l'outillage impliqué quand vous déplacez de l'argent pour le compte des entreprises que vous servez.
• Stripe App Marketplace pour voir comment les applications listées sont présentées aux entreprises qui choisissent quoi installer.
• OWASP pour les classes courantes de vulnérabilités web et d'API contre lesquelles toute intégration touchant à des données sensibles devrait être testée.

La version courte

S'intégrer à Stripe commence par nommer le schéma dont vous avez besoin : facturer vos propres clients, activer les paiements pour les entreprises que vous servez, ou construire un outil que d'autres installent, car ce sont des produits différents. Quel que soit le schéma, construisez de façon défensive, car l'argent est impitoyable : utilisez des clés d'idempotence sur chaque opération qui modifie de l'argent, traitez les événements de webhook vérifiés comme la source de vérité pour l'état du paiement, et réconciliez vos enregistrements avec ceux de la plateforme selon un calendrier. Si vous construisez un outil pour d'autres, décidez direct ou listé délibérément, car une application de marketplace est un produit séparé avec sa propre revue, son support et sa roadmap, et ne listez que lorsqu'il y a une vraie demande et que vous y êtes prêt. L'App Marketplace suit la même forme que toute marketplace, avec une barre de confiance plus haute parce qu'elle se situe près de l'argent. Et l'écosystème de partenaires est plus large que la marketplace, avec des relations technologiques, de solution et d'apport d'affaires qui sont des démarches différentes, alors choisissez celle qui correspond à ce que vous voulez. Parce que les spécificités et tous frais changent, confirmez-les dans la documentation officielle actuelle, puisque ceci est un manuel indépendant, pas un manuel officiel.

Si vous voulez de l'aide pour choisir votre schéma d'intégration, décider s'il faut lister, ou choisir la bonne démarche de partenariat, un Partner Audit passe en revue votre produit, votre surface d'intégration et vos options d'écosystème, puis vous remet un plan concret de ce qu'il faut construire et des relations à poursuivre.