# Présentation de l'API Découvrez comment les objets de l'API Stripe fonctionnent ensemble et apprenez les bonnes pratiques pour les associer. Si votre plateforme Connect utilise des [comptes configurés par le client](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), consultez notre [guide](https://docs.stripe.com/connect/use-accounts-as-customers.md) pour remplacer dans votre code les références `Customer` et événements par les références équivalentes de l’API Comptes v2. 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 Dans votre compte Stripe, tout est un objet, que vous le créiez via l’API ou non. Votre solde correspond à un objet [Balance](https://docs.stripe.com/api/balance.md), le suivi des paiements récurrents des clients s’effectue via des objets [Abonnement](https://docs.stripe.com/api/subscriptions.md), les informations de paiement sont stockées dans des objets [PaymentMethod](https://docs.stripe.com/api/payment_methods.md), etc. Même les intégrations low-code ou no-code génèrent ces objets. C’est aussi le cas des actions effectuées dans le Dashboard. Par exemple, lorsque vous créez manuellement un produit dans le Dashboard, cela génère un objet [Product](https://docs.stripe.com/api/products.md). ### 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_payment_method` 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 repose toujours sur les mêmes objets et les mêmes étapes, avec des objets supplémentaires ajoutés autour de cette logique centrale. ## Objets de paiement 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. [Watch on YouTube](https://www.youtube.com/watch?v=CUAY6IQcVQM) Pour en savoir plus sur les options d’intégration des paiements de Stripe, consultez les guides suivants : - [Payment Links](https://docs.stripe.com/payment-links.md) - [Checkout](https://docs.stripe.com/payments/checkout.md) - [Abonnements](https://docs.stripe.com/billing.md) - [Facturation](https://docs.stripe.com/invoicing.md) - [Payment Intents](https://docs.stripe.com/payments/payment-intents.md) ## Le parcours d’un paiement Dans une intégration Stripe moderne, chaque paiement utilise un objet appelé [PaymentIntent](https://docs.stripe.com/api/payment_intents.md), 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](https://docs.stripe.com/payments/paymentintents/lifecycle.md), dont voici une version simplifiée : Indique l'état d'un PaymentIntent qui passe de requires_payment_method à requires_confirmation, puis à processing avant de finalement prendre l'état succeeded ou canceled (See full diagram at https://docs.stripe.com/payments-api/tour) ### Moyens de paiement Au début du processus, l’état du PaymentIntent est `requires_payment_method`. 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](https://docs.stripe.com/api/payment_methods.md). 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](https://docs.stripe.com/payments/setup-intents.md). ### Confirmation L’état suivant est : `requires_confirmation`. 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](https://docs.stripe.com/payments/elements.md) 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](https://docs.stripe.com/payments/checkout.md) ou [Payment Links](https://docs.stripe.com/payment-links.md), 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.](https://docs.stripe.com/payments/online-payments.md) Dans la plupart des cas, un [Paiement](https://docs.stripe.com/api/charges.md) 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](https://docs.stripe.com/payments/cards/overview.md).) 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_payment_method` en cas d’échec du paiement. Une fois ce processus terminé, un dernier objet entre en jeu : l’objet [Event](https://docs.stripe.com/api/events.md). 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 d’[endpoints de webhook](https://docs.stripe.com/webhooks.md). Dans d’autres intégrations, par exemple celles utilisant [Checkout](https://docs.stripe.com/payments/checkout.md) ou [Payment Links](https://docs.stripe.com/payment-links.md), Stripe écoute ces événements et fournit une réponse préprogrammée.