Utiliser des destinations d'événements avec des abonnements

Stripe envoie les notifications à votre application au moyen de destinations d’événements, qui vous aident à gérer vos abonnements, car la majeure partie de l’activité se fait de manière asynchrone.

Pour utiliser des destinations d’événements avec vos abonnements :

1. Créez un endpoint de webhook dans votre application.
2. Ajoutez la logique voulue pour gérer les événements Stripe. Pour les abonnements, il s’agit principalement de traiter les échecs de paiement et les changements d’état de l’abonnement (comme le basculement d’une période d’essai à l’état actif).
3. Testez votre endpoint de webhook pour confirmer qu’il fonctionne comme prévu.

Si votre application fonctionne sur AWS, vous pouvez configurer Stripe de façon à envoyer les événements directement à AWS EventBridge dans votre compte AWS.

Découvrez comment configurer et utiliser les destinations d’événements. Vous pouvez également utiliser le guide de démarrage relatif aux webhooks pour créer un endpoint de webhook minimal.

Subscription events

Stripe déclenche des événements chaque fois qu’un abonnement est créé ou modifié. Certains événements sont envoyés dès la création de l’abonnement, tandis que d’autres se répètent régulièrement à l’occasion de chaque facturation.

Veillez à ce que votre intégration gère les événements de manière adéquate. Par exemple, vous pouvez envoyer un e-mail à votre client en cas d’échec de paiement ou révoquer son accès s’il annule son abonnement.

Le tableau suivant décrit les événements les plus courants liés aux abonnements et, le cas échéant, suggère les actions à entreprendre pour les gérer.

Handle payment failures

Les événements constituent un moyen sûr pour Stripe de vous informer des échecs de paiement de vos factures d’abonnement. Certains échecs de paiement sont temporaires : par exemple, l’émetteur de la carte peut refuser le débit initial, mais autoriser une nouvelle tentative automatique par la suite. D’autres échecs de paiement sont en revanche définitifs, comme ceux liés à l’absence de moyen de paiement utilisable pour le client, et nécessitent une action.

Veuillez vous reporter au guide de présentation des abonnements pour en savoir plus sur la façon de gérer les échecs de paiement qui nécessitent un moyen de paiement.

Handle payments that require additional action

Certains moyens de paiement peuvent nécessiter des étapes supplémentaires, comme une authentification du client, pour que l’opération puisse aboutir. Si vous recevez de tels événements, votre application doit notifier le client pour qu’il effectue l’action requise. Pour plus d’informations sur la façon de gérer les événements nécessitant une action supplémentaire, consultez le guide de présentation des abonnements.

Track active subscriptions

Les abonnements nécessitent de la coordination entre votre site et Stripe : l’aboutissement ou l’échec des paiements récurrents détermine la continuité d’accès à votre produit ou service.

Dans une intégration type, vous stockez les identifiants de vos clients et une valeur d’horodatage associée qui représente la date d’expiration de l’accès du client sur votre site lorsqu’un client s’abonne. Lorsque le client se connecte, vous pouvez vérifier si l’horodatage est toujours dans le futur. Si c’est le cas lors de la connexion du client, le compte est actif et le client doit toujours avoir accès au service.

Lors du renouvellement de l’abonnement, Stripe facture le client et tente d’encaisser le paiement soit en débitant automatiquement le moyen de paiement enregistré, soit en envoyant la facture par e-mail aux clients. Stripe notifie votre site de l’état de la facture via les destinations d’événements :

1. Votre site reçoit un événement invoice.paid.

   • Lorsque vous débitez un moyen de paiement automatiquement, votre site reçoit d’abord un événement invoice.upcoming au niveau de la destination d’événement que vous avez configurée, quelques jours avant le renouvellement. Vous pouvez écouter cet événement pour ajouter des postes de facture à la prochaine facture. Si le paramétrage est collection_method=send_invoice, Stripe n’envoie pas d’événement invoice.upcoming.

2. Votre application trouve le client pour lequel le paiement a été effectué.

3. Votre application met à jour la date d’expiration de l’accès du client dans votre base de données sur la date à venir appropriée (plus un ou deux jour(s) de marge).

Catch subscription status changes

Assurez-vous que votre intégration surveille et gère correctement les changements d’état des abonnements décrits dans le tableau suivant.

Certaines modifications d’état requièrent une attention particulière :

• Quelques jours avant la fin de la période d’essai et le passage de l’abonnement de trialing à active, vous recevez un événement customer.subscription.trial_will_end. À réception de cet événement, vérifiez qu’un moyen de paiement est défini pour le client afin de pouvoir le facturer. Si vous le souhaitez, vous pouvez notifier le client qu’il va être débité.

• Lorsqu’un abonnement bascule à l’état past_due, prévenez votre client directement et demandez-lui de mettre ses données de paiement à jour. Stripe propose plusieurs fonctionnalités pour automatiser ce processus. Reportez-vous à la page consacrée au recouvrement de revenus.

• Lorsque l’état d’un abonnement passe à canceled ou unpaid, révoquez l’accès à votre produit.

Webhooks et factures

Register a webhook endpoint to keep track of invoice statuses. Your subscription integration depends on correctly finalizing invoices and properly handling invoice finalization failures.

Lorsque vous activez l’encaissement automatique, Stripe finalise automatiquement la facture et lance son encaissement automatique.

• If Stripe fails to receive a successful response to invoice.created, we delay finalizing all invoices with automatic collection for up to 72 hours, excluding those where you have set a custom scheduled finalization time.
• Répondre correctement à invoice.created implique la gestion de tous les endpoints de webhook configurés pour votre compte, ainsi que les endpoints de webhook de toutes les plateformes auxquelles vous vous êtes connecté.
• Mettre à jour un abonnement pour tenter des paiements en mode synchrone (sur la facture initiale et certaines mises à jour) n’entraîne pas ce délai.
• Invoice finalization failure prevents payment collection for the invoice. Make sure you listen for the invoice.finalization_failed event in your webhook endpoint.

Événements webhook liés à la finalisation des factures

See a complete list of invoice event types.

Finalisation de facture réussie

Stripe attend une heure après réception d’une réponse de réussite pour l’événement invoice.created avant de tenter le paiement. Si nous ne recevons aucune réponse de réussite dans les 72 heures, nous tentons de finaliser la facture et de l’envoyer.

Si vous souhaitez traiter les factures ponctuelles différemment des factures d’abonnement, cochez la propriété subscription dans le corps du webhook. Ceci permet d’indiquer si la facture a été créée pour un abonnement.

En mode production, si votre endpoint de webhook ne renvoie pas de réponse correcte, Stripe renouvelle sa tentative de notification pendant 3 jours au maximum, avec un ralentissement exponentiel du rythme des tentatives. En mode test, nous effectuons trois tentatives sur plusieurs heures. Pendant ce temps, à défaut de recevoir une notification de réussite, aucune facturation du client n’est tentée de notre part. Nous vous informons également par e-mail de l’échec du webhook.

Ce comportement s’applique à tous les endpoints de webhook définis sur votre compte, y compris les cas où une application Stripe Connect ou un service tiers rencontre des problèmes pour gérer les webhooks entrants.

Échec de la finalisation de facture

Lorsque Stripe n’est pas en mesure de finaliser une facture, il envoie un événement invoice.finalization_failed à votre endpoint de webhook. Un abonnement reste actif lorsqu’une facture ne peut pas être finalisée, ce qui signifie que l’utilisateur reste en capacité d’accéder à votre produit tandis que vous ne pouvez pas percevoir ses paiements. Veillez à prendre les mesures utiles pour vos factures non finalisées. Vous ne pouvez pas percevoir de paiements pour une facture qui n’a pas été finalisée.

Pour déterminer la raison de l’échec de la finalisation de la facture, inspectez le champ last_finalization_error de l’objet Invoice, qui vous fournira davantage d’informations sur l’échec et vous renseignera sur la manière d’y remédier.

If you’re using Stripe Tax, check if the automatic_tax.status field is requires_location_inputs, indicating that the address details are invalid or insufficient. If Stripe Tax can’t find a recognized customer location, we can’t finalize the invoice. Learn how to handle invoice finalization failures.

Testing

To test event destinations, choose one of these two options:

1. Perform actions in test mode that send legitimate events to your event destination. For example, to trigger the charge.succeeded event, you can use a test card that produces a successful charge.
2. Déclenchez des événements à l’aide de l’interface de ligne de commande Stripe ou via Stripe pour Visual Studio Code.