Come recuperare i pagamenti falliti in Zuora

Zuora ti dà molto controllo sull’incasso dei pagamenti, il che significa anche molte impostazioni da configurare bene. I pagamenti falliti in Zuora toccano almeno quattro aree: payment run, regole di nuovo tentativo, notifiche e il modo in cui i clienti aggiornano il metodo di pagamento. Questa guida le passa in rassegna una per una e si chiude con un piano di configurazione pratico.

Si attiene alla documentazione di Zuora: Payment runs, Configure payment retry rules, Payment Retry, Configurable Payment Retry, Payment attempts and retry rules, Standard events for Zuora Payments e How do I allow customers to modify their stored payment methods? (tutte consultate a novembre 2026). I nomi dei campi possono variare con la versione del tuo tenant, quindi verificali nelle tue impostazioni.

Passo 1: capire i payment run

In Zuora, l’incasso automatico avviene tramite i payment run. Un payment run incassa le fatture aperte usando metodi di pagamento elettronici come carte o ACH. Secondo la documentazione sui payment run:

• Un run può elaborare fino a 200.000 fatture.
• Esistono run ad hoc, che avvii a mano, e run ricorrenti, che vengono eseguiti con un calendario giornaliero, settimanale o mensile.
• I run incassano solo dagli account con auto-pay attivo. L’auto-pay si imposta su ogni account cliente, quindi un account senza non verrà mai addebitato da un run, e le sue fatture resteranno semplicemente aperte.
• Quando una fattura è in fase di elaborazione da parte di un pagamento, viene bloccata, e qualsiasi altro pagamento su di essa fallisce. Zuora consiglia di decidere quali fatture vengono incassate con quale metodo (payment run, payment page, API) perché non si scontrino.

La prima cosa da controllare quando «Zuora non ritenta» spesso non riguarda affatto i nuovi tentativi: è se l’account ha l’auto-pay attivo e un metodo di pagamento elettronico predefinito.

Passo 2: scegliere il meccanismo di nuovo tentativo

Zuora ha due modi per ritentare un pagamento elettronico fallito. Zuora sconsiglia di usarli entrambi contemporaneamente.

Regole di nuovo tentativo a livello di tenant

Le regole integrate, descritte in Configure payment retry rules, si applicano per impostazione predefinita all’elaborazione dei pagamenti falliti quando il payment retry è attivo nel tuo tenant. Imposti:

• il numero massimo di volte consecutive in cui un metodo di pagamento fallito viene ritentato;
• un intervallo minimo dall’ultimo tentativo fallito (per esempio, con 8 ore, non avviene alcun nuovo tentativo automatico se l’ultimo fallimento risale a meno di 8 ore prima);
• un periodo di tempo durante il quale i pagamenti non vengono ritentati.

Puoi sovrascriverle per metodo di pagamento. Queste regole sono semplici e prevedibili, ma le stesse regole valgono per ogni rifiuto, qualunque sia il motivo.

Configurable Payment Retry (CPR)

Configurable Payment Retry è l’opzione più flessibile di Zuora. Ti permette di impostare la logica dei nuovi tentativi per gruppo di clienti e per codice di risposta del gateway, mappando i codici su categorie come hard, medium e soft decline. Punti chiave dalla documentazione:

Impostazione o comportamento	Cosa documenta Zuora
Finestra dei tentativi	Giorni dall’ingresso nel ciclo di nuovi tentativi all’ultimo tentativo, massimo 90 giorni
Numero di tentativi	Massimo 20; il payment run fa il primo tentativo, CPR fa gli altri
Smart Retry	Un modello di machine learning facoltativo che sceglie i momenti dei tentativi in base alle caratteristiche dell’abbonato e della transazione
Hard decline	Un’opzione Stop Retry On Hard Declines chiude il ciclo su un hard decline
Tempi	I tentativi partono in batch allo scoccare dell’ora, quindi non possono essere più frequenti di uno all’ora
Metodi di pagamento	Solo pagamenti con carta, non addebiti diretti come ACH o SEPA
Modifiche alle regole	Si applicano solo ai tentativi futuri; i cicli conclusi non vengono riavviati

Due comportamenti dalle buone pratiche di CPR sono facili da trascurare:

• CPR disattiva l’auto-pay mentre è in corso un ciclo di nuovi tentativi, così il payment run normale non addebita di nuovo la fattura. Secondo la pagina sulle impostazioni dell’auto-pay, ciò che cambia dipende dal livello del nuovo tentativo: a livello di fattura viene disattivato solo il flag auto-pay della fattura; a livello di account viene disattivato l’auto-pay dell’account, che viene riattivato solo una volta incassato il pagamento. Zuora consiglia il nuovo tentativo a livello di fattura, che mantiene l’account idoneo ai payment run futuri. Una pagina di buone pratiche più vecchia descrive entrambi i flag impostati a false, quindi verifica quale livello usa il tuo tenant.
• Per fermare subito i nuovi tentativi (per esempio, il cliente ha pagato con bonifico), chiudi a mano il ciclo di nuovi tentativi, cosa che puoi fare tramite le API di CPR.

Se non sai come classificare un codice di risposta, Zuora suggerisce di mapparlo come soft decline e monitorare i risultati. Zuora documenta anche un modo per testare Smart Retry rispetto alla tua logica esistente prima di passare tutto al nuovo sistema.

Passo 3: avvisare il cliente, con notifiche e callout

I nuovi tentativi recuperano i rifiuti temporanei. Le carte scadute, sostituite o bloccate richiedono il cliente. Gli eventi standard per i pagamenti di Zuora ti danno gli agganci:

• Payment Declined: scatta quando il gateway rifiuta un pagamento elettronico. Un’impostazione «Sequence of failed attempt» stabilisce a quale fallimento consecutivo scatta la notifica; viene confrontata con il NumConsecutiveFailures del metodo di pagamento e per impostazione predefinita vale 1. I pagamenti esterni non fanno scattare queste notifiche.
• Avvisi di scadenza della carta: eventi 15 e 30 giorni prima della scadenza della carta predefinita (la data di scadenza è l’ultimo giorno del mese di scadenza). Ti permettono di chiedere una nuova carta prima che qualcosa fallisca.
• Payment Method Updated: scatta quando cambia il metodo di pagamento predefinito, ed è il tuo segnale per fermare i promemoria.

Ogni notifica può essere consegnata come email o come callout, una richiesta HTTP al tuo endpoint, configurata nella definizione della notifica. Usa i callout per aggiornare la tua app (banner, accesso) e per far partire qualsiasi messaggio gestito fuori da Zuora. Anche Zuora Workflow può reagire a questi eventi e inviare email da modello o chiamare API esterne, se preferisci tenere la logica dentro Zuora.

Un semplice piano di notifiche:

Trigger	Messaggio	Canale
La carta scade tra 30 giorni	«La tua carta sta per scadere, aggiornala qui»	Email
Primo pagamento rifiutato	«Il tuo pagamento non è andato a buon fine», con il link di aggiornamento	Email e in-app
Terzo fallimento consecutivo	Promemoria con la data in cui l’accesso viene limitato	Email
Metodo di pagamento aggiornato	Conferma, nessun altro promemoria	Email

Passo 4: lasciare che il cliente aggiorni il metodo di pagamento

Il link di aggiornamento in quelle email deve portare da qualche parte. Zuora documenta tre modi per cambiare un metodo di pagamento salvato nella sua guida sulla modifica dei metodi di pagamento salvati:

1. La pagina hosted del metodo di pagamento per le carte di credito, passando l’ID del metodo di pagamento esistente (pmId) così il cliente può aggiornare i dati della carta. È la strada che tiene i dati della carta fuori dai tuoi server; Zuora consiglia Payment Pages 2.0 invece di gestire i dati della carta tramite API.
2. L’operazione REST Update a payment method. Il riferimento API di Zuora raccomanda vivamente Payment Pages 2.0 invece di chiamarla direttamente, e inviare un numero di carta tramite questa operazione fa rientrare i tuoi sistemi nel perimetro PCI.
3. L’interfaccia di Zuora, nella sezione Electronic Payment Methods dell’account cliente, per gli agenti del supporto.

Dopo il salvataggio di un nuovo metodo di pagamento predefinito, assicurati che la fattura aperta venga davvero incassata, dal payment run successivo (controlla l’auto-pay, che CPR potrebbe aver disattivato) o con un pagamento immediato. Ricorda il blocco della fattura: non lasciare che una payment page e un payment run addebitino la stessa fattura nello stesso momento.

Una checklist di recupero per Zuora

1. Verifica l’auto-pay su ogni account con abbonamento attivo e conferma che esista un metodo di pagamento elettronico predefinito.
2. Scegli un solo meccanismo di nuovo tentativo: regole del tenant per semplicità, CPR per una logica che tenga conto del rifiuto e dei gruppi di clienti. Non entrambi.
3. Mappa i codici di risposta in CPR e attiva Stop Retry On Hard Declines, così una carta rubata non viene ritentata per settimane.
4. Tieni la finestra dei tentativi più breve del periodo di fatturazione per i piani mensili.
5. Attiva gli avvisi di scadenza della carta a 30 e 15 giorni, e guarda il Payment Method Updater, che chiede ai servizi di aggiornamento di Visa, Mastercard e American Express i nuovi dati della carta prima del bill cycle day sui gateway supportati.
6. Configura la notifica Payment Declined con un link a una pagina di pagamento hosted, più un callout alla tua app.
7. Incassa dopo un aggiornamento: conferma che la fattura venga addebitata una volta salvata una nuova carta.
8. Rivedi i rifiuti ogni mese per codice di risposta e gruppo di clienti.

Farlo con NoChurn

Zuora resta responsabile di fatturazione, payment run, nuovi tentativi e del tuo gateway. NoChurn si collega tramite un client OAuth di Zuora, importa account e abbonamenti, riceve le notifiche di Zuora e aggiunge email di recupero scritte dall’IA che controlli prima che partano, con un link per aggiornare il metodo di pagamento. Aggiunge anche flussi di disdetta con motivi, offerte (uno sconto o un cambio di piano sull’abbonamento Zuora) e una disdetta in un clic sempre visibile, email di win-back a 30, 60 e 90 giorni in base al motivo della disdetta e un churn score da 0 a 100. Le contestazioni arrivano dal gateway dietro Zuora; con Stripe o Braintree, NoChurn raccoglie le prove e scrive una bozza di risposta che controlli tu. Vedi NoChurn + Zuora.