Come recuperare i pagamenti falliti degli abbonamenti su Braintree
Come Braintree gestisce gli addebiti falliti: stato Past Due, nuovi tentativi automatici, Account Updater, webhook degli abbonamenti e contestazioni.
Di Florian
La fatturazione ricorrente di Braintree è volutamente essenziale. Addebita gli abbonamenti, ritenta gli addebiti falliti secondo un calendario che scegli tu e ti dice cosa è successo tramite i webhook. Tutto il resto, comprese le email ai clienti, una pagina per aggiornare la carta e cosa fa il tuo prodotto mentre un abbonamento è in arretrato, spetta a te. Questa guida copre cosa fa Braintree in modo nativo, le impostazioni che contano e i pezzi che devi aggiungere. Si chiude con una breve sezione sulle contestazioni, perché un rinnovo fallito o contestato spesso diventa una di esse.
Si attiene alla documentazione di Braintree: le impostazioni avanzate della fatturazione ricorrente, la panoramica della fatturazione ricorrente, Statuses, Subscription: Retry Charge, i webhook degli abbonamenti, Account Updater e Managing disputes via the API (tutti consultati a novembre 2026).
Cosa succede quando l’addebito di un abbonamento fallisce
Quando Braintree fattura un abbonamento e la transazione viene rifiutata dal processore o respinta dal gateway, l’abbonamento passa a Past Due. Da lì, secondo la guida alle impostazioni avanzate:
- Braintree ritenta automaticamente se i nuovi tentativi sono attivi nel Control Panel.
- Un nuovo tentativo riuscito riporta l’abbonamento ad Active, purché non abbia superato la data di fatturazione finale.
- I nuovi tentativi automatici non cambiano le date di inizio e fine del periodo di fatturazione in corso.
- Alcuni codici di rifiuto, come una carta scaduta o rubata, non vengono mai ritentati perché indicano che la transazione difficilmente andrà mai a buon fine.
L’oggetto subscription ti aiuta a seguire la situazione: daysPastDue indica da quanti giorni l’abbonamento è in arretrato, e failureCount conta i tentativi di addebito falliti consecutivi.
Stati dell’abbonamento in sintesi
| Stato | Significato (dal riferimento degli stati di Braintree) |
|---|---|
| Active | Fatturazione normale |
| Past Due | Un addebito è fallito; potrebbero esserci nuovi tentativi in sospeso |
| Canceled | Non ci saranno ulteriori addebiti |
| Expired | L’abbonamento ha raggiunto il numero di cicli di fatturazione impostato |
Expired non è uno stato di errore; un abbonamento che termina per mancato pagamento compare come Canceled o resta Past Due, a seconda delle tue impostazioni.
Le impostazioni dei nuovi tentativi
I nuovi tentativi si configurano nel Control Panel in Account Settings, Recurring Billing, Options, non tramite l’API. Le impostazioni documentate da Braintree:
- Se ritentare automaticamente le transazioni fallite.
- Giorni prima del primo nuovo tentativo, tra 1 e 10 giorni.
- Cosa fare quando i nuovi tentativi falliscono: disdire l’abbonamento, continuare a ritentare o lasciarlo in arretrato.
L’ultima impostazione merita una scelta ponderata:
| Opzione | Cosa fa Braintree | Quando ha senso |
|---|---|---|
| Cancel | Termina l’abbonamento | Vuoi uno stato finale chiaro e riconquisterai i clienti separatamente |
| Continue retrying | Ritenta una volta per ciclo di fatturazione, alla solita data di fatturazione | Piani di basso valore in cui i clienti spesso ricaricano più tardi |
| Leave past due | Il saldo continua ad accumularsi a ogni ciclo, senza ulteriori tentativi | Incasserai tu e ti serve lo storico |
Con “leave past due”, il saldo cresce a ogni ciclo senza alcun nuovo tentativo, quindi qualcuno deve contattare il cliente. Con “continue retrying”, c’è un solo tentativo per ciclo, quindi non sostituisce dei nuovi tentativi tempestivi dopo il primo fallimento.
Nuovi tentativi manuali
Puoi ritentare tu un abbonamento in arretrato con Subscription: Retry Charge, dall’API o dal Control Panel. Passa true per inviare automaticamente la transazione al regolamento se il tentativo riesce. Un tentativo manuale riuscito riporta l’abbonamento ad Active; un tentativo manuale fallito non conta come uno dei tentativi automatici. È questa la chiamata da fare subito dopo che un cliente aggiorna la carta, invece di aspettare il prossimo tentativo programmato.
Account Updater
Account Updater richiede i dati aggiornati delle carte salvate nel vault che sono scadute o state sostituite, il che previene alcuni fallimenti prima che accadano. Secondo la documentazione di Braintree:
- Gli aggiornamenti dipendono dall’adesione della banca emittente; le carte prepagate e le carte usate tramite Apple Pay o Google Pay non sono supportate.
- Dopo il batch iniziale, le richieste partono a ciclo continuo, anche quando un pagamento ricorrente è in scadenza entro due settimane, e dopo alcuni rifiuti.
- Puoi esaminare gli aggiornamenti nel Control Panel, in un report o tramite un webhook giornaliero.
Un dettaglio importante: aggiungere un nuovo metodo di pagamento al vault di un cliente non sposta su di esso gli abbonamenti esistenti. Se un cliente ti dà una nuova carta, aggiorna il token del metodo di pagamento dell’abbonamento, poi ritenta l’addebito.
Webhook per gli abbonamenti
Braintree invia questi tipi di webhook degli abbonamenti:
| Tipo | Quando scatta | Cosa fare |
|---|---|---|
subscription_charged_unsuccessfully |
Un abbonamento esistente non produce un addebito riuscito (non sui tentativi manuali, non sull’addebito iniziale) | Registra il rifiuto, avvia i messaggi al cliente |
subscription_went_past_due |
L’abbonamento passa da Active a Past Due (una volta per ciclo) | Mostra un banner nell’app, invia la prima email |
subscription_charged_successfully |
Un addebito riesce | Ferma i messaggi, togli il banner |
subscription_went_active |
L’abbonamento diventa Active | Ripristina l’accesso |
subscription_canceled |
L’abbonamento viene disdetto | Togli l’accesso, salva la data di disdetta |
subscription_expired |
L’abbonamento ha raggiunto l’ultimo ciclo | Chiudi l’accesso come previsto |
Braintree nota che la data di disdetta non viene restituita nei risultati di ricerca degli abbonamenti, quindi se ti serve, salvala quando arriva subscription_canceled.
Cosa devi aggiungere tu
Braintree documenta alcune notifiche email per la fatturazione ricorrente; verifica cosa coprono per il tuo account. Un processo di recupero completo di solito richiede di più:
- Una prima email su
subscription_went_past_due, inviata lo stesso giorno, con un solo link per aggiornare la carta. Non citare il motivo grezzo del rifiuto. - Una pagina di aggiornamento della carta costruita con l’integrazione lato client di Braintree, così i dati della carta vanno direttamente a Braintree e non toccano mai i tuoi server. In caso di successo, aggiorna il metodo di pagamento dell’abbonamento e chiama Retry Charge.
- Promemoria scanditi sui nuovi tentativi, per esempio un giorno dopo il fallimento di ogni tentativo programmato.
- Un ultimo avviso prima che l’abbonamento venga disdetto, con la data.
- Un banner nell’app mentre l’abbonamento è in arretrato.
- Una gestione separata per i rifiuti hard. Se la carta è scaduta o segnalata come rubata, Braintree non ritenterà, quindi l’email è l’unica via di recupero: inviala subito.
Contestazioni su Braintree
Le contestazioni sono l’altro modo in cui i ricavi da abbonamento si perdono, e Braintree offre un’API completa per gestirle, descritta in Managing disputes via the API:
- I webhook di tipo
dispute_opened,dispute_won,dispute_lost,dispute_accepted,dispute_expirede altri ti dicono quando un caso si apre o cambia stato. - Le prove testuali (per esempio un numero di rimborso o di tracciamento) si aggiungono con Dispute: Add Text Evidence.
- Le prove in file si caricano con una richiesta Document Upload, poi si allegano con Dispute: Add File Evidence. La documentazione di Braintree indica un limite predefinito di 4 MB per file e 5 MB per contestazione.
- Finalize invia la tua risposta e le prove alla banca del titolare. Le prove si possono aggiungere solo mentre la contestazione è aperta.
- Data di risposta: ogni contestazione ne ha una. Se la manchi, perdi il diritto di contestare e la contestazione diventa expired.
- Accettare una contestazione significa che non la contesti e i fondi tornano al cliente.
Per un’azienda in abbonamento, la prova più forte è di solito lo storico: quando il cliente si è iscritto, cosa ha usato, quali promemoria ha ricevuto e se ha mai provato a disdire. Raccoglilo prima che la scadenza si avvicini.
Farlo con NoChurn
Braintree tiene l’elaborazione delle carte, il tuo conto merchant e i propri nuovi tentativi sugli abbonamenti; NoChurn lavora accanto a loro. Si collega con il tuo merchant ID e le chiavi API di Braintree, segue i webhook di Braintree e aggiunge email di recupero scritte dall’IA che rivedi prima dell’invio, con una pagina ospitata per aggiornare il metodo di pagamento. Per le contestazioni, NoChurn raccoglie automaticamente le prove (risposte al flusso di disdetta, email inviate, utilizzo, conversazioni con il supporto) e redige una risposta con l’IA, inviata a Braintree solo dopo la tua revisione. Aggiunge anche flussi di disdetta con offerte e una disdetta in un clic sempre visibile, email di win-back a 30, 60 e 90 giorni e un punteggio di churn da 0 a 100. Vedi NoChurn + Braintree.