# Mises à jour de l'état des paiements Surveiller et vérifier l'état des paiements, afin de pouvoir répondre aux paiements réussis et échoués. Les *PaymentIntents* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) sont mis à jour en fonction des actions effectuées par vos clients ou par les moyens de paiement. Votre intégration peut examiner un PaymentIntent pour déterminer l’état du processus de paiement et ainsi vous permettre d’entreprendre les actions commerciales appropriées ou de répondre aux états nécessitant une intervention supplémentaire. Vous pouvez aussi utiliser le Dashboard Stripe pour configurer votre compte afin de recevoir des e-mails lors des changements d’état des paiements, par exemple à la réussite d’un paiement. Modifiez vos [notifications par e-mail](https://docs.stripe.com/get-started/account/teams.md#email-notifications) dans les [paramètres de l’utilisateur](https://dashboard.stripe.com/settings/user). ## Vérifier l’état du PaymentIntent côté client Lorsqu’un paiement est effectué côté client avec la fonction [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment), vous pouvez examiner le PaymentIntent renvoyé pour déterminer son état actuel : ```javascript (async () => { const {paymentIntent, error} = await stripe.confirmCardPayment(clientSecret); if (error) { // Handle error here } else if (paymentIntent && paymentIntent.status === 'succeeded') { // Handle successful payment here } })(); ``` Voici les résultats possibles lorsque la fonction `confirmCardPayment` est utilisée : | **Événement** | **Ce qui s’est passé** | **Intégration attendue** | | -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Aboutit à un PaymentIntent | Le client a effectué un paiement sur votre page de paiement | Informer le client que son paiement a abouti | | Aboutit à une erreur | Le paiement du client a échoué sur votre page de paiement | Afficher un message d’erreur et inviter votre client à effectuer une nouvelle tentative de paiement | La promesse renvoyée par `confirmCardPayment` aboutit lorsque le processus de paiement réussit ou échoue en renvoyant une erreur. Si le paiement réussit et renvoie un PaymentIntent, son état est toujours `succeeded` (ou `requires_capture` en cas de [capture ultérieure](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)). Lorsque le paiement nécessite une étape supplémentaire, par exemple une authentification, la promesse n’aboutit qu’une fois que cette étape est effectuée ou après expiration du délai. ## Vérifier l’état du PaymentIntent côté client sans utiliser confirmCardPayment Pour vérifier l’état d’un PaymentIntent sans utiliser la fonction `confirmCardPayment`, récupérez-le séparément à l’aide de la fonction [retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) en transmettant la *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)). ```javascript (async () => { const {paymentIntent} = await stripe.retrievePaymentIntent(clientSecret); if (paymentIntent && paymentIntent.status === 'succeeded') { // Handle successful payment here } else { // Handle unsuccessful, processing, or canceled payments and API errors here } })(); ``` Voici quelques [états possibles](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) d’un PaymentIntent après confirmation : | **Ce qui s’est passé** | **État attendu du PaymentIntent** | | ----------------------------------------------------------- | --------------------------------- | | Le client a effectué un paiement sur votre page de paiement | `succeeded` | | Le client n’a pas effectué le paiement | `requires_action` | | Le paiement du client a échoué sur votre page de paiement | `requires_payment_method` | [En savoir plus sur les états des Paymentintents](https://docs.stripe.com/payments/paymentintents/lifecycle.md). ## Suivre un PaymentIntent avec des webhooks Stripe peut envoyer des événements *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) à votre serveur pour vous informer du changement d’état d’un PaymentIntent, ce qui est notamment utile pour déterminer quand fournir les biens ou les services. Ne tentez pas de gérer la *réalisation* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) d’une commande côté client, car vos clients peuvent quitter la page après la finalisation du règlement, mais avant le début du processus de réalisation de la commande. Utilisez donc plutôt des webhooks pour surveiller l’événement `payment_intent.succeeded` et gérer son exécution de manière asynchrone au lieu de tenter de réaliser la commande côté client. > Il est techniquement possible de recourir au polling (en récupérant de façon répétée un PaymentIntent pour vérifier son état) afin de surveiller les changements causés par des opérations asynchrones, plutôt que d’utiliser des webhooks, mais cette solution est bien moins fiable et peut entraîner des problèmes de limite de débit. Stripe applique une [limite de débit](https://docs.stripe.com/testing.md#rate-limits) sur les requêtes API. Ainsi, nous vous recommandons de procéder avec prudence si vous choisissez de recourir au polling. Pour gérer un événement webhook, créez un chemin sur votre serveur et configurez l’endpoint d’un webhook correspondant [dans le Dashboard](https://dashboard.stripe.com/account/webhooks). Stripe envoie l’événement `payment_intent.succeeded` lorsque le paiement réussit et l’événement `payment_intent.payment_failed` lorsque le paiement échoue. La charge utile du webhook inclut l’objet PaymentIntent. L’exemple suivant montre comment gérer les deux événements : #### Ruby ```ruby require 'sinatra' require 'stripe' post '/webhook' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature status 400 return end case event['type'] when 'payment_intent.succeeded' intent = event['data']['object'] puts "Succeeded:", intent['id'] # Fulfill the customer's purchase when 'payment_intent.payment_failed' intent = event['data']['object'] error_message = intent['last_payment_error'] && intent['last_payment_error']['message'] puts "Failed:", intent['id'], error_message # Notify the customer that payment failed end status 200 end ``` Lorsque le paiement échoue, vous pouvez trouver des informations en examinant la propriété `last_payment_error` du PaymentIntent. Vous pouvez informer votre client de l’échec du paiement et l’inviter à réessayer avec un autre moyen de paiement. Réutilisez ensuite le même PaymentIntent pour continuer à suivre l’achat de votre client. ### Gérer des événements de webhook spécifiques La liste suivante décrit comment gérer différents événements de webhook : | Événement | Description | Étapes suivantes | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `processing` | Le paiement du client a été correctement envoyé à Stripe. Ne s’applique qu’aux moyens de paiement pour lesquels la [confirmation de paiement](https://docs.stripe.com/payments/payment-methods.md#payment-notification) est différée. | Attendez que le paiement effectué réussisse ou échoue. | | `succeeded` | Le paiement du client a abouti. | Fulfill the purchased goods or services. | | `amount_capturable_updated` | Le paiement du client est autorisé et prêt à être capturé. | Capturez les fonds disponibles pour le paiement. | | `payment_failed` | Le paiement du client a été refusé par un réseau de cartes ou a expiré. | Contactez votre client par e-mail ou notification push pour l’inviter à fournir un autre moyen de paiement. | Pour tester des webhooks localement, vous pouvez utiliser l’[interface de ligne de commande Stripe](https://docs.stripe.com/stripe-cli.md). Après l’avoir installée, vous pouvez transférer les événements à votre serveur : ```bash stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) ``` En savoir plus sur [la configuration des webhooks](https://docs.stripe.com/webhooks.md). ## Identifier les paiements d’un PaymentIntent Lorsque vous tentez d’encaisser le paiement d’un client, le PaymentIntent crée un API [Charge](https://docs.stripe.com/api/charges.md). Pour accéder à l’identifiant du dernier paiement, inspectez la propriété [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) du PaymentIntent : #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' intent = Stripe::PaymentIntent.retrieve('{{PAYMENT_INTENT_ID}}') latest_charge = intent.latest_charge ``` Pour voir tous les paiements associés à un PaymentIntent, y compris ceux qui n’ont pas abouti, [affichez la liste de tous les paiements](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent) et spécifiez le paramètre `payment_intent`. ```curl curl -G https://api.stripe.com/v1/charges \ -u "<>:" \ -d "payment_intent={{PAYMENTINTENT_ID}}" ``` ## Gérer les actions suivantes Certains moyens de paiement nécessitent des actions supplémentaires, comme l’authentification, pour finaliser le processus de paiement. Stripe.js les gère automatiquement lors de la confirmation du PaymentIntent, mais si vous disposez d’une intégration avancée, il peut s’avérer préférable de les gérer manuellement. La propriété [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) du PaymentIntent indique l’étape suivante à effectuer par votre intégration pour finaliser le paiement. Le type d’actions suivantes possibles peut varier selon le moyen de paiement. Vous trouverez une liste complète des actions suivantes possibles dans la [documentation relative à l’API](https://docs.stripe.com/api.md#payment_intent_object-next_action-type). Pour en savoir plus sur la gestion des actions suivantes requises par différents moyens de paiement, consultez la [documentation relative aux moyens de paiement](https://docs.stripe.com/payments/payment-methods/overview.md).