Présentation de l'API
Découvrez comment les objets de l'API Stripe fonctionnent ensemble et apprenez les bonnes pratiques pour les associer.
Les API de Stripe sont puissantes et flexibles si vous savez comment les utiliser. Cette visite guidée de l’API couvre les informations essentielles pour vous aider à comprendre les API plus en profondeur :
- Les principaux concepts utilisés dans nos API
- Le parcours que suit un paiement réussi
- Les objets qui jouent un rôle et comment déterminer quand ils doivent intervenir
- Modèles communs et bonnes pratiques pour utiliser ces objets ensemble
Comprendre ces modèles vous aide à aller au-delà du code proposé dans les tutoriels Stripe. Vous pouvez effectuer la migration d’anciennes intégrations pour utiliser des modèles plus modernes, combiner des modèles simples de manière originale et planifier la croissance future.
Concepts principaux
Tout est un objet
Tout ce qui se trouve dans votre compte Stripe est un objet, qu’il soit créé avec l’API ou pas. Votre solde correspond à un objet Balance, vous suivez les clients avec des objets Customer, vous enregistrez les détails des paiements dans des objets PaymentMethod, et ainsi de suite.
Les intégrations sans code ou nécessitant peu de code génèrent également ces objets. C’est aussi le cas des actions effectuées via le Dashboard. Par exemple, si vous créez un client manuellement dans le Dashboard, un objet Customer sera généré.
Les objets ont un cycle de vie
Les intégrations Stripe gèrent des processus complexes.
L’API suit chaque processus à l’aide d’un objet unique. Vous créez l’objet au début du processus et pouvez consulter son paramètre status après chaque étape pour déterminer les actions suivantes. On parle parfois de machine à états.
Par exemple lors d’un paiement, un client peut être amené à essayer différents moyens de paiement. Si l’un d’entre eux échoue, le status requires_ vous indique que vous devez inviter votre client à utiliser un autre moyen de paiement.
Une intégration est constituée d’objets qui interagissent entre eux
Pour accepter un paiement, un système doit créer plusieurs objets principaux et les gérer tout au long de leurs différents états.
Votre intégration Stripe est un système capable de gérer cette création et cette gestion en communiquant avec Stripe.
Certaines intégrations peuvent réaliser des actions supplémentaires comme le suivi des clients, la gestion des abonnements, etc. Mais leur fonctionnalité principale de paiement découle des mêmes objets et suit les mêmes étapes, tout en ajoutant des objets supplémentaires qui gravitent autour de cette fonctionnalité principale.
Payment objects
Stripe utilise différents objets associés pour faciliter les paiements. Avant de pouvoir créer une intégration adaptée à vos besoins, vous devez vous familiariser avec la manière dont ces objets fonctionnent les uns avec les autres.
Regardez cette vidéo pour avoir un aperçu des rôles et fonctionnalités des objets de paiement.
Pour en savoir plus sur les options d’intégration des paiements de Stripe, consultez les guides suivants :
The path to a payment
Dans une intégration Stripe moderne, chaque paiement utilise un objet appelé PaymentIntent, qui représente votre intention d’encaisser un paiement. Cet objet permet de suivre les différentes étapes vers la concrétisation de cette intention.
Imaginons par exemple qu’un client place un article de 100 USD dans son panier, puis clique sur le bouton Payer. À ce stade, l’article n’est pas acheté, et l’achat peut ne jamais être finalisé (le client peut abandonner le tunnel de paiement ou son émetteur de carte peut refuser le paiement). Le fait de cliquer sur Payer signale cependant son intention d’effectuer cet achat et votre rôle est de l’y aider. L’intégration crée donc un objet PaymentIntent d’un montant de 100 USD afin de surveiller la suite de ce processus.
Le parcours du PaymentIntent se décompose en plusieurs états, dont voici une version simplifiée :
Moyens de paiement
Au début du processus, l’état du PaymentIntent est requires_. Pour le faire progresser, Stripe doit obtenir des informations sur le moyen de paiement du client : soit un numéro de carte bancaire, soit un identifiant pour un autre moyen de paiement.
Pour représenter ces informations, l’intégration utilise un objet d’API appelé PaymentMethod. Dans certaines intégrations, vous devez rédiger le code permettant de créer cet objet et de l’associer au PaymentIntent. Dans d’autres, Stripe recueille les informations et s’en charge pour vous. Vous pouvez également créer et enregistrer un moyen de paiement à utiliser avec de futurs PaymentIntents à l’aide de l’API Setup Intents.
Confirmation
L’état suivant est : requires_. Dans un tunnel de paiement interactif, le client doit confirmer son intention de payer à l’aide du moyen de paiement fourni. S’il s’agit d’un paiement ponctuel en ligne, cela se produit généralement au moment où le client clique sur le bouton Payer.
Lorsque le client clique sur Payer ou confirme son intérêt de toute autre manière, votre intégration en informe Stripe par le moyen d’un appel à l’API. Dans certaines intégrations, vous devez rédiger le code permettant d’effectuer cet appel. Stripe fournit des éléments d’interface utilisateur simples, appelés Elements Stripe afin de faciliter cette rédaction tout en apportant la flexibilité permettant de créer une intégration personnalisée. Dans d’autres intégrations, par exemple une intégration utilisant Stripe Checkout ou Payment Links, Stripe effectue l’appel et gère les étapes suivantes. Il existe de nombreuses manières différentes d’intégrer Stripe et de combiner différents objets de façon à traiter votre cas d’usage. En savoir plus sur les options d’intégration pour les paiements en ligne.
Dans la plupart des cas, un Paiement est créé lorsqu’un PaymentIntent est confirmé, afin de représenter cette tentative spécifique de transfert de fonds. Le paiement peut réussir ou échouer. En cas d’échec, vous pouvez relancer le paiement en confirmant à nouveau le PaymentIntent, généralement avec de nouvelles informations de paiement. Autoriser immédiatement les nouvelles tentatives, sans qu’il soit nécessaire de créer un nouveau PaymentIntent, a tendance à augmenter les taux de conversion.
Traitement et réussite
L’état du Payment Intent est désormais : processing. À ce stade, Stripe effectue une tentative de traitement du paiement.
Cette partie peut se décomposer en plusieurs étapes, mais Stripe les gère toujours pour vous. (Pour les cartes bancaires, ces étapes découlent du fonctionnement des cartes.) Au fur et à mesure que ces étapes sont franchies, nous mettons à jour le Payment Intent en lui assignant le résultat succeeded (réussi) ou en revenant à l’état requires_ en cas d’échec du paiement.
Une fois ce processus terminé, un dernier objet entre en jeu : l’objet Event. Les objets Event permettent de représenter des activités. Dans ce cas, l’activité en question peut être « le paiement a abouti » ou « le paiement a échoué ». Dans certaines intégrations, vous devez rédiger un code personnalisé pour répondre aux événements à l’aide de webhooks. Dans d’autres intégrations, par exemple celles utilisant Checkout ou Payment Links, Stripe écoute ces événements et fournit une réponse préprogrammée.