Récupérer les paiements d’abonnement échoués sur Braintree

La facturation récurrente de Braintree est volontairement minimaliste. Elle prélève les abonnements, relance les prélèvements échoués selon un calendrier que vous choisissez, et vous dit ce qui s’est passé par des webhooks. Tout le reste, y compris les emails aux clients, une page pour mettre à jour la carte et ce que fait votre produit pendant qu’un abonnement est en retard de paiement, est à votre charge. Ce guide couvre ce que Braintree fait nativement, les réglages qui comptent et les éléments à ajouter. Il se termine par une courte section sur les litiges, car un renouvellement échoué ou contesté en devient souvent un.

Il s’en tient à la documentation de Braintree : les réglages avancés de la facturation récurrente, la vue d’ensemble de la facturation récurrente, Statuses, Subscription: Retry Charge, les webhooks d’abonnement, Account Updater et Managing disputes via the API (tous consultés en novembre 2026).

Ce qui se passe quand un prélèvement d’abonnement échoue

Quand Braintree facture un abonnement et que la transaction est refusée par le processeur ou rejetée par la passerelle, l’abonnement passe en Past Due. À partir de là, d’après le guide des réglages avancés :

• Braintree relance automatiquement si les relances sont activées dans le Control Panel.
• Une relance réussie ramène l’abonnement à Active, tant qu’il n’a pas dépassé sa dernière date de facturation.
• Les relances automatiques ne modifient pas les dates de début et de fin de la période de facturation en cours.
• Certains codes de refus, comme une carte expirée ou volée, ne sont jamais relancés, car ils indiquent que la transaction a peu de chances de réussir un jour.

L’objet abonnement vous aide à suivre tout cela : daysPastDue donne le nombre de jours de retard de l’abonnement, et failureCount compte les tentatives de prélèvement échouées consécutives.

Les statuts d’abonnement en bref

Statut	Signification (d’après la référence des statuts de Braintree)
Active	Facturation normale
Past Due	Un prélèvement a échoué ; des relances peuvent être en attente
Canceled	Aucune facturation ne suivra
Expired	L’abonnement a atteint son nombre de cycles de facturation

Expired n’est pas un état d’échec ; un abonnement qui se termine pour défaut de paiement apparaît comme Canceled ou reste Past Due, selon vos réglages.

Les réglages de relance

Les relances se configurent dans le Control Panel, sous Account Settings, Recurring Billing, Options, pas par l’API. Les réglages documentés par Braintree :

• Relancer ou non automatiquement les transactions échouées.
• Jours avant la première relance, entre 1 et 10 jours.
• Que faire après l’échec des relances : résilier l’abonnement, continuer à relancer ou le laisser en retard de paiement.

Le dernier réglage mérite un choix réfléchi :

Option	Ce que fait Braintree	Quand c’est pertinent
Cancel	Met fin à l’abonnement	Vous voulez un état final clair et ferez revenir les clients séparément
Continue retrying	Relance une fois par cycle de facturation, à la date de facturation habituelle	Offres de faible montant où les clients approvisionnent souvent leur compte plus tard
Leave past due	Le solde s’accumule à chaque cycle, sans nouvelle tentative	Vous encaisserez vous-même et avez besoin de l’historique

Avec « leave past due », le solde grossit à chaque cycle sans nouvelle tentative, donc quelqu’un doit contacter le client. Avec « continue retrying », il n’y a qu’une tentative par cycle, ce qui ne remplace pas des relances rapides après le premier échec.

Relances manuelles

Vous pouvez relancer vous-même un abonnement en retard avec Subscription: Retry Charge, depuis l’API ou le Control Panel. Passez true pour soumettre automatiquement la transaction au règlement si la relance réussit. Une relance manuelle réussie ramène l’abonnement à Active ; une relance manuelle échouée ne compte pas parmi les tentatives automatiques. C’est ce que vous appelez juste après qu’un client a mis à jour sa carte, plutôt que d’attendre la prochaine relance prévue.

Account Updater

Account Updater demande des données à jour pour les cartes du vault qui ont expiré ou été remplacées, ce qui évite certains échecs avant qu’ils ne surviennent. D’après la documentation de Braintree :

• Les mises à jour dépendent de la participation de la banque émettrice ; les cartes prépayées et les cartes utilisées via Apple Pay ou Google Pay ne sont pas prises en charge.
• Après le premier lot, les demandes partent en continu, notamment quand un paiement récurrent est dû dans les deux semaines, et après certains refus.
• Vous pouvez consulter les mises à jour dans le Control Panel, dans un rapport ou via un webhook quotidien.

Un détail important : ajouter un nouveau moyen de paiement au vault d’un client n’y fait pas passer les abonnements existants. Si un client vous donne une nouvelle carte, mettez à jour le token de moyen de paiement de l’abonnement, puis relancez le prélèvement.

Les webhooks d’abonnement

Braintree envoie ces types de webhooks d’abonnement :

Type	Quand il se déclenche	Que faire
subscription_charged_unsuccessfully	Un abonnement existant ne produit pas de prélèvement réussi (ni sur les relances manuelles, ni sur le prélèvement initial)	Enregistrer le refus, lancer les messages au client
subscription_went_past_due	L’abonnement passe d’Active à Past Due (une fois par cycle)	Afficher un bandeau dans l’app, envoyer le premier email
subscription_charged_successfully	Un prélèvement réussit	Arrêter les messages, retirer le bandeau
subscription_went_active	L’abonnement devient Active	Rétablir l’accès
subscription_canceled	L’abonnement est résilié	Retirer l’accès, enregistrer la date de résiliation
subscription_expired	L’abonnement a atteint son dernier cycle	Mettre fin à l’accès comme prévu

Braintree précise que la date de résiliation n’est pas renvoyée dans les résultats de recherche d’abonnements ; si vous en avez besoin, enregistrez-la à l’arrivée de subscription_canceled.

Ce que vous devez ajouter vous-même

Braintree documente quelques notifications email pour la facturation récurrente ; vérifiez ce qu’elles couvrent pour votre compte. Un processus de récupération complet demande généralement davantage :

1. Un premier email sur subscription_went_past_due, envoyé le jour même, avec un seul lien pour mettre à jour la carte. Ne citez pas la raison brute du refus.
2. Une page de mise à jour de la carte construite avec l’intégration côté client de Braintree, pour que les données de carte aillent directement chez Braintree sans jamais toucher vos serveurs. En cas de succès, mettez à jour le moyen de paiement de l’abonnement et appelez Retry Charge.
3. Des rappels calés sur les relances, par exemple un jour après l’échec de chaque relance prévue.
4. Un dernier avis avant la résiliation de l’abonnement, avec la date.
5. Un bandeau dans l’app tant que l’abonnement est en retard de paiement.
6. Un traitement à part pour les refus définitifs. Si la carte est expirée ou déclarée volée, Braintree ne relancera pas, donc l’email est la seule voie de récupération : envoyez-le immédiatement.

Les litiges Braintree

Les litiges sont l’autre façon dont le revenu d’abonnement fuit, et Braintree fournit une API complète pour eux, décrite dans Managing disputes via the API :

• Des webhooks de type dispute_opened, dispute_won, dispute_lost, dispute_accepted, dispute_expired et d’autres vous disent quand un dossier s’ouvre ou change de statut.
• Les preuves texte (par exemple un numéro de remboursement ou de suivi) s’ajoutent avec Dispute: Add Text Evidence.
• Les preuves fichier se téléversent avec une requête Document Upload, puis se joignent avec Dispute: Add File Evidence. La documentation de Braintree indique une limite de 4 Mo par fichier et de 5 Mo par litige par défaut.
• Finalize envoie votre réponse et vos preuves à la banque du titulaire. Les preuves ne peuvent être ajoutées que tant que le litige est ouvert.
• Date limite de réponse : chaque litige en a une. Si vous la ratez, vous perdez le droit de contester et le litige passe en expired.
• Accepter un litige signifie que vous ne le contestez pas et que les fonds retournent au client.

Pour un business d’abonnement, la preuve la plus solide est généralement l’historique : quand le client s’est inscrit, ce qu’il a utilisé, quels rappels il a reçus et s’il a jamais tenté de résilier. Rassemblez-le avant que l’échéance n’approche.

Le faire avec NoChurn

Braintree garde le traitement des cartes, votre compte marchand et ses propres relances d’abonnement ; NoChurn travaille à côté. Il se connecte avec votre merchant ID et vos clés API Braintree, suit les webhooks de Braintree et ajoute des emails de récupération rédigés par l’IA que vous relisez avant leur envoi, avec une page hébergée pour mettre à jour le moyen de paiement. Pour les litiges, NoChurn réunit automatiquement les preuves (réponses du parcours d’annulation, emails envoyés, usage, conversations de support) et rédige une réponse avec l’IA, envoyée à Braintree seulement après votre relecture. Il ajoute aussi des parcours d’annulation avec offres et une annulation en un clic toujours visible, des emails de reconquête à J30, J60 et J90, et un score de churn de 0 à 100. Voir NoChurn + Braintree.