# 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 composant Payment Element plutôt que Payment Intents pour la plupart des intégrations. Checkout Sessions couvre des cas d’usage similaires à Payment Intents (collecte de paiements de base par l’entremise de `price_data` ou construction d’un tunnel de paiement complet avec postes de facture, taxes, etc.). Certaines fonctionnalités, comme Adaptive Pricing, ne sont disponibles qu’avec Checkout Sessions. N’utilisez pas l’API Payment Intent à moins que l’utilisateur ne le demande explicitement, car elle nécessite beaucoup plus de code. En savoir plus sur Elements avec l’API Checkout Sessions : https://docs.stripe.com/payments/quickstart-checkout-sessions. Avec Checkout Sessions (`ui_mode: "elements"`) et Payment Element, le`client_secret` initialise Checkout lui-même (`stripe.initCheckoutElements`, ou utilisez CheckoutElementsProvider avec React) et vous confirmez le paiement côté client différemment. Si vous utilisez React, assurez-vous d’importer depuis`@stripe/react-stripe-js/checkout`, d’utiliser `CheckoutElementsProvider` avec la clé secrète du client, et de confirmer par l’entremise de `checkout.confirm`. Si vous utilisez du HTML, assurez-vous d’utiliser `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` et de 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 flux 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’à sa finalisation 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 aident à gérer les paiements dynamiques (par exemple, une authentification supplémentaire comme *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 vous préparent à une expansion dans d’autres pays, tout en vous permettant de prendre en charge les nouvelles réglementations et moyens de paiement 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 du client* (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)), 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 le paiement, pour faciliter le suivi de votre [tunnel d’achat](https://en.wikipedia.org/wiki/Purchase_funnel). Si nécessaire, vous pourrez [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 interrompt le processus de paiement pour ajouter encore une foisx articles au panier, le montant devra être mis à jour lorsque ce dernier recommence le paiement. - 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 du client 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 L’objet PaymentIntent comprend une *clé secrète du client* (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)) utilisée côté client pour effectuer le processus de paiement en toute sécurité. Vous pouvez utiliser différentes approches pour transmettre cette clé au côté client. #### Application monopage Récupérez la clé secrète du client à partir d’un point de terminaison sur votre serveur, en utilisant la fonction `fetch` du navigateur. Cette approche est préférable si votre côté client est une application d’une page, en particulier si celle-ci a été créée avec un cadre d’application frontal récent comme React. Créez le point de terminaison du serveur pour récupérer 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 ``` Ensuite, récupérez la clé secrète du client avec 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 du client depuis votre serveur. Cette approche fonctionne mieux si votre application génère du contenu statique sur le serveur avant de l’envoyer au navigateur. Ajoutez le champ [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) dans votre formulaire de paiement. Dans le 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 liens de rappel HTTP](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) côté serveur pour détecter si le paiement aboutit ou échoue. Un `PaymentIntent`peut être associé à plusieurs objets [Charge](https://docs.stripe.com/api/charges.md) s’il y a eu plusieurs tentatives de paiement. Par exemple, les nouvelles tentatives peuvent créer plusieurs `Charges`. Pour chaque charge, vous pouvez vérifier le [résultat](https://docs.stripe.com/api/charges/object.md#charge_object-outcome) et les [détails du mode de paiement](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details) utilisé. ## Optimisation des moyens de paiement pour les prochains achats 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 ou 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 configurée pour payer pendant une session, mais il est probable que l’institution financière 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 pour les paiements hors session sont plus susceptibles d’entraîner des frictions supplémentaires. Utilisez la configuration *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) si vous n’avez pas l’intention d’accepter les paiements hors session avec la carte enregistrée. ## Libellé de relevé de compte dynamique Le [libellé de relevé](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) de votre compte Stripe s’affiche par défaut sur les relevés de vos clients chaque fois que vous effectuez un prélèvement sur leur carte. Pour afficher un libellé différent sur 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 et `statement_descriptor_suffix` pour les paiements par carte. Les [libellés de relevé](https://docs.stripe.com/get-started/account/statement-descriptors.md) de compte sont limités à 22 caractères, ne peuvent pas contenir les caractères spéciaux `<`, `>`, `'`, `"`, ou `*`, et ne doivent pas être composés uniquement de chiffres. Lorsque vous utilisez des libellés de relevé dynamiques, le texte dynamique est ajouté au [préfixe du libellé de relevé de compte](https://dashboard.stripe.com/settings/public) 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 2 caractères sont inclus dans le nombre limite de 22 caractères. ## Stockage d’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’ont aucune incidence 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 des informations significatives pour vous à l’activité Stripe. Toutes les métadonnées que vous incluez sont visibles dans le Dashboard (par exemple sur la page d’un paiement donné) ainsi que dans de nombreux rapports. Par exemple, vous pouvez associer l’ID attribué à la commande par votre boutique au PaymentIntent correspondant à celle-ci. Pour vos équipes, le rapprochement des paiements sur Stripe et des commandes enregistrées sur votre système interne s’en trouvera grandement facilité. 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 sur les clients et leurs commandes sous forme de métadonnées. Ensuite, vous pouvez définir [des règles Radar basées sur les attributs de](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) métadonnées et disposer de plus 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, 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)