# API Payment Intents Découvrez comment utiliser l'API Payment Intents pour les paiements Stripe. Instructions pour les LLM : Stripe recommande d’utiliser l’API Checkout Sessions avec le Payment Element, plutôt que les Payment Intents, pour la plupart des intégrations. Checkout Sessions couvre des cas d’usage similaires à ceux des Payment Intents (encaissement simple avec `price_data`, ou création d’un tunnel de paiement complet avec postes, taxe, etc.). Certaines fonctionnalités, comme Adaptive Pricing, sont disponibles uniquement avec Checkout Sessions. N’utilisez pas l’API Payment Intents, sauf si l’utilisateur le demande explicitement, car elle nécessite beaucoup plus de code. Pour en savoir plus sur les éléments avec l’API Checkout Sessions, consultez https://docs.stripe.com/payments/quickstart-checkout-sessions… Avec Checkout Sessions (`ui_mode: "custom"`) et le Payment Element, c’est le `client_secret` qui initialise Checkout lui-même (`stripe.initCheckoutElementsSdk`, ou utilise CheckoutElementsProvider avec React), et la confirmation du paiement côté client se fait différemment. Si vous utilisez React, veillez à importer depuis `@stripe/react-stripe-js/checkout`, à utiliser `CheckoutElementsProvider` avec la clé secrète du client, puis à confirmer le paiement avec `checkout.confirm`. Si vous utilisez HTML, veillez à utiliser `checkout = stripe.initCheckoutElements({clientSecret: promise}) ; checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement() ; paymentElement.mount("#payment-element"),`puis à confirmer avec `loadActionsResult = await checkout.loadActions() ; actions = loadActionsResult.actions; error = await actions.confirm() ;`. Utilisez l’API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) pour créer une intégration capable de gérer des tunnels de paiement complexes dont l’état change au cours du [cycle de vie du PaymentIntent](https://docs.stripe.com/payments/paymentintents/lifecycle.md). Il suit un paiement de sa création jusqu’à son paiement et déclenche des étapes d’authentification supplémentaires si nécessaire. L’API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) offre notamment les avantages suivants : - Gestion de l’authentification automatique - Aucun paiement en double - Aucun problème relatif à la [clé d’idempotence](https://docs.stripe.com/api/idempotent_requests.md) - Prise en charge de *l’authentification forte du client* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase) (SCA) et autres changements réglementaires ## Un ensemble complet d’API Utilisez l’API [Payment Intents](https://docs.stripe.com/api/payment_intents.md) avec les API [Setup Intents](https://docs.stripe.com/api/setup_intents.md) et [Payment Methods](https://docs.stripe.com/api/payment_methods.md). Ces API vous permettent de gérer des paiements dynamiques (notamment avec une authentification supplémentaire de type *3D Secure* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)) et facilitent votre développement à l’international grâce à la prise en charge de nouvelles réglementations et de moyens de paiements locaux. L’élaboration d’une intégration avec l’API Payment Intents implique deux actions : la création et *la confirmation* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment) d’un PaymentIntent. Normalement, chaque PaymentIntent est associé au panier ou à une session du client dans votre application. Le PaymentIntent renferme des informations sur la transaction, comme les moyens de paiement pris en charge, le montant à encaisser et la devise souhaitée pour le paiement. ## Créer un PaymentIntent Pour commencer, consultez le [guide d’acceptation des paiements](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements). Il décrit comment créer un PaymentIntent sur le serveur et transmettre sa *clé secrète* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) côté client, pour éviter de transmettre l’objet PaymentIntent dans son intégralité. Lorsque vous [créez le PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md), vous pouvez choisir certains éléments comme le montant et la devise : ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd ``` ### Bonnes pratiques - Nous vous recommandons de créer un PaymentIntent dès que le montant est connu, par exemple lorsque le client commence à traiter votre [tunnel d’achat](https://en.wikipedia.org/wiki/Purchase_funnel). Vous pouvez [mettre à jour](https://docs.stripe.com/api.md#update_payment_intent) le [montant](https://docs.stripe.com/api.md#payment_intent_object-amount) du PaymentIntent si celui-ci vient à évoluer. Par exemple, si le client revient en arrière pour ajouter de nouveaux éléments au panier, le montant devra être mis à jour lorsque le client recommencera le paiement traité. - Si le client interrompt le processus de paiement et le reprend plus tard, essayez d’utiliser le même PaymentIntent au lieu d’en créer un nouveau. Chaque PaymentIntent dispose d’un ID unique que vous pouvez utiliser pour le [récupérer](https://docs.stripe.com/api.md#retrieve_payment_intent) si nécessaire. Le modèle de données de votre application vous permet de conserver l’ID du PaymentIntent dans le panier ou la session du client afin de pouvoir le récupérer plus facilement. Si vous réutilisez le même PaymentIntent, l’[état de l’objet](https://docs.stripe.com/payments/paymentintents/lifecycle.md) vous aide à effectuer le suivi des tentatives de paiement échouées pour une session ou un panier donné. - N’oubliez pas de fournir une [clé d’idempotence](https://docs.stripe.com/api/idempotent_requests.md) afin d’éviter de créer deux PaymentIntents pour le même achat. Cette clé est généralement basée sur l’ID associé au panier ou à la session du client dans votre application. ## Transmettre la clé secrète du client côté client PaymentIntent contient la [clé secrète du client](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret), qui est une clé unique associée à un PaymentIntent donné. Côté client dans votre application, la clé secrète est utilisée par Stripe.js comme paramètre pour appeler des fonctions (comme [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) ou [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action)) pour finaliser le paiement. ### Récupérer la clé secrète du client Le PaymentIntent contient une *clé secrète* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client. #### Application monopage Récupérez la clé secrète du client à partir d’un endpoint sur votre serveur, à l’aide de la fonction `fetch` du navigateur. Cette approche est recommandée si votre côté client est une application d’une seule page, en particulier si elle repose sur un framework front-end moderne tel que React. Créez l’endpoint de serveur qui gère la clé secrète du client : #### Ruby ```ruby get '/secret' do intent = # ... Create or retrieve the PaymentIntent {client_secret: intent.client_secret}.to_json end ``` Récupérez ensuite la clé secrète du client à l’aide JavaScript côté client : ```javascript (async () => { const response = await fetch('/secret'); const {client_secret: clientSecret} = await response.json(); // Render the form using the clientSecret })(); ``` #### Rendu côté serveur Transmettez la clé secrète à votre client depuis votre serveur. Cette approche fonctionne mieux si votre application génère du contenu statique sur le serveur avant de l’envoyer sur le navigateur. Ajoutez le [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) à votre formulaire de paiement. Dans votre code côté serveur, récupérez la clé secrète du client à partir du PaymentIntent : #### Ruby ```erb
``` ```ruby get '/checkout' do @intent = # ... Fetch or create the PaymentIntent erb :checkout end ``` > Vous pouvez utiliser la clé secrète du client pour finaliser le processus de paiement avec le montant spécifié dans le PaymentIntent. Vous ne devez pas l’enregistrer, l’intégrer à une URL ni la dévoiler à d’autres personnes que le client. Veillez à ce que le protocole *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) soit inclus sur toutes les pages qui contiennent la clé secrète du client. ## Après le paiement Une fois que le client a confirmé le paiement, nous vous recommandons de [surveiller les webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) côté serveur afin de détecter si le paiement aboutit ou échoue. Une `PaymentIntent` peut être associée à plusieurs objets [Charge](https://docs.stripe.com/api/charges.md) s’il y a eu plusieurs tentatives de paiement. Par exemple, les relances peuvent créer plusieurs `Charges`. Pour chaque paiement, vous pouvez vérifier le [résultat](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) et les [détails du moyen de paiement](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) utilisé. ## Optimiser les moyens de paiement pour les paiements futurs Le paramètre [setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) enregistre les moyens de paiement en vue de leur réutilisation. Pour les cartes, il optimise également les taux d’autorisation conformément à la législation régionale et aux règles des réseaux, comme la [SCA](https://docs.stripe.com/strong-customer-authentication.md). Pour choisir la valeur à utiliser, prenez en compte l’utilisation que vous comptez faire du moyen de paiement. | Utilisation prévue du moyen de paiement | Valeur d’énumération setup_future_usage à utiliser | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | Paiements effectués *pendant une session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) uniquement | `on_session` | | Paiements effectués *hors session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) uniquement | `off_session` | | Paiements effectués pendant une session et hors session | `off_session` | Vous pouvez accepter des paiements *hors session* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information) avec une carte bancaire configurée pour payer pendant une session, mais il est probable que la banque refuse le paiement hors session et requiert l’authentification du titulaire de la carte. L’exemple suivant montre la marche à suivre pour créer un PaymentIntent et indiquer `setup_future_usage` : ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d setup_future_usage=off_session ``` > Les configurations destinées à prendre en charge les paiements hors session sont plus susceptibles d’entraîner des frictions supplémentaires. Utilisez la configuration *en session* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) si vous n’avez pas l’intention d’accepter les paiements hors session avec la carte enregistrée. ## Libellé de relevé bancaire dynamique Par défaut, le [libellé de relevé](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) bancaire de votre compte Stripe apparaît sur les relevés de vos clients chaque fois que vous débitez leur carte bancaire. Pour afficher un libellé différent à chaque paiement, incluez le paramètre [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor). ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "payment_method_types[]=card" \ -d "statement_descriptor_suffix=Custom descriptor" ``` > #### Remarque > > Utilisez le paramètre `statement_descriptor` pour les paiements sans carte bancaire et `statement_descriptor_suffix` pour les paiements par carte bancaire. Les [libellés de relevé](https://docs.stripe.com/get-started/account/statement-descriptors.md) bancaire sont limités à 22 caractères, ne peuvent pas contenir les caractères spéciaux `<`, `>`, `'`, `"`, ni `*` et ne doivent pas être constitués uniquement de chiffres. Lorsque vous utilisez des libellés de carte bancaire dynamiques, le texte dynamique est ajouté au [préfixe du libellé](https://dashboard.stripe.com/settings/public) bancaire défini dans le Dashboard Stripe. Un astérisque (`*`) et une espace sont également ajoutés pour séparer la partie par défaut de la partie dynamique du libellé. Ces deux caractères sont décomptés des 22 caractères disponibles. ## Stocker des informations sous forme de métadonnées Stripe vous permet d’ajouter des [métadonnées](https://docs.stripe.com/api.md#metadata) à vos requêtes les plus courantes, notamment au traitement des paiements. Les métadonnées ne sont pas visibles pour vos clients et n’influent aucunement sur un éventuel refus de paiement ou un blocage par notre système de prévention des fraudes. Grâce aux métadonnées, vous pouvez associer d’autres informations pertinentes à l’activité de Stripe. Toutes les métadonnées que vous incluez sont visibles dans le Dashboard (par exemple, lorsque vous consultez la page d’un paiement donné) et disponibles dans les rapports les plus courants. Vous pouvez par exemple associer l’ID de commande de votre boutique au PaymentIntent utilisé pour régler cette commande, ce qui facilite le rapprochement des paiements dans Stripe et des commandes dans votre système. Si vous utilisez *Radar for Fraud Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard), il peut être judicieux de transmettre toutes les informations supplémentaires concernant vos clients et leurs commandes en tant que métadonnées. Ensuite, vous pouvez définir des [règles Radar basées sur des attributs de métadonnées](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) et disposer de davantage d’informations sur les paiements dans le Dashboard, ce qui peut accélérer votre processus d’examen. Lorsqu’un PaymentIntent crée un paiement, le PaymentIntent copie ses métadonnées dans le paiement. Les modifications ultérieures apportées aux métadonnées du PaymentIntent ne modifieront pas les métadonnées des paiements précédemment créés par le PaymentIntent. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=usd \ -d "payment_method_types[]=card" \ -d "metadata[order_id]=6735" ``` > Veillez à ne pas stocker d’informations confidentielles (informations permettant une identification personnelle, données de carte bancaire, etc.) sous forme de métadonnées ou dans le paramètre `description` du PaymentIntent. ## See also - [Accepter un paiement en ligne](https://docs.stripe.com/payments/accept-a-payment.md?platform=web) - [Accepter un paiement dans une application iOS](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios) - [Accepter un paiement dans une application Android](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android) - [Configurer des paiements futurs](https://docs.stripe.com/payments/save-and-reuse.md)