I decline code di Stripe spiegati: cosa fare per ciascuno

Quando un rinnovo fallisce su Stripe, l’addebito torna con una breve stringa come insufficient_funds o do_not_honor. Quella stringa è l’informazione più utile che ricevi sul fallimento. Ti dice se un nuovo tentativo può funzionare, se il cliente deve fare qualcosa e cosa puoi dirgli.

Questa guida passa in rassegna i decline code che contano di più per gli abbonamenti, raggruppati per cosa dovresti fare. Si attiene a ciò che Stripe documenta nel suo riferimento dei decline code e nella guida ai rifiuti delle carte (entrambi consultati a novembre 2026), e lo dice quando le pagine di Stripe lasciano spazio all’interpretazione.

Dove si trovano i codici

Un pagamento con carta fallito su Stripe può riportare diversi campi. Rispondono a domande diverse:

Campo	Cosa ti dice	Dove trovarlo
decline_code	Il motivo normalizzato da Stripe per il rifiuto dell’emittente, se l’emittente ne ha dato uno	Sull’errore, e su last_payment_error del PaymentIntent
advice_code	Cosa fare dopo: ritentare, non ritentare, o verificare i dati della carta	Sull’errore, accanto al decline code
network_decline_code	Il codice grezzo del circuito della carta	Sull’esito dell’addebito
network_advice_code	Il consiglio del circuito stesso (per Mastercard, i suoi Merchant Advice Code)	Sull’esito dell’addebito

Stripe ha aggiunto i campi network advice e decline code all’API a dicembre 2024. La documentazione di Stripe avverte che il significato di un network_decline_code cambia tra un circuito e l’altro, quindi leggilo sempre insieme al marchio della carta.

Per gli abbonamenti, di solito li leggerai dal webhook invoice.payment_failed: recupera il PaymentIntent della fattura e guarda last_payment_error.

Prima gli advice code

L’advice_code è il segnale più semplice, e la guida ai rifiuti delle carte di Stripe documenta tre valori:

• try_again_later: l’emittente ha rifiutato, ma puoi ritentare. Se i tentativi ripetuti falliscono, il cliente deve contattare il suo emittente.
• do_not_try_again: non usare più questa carta per questa transazione. Guarda il decline code per il motivo.
• confirm_card_data: l’emittente ha rifiutato perché alcuni dati della carta erano sbagliati. Il cliente deve controllare i suoi dati.

Se c’è un advice code, lascia che prevalga su qualsiasi regola generale. Un do_not_try_again su quello che sembra un soft decline significa fermati.

Soft e hard decline

Stripe non etichetta ogni codice come soft o hard, ma la distinzione è utile e Stripe la usa nella sua documentazione sui nuovi tentativi:

• I soft decline sono temporanei. La carta è valida; l’emittente ha detto no questa volta. Ritentare più tardi può funzionare.
• Gli hard decline significano che la carta non può essere addebitata così com’è. La pagina Smart Retries di Stripe elenca i codici che non ritenterà senza un nuovo metodo di pagamento: incorrect_number, lost_card, pickup_card, stolen_card, revocation_of_authorization, revocation_of_all_authorizations, authentication_required, highest_risk_level e transaction_not_allowed.

Per questi hard decline code, Stripe continua a programmare nuovi tentativi sulla fattura, ma un addebito parte solo quando viene collegato un nuovo metodo di pagamento. Se nessuno lo chiede al cliente, non succederà nulla. Spieghiamo nel dettaglio il lato dei nuovi tentativi in come funzionano gli Smart Retries di Stripe.

I codici comuni, e cosa fare

La tabella qui sotto copre i codici che vedrai più spesso sui rinnovi degli abbonamenti. «Descrizione e passo successivo secondo Stripe» riassume il riferimento dei decline code; «Per un abbonamento» è la nostra lettura pratica.

Codice	Descrizione e passo successivo secondo Stripe	Ritentare?	Per un abbonamento
insufficient_funds	Fondi insufficienti; il cliente dovrebbe usare un altro metodo di pagamento	Sì, più tardi	Ritenta in un momento migliore (dopo un probabile giorno di paga); invia un’email al cliente con un link di aggiornamento
generic_decline	Rifiutato per un motivo sconosciuto, o bloccato da Radar; il cliente contatta l’emittente	Qualche volta	Ritenta; invia un’email; suggerisci al cliente di chiamare la banca o provare un’altra carta
do_not_honor	Rifiuto generico dell’emittente senza motivo specifico	Qualche volta	Come generic_decline
processing_error	Errore durante l’elaborazione della carta; riprova, poi contatta l’emittente	Sì	Ritenta presto; invia un’email solo se continua a fallire
card_velocity_exceeded	Il cliente ha superato il saldo, il limite di credito o il limite di transazione; contatti l’emittente	Sì, più tardi	Ritenta più tardi; cita un limite di spesa nell’email
expired_card	La carta è scaduta; usa un’altra carta	No	Verifica prima un aggiornamento automatico della carta; altrimenti chiedi una nuova carta
incorrect_cvc	Il CVC non è corretto; riprova con il CVC corretto	No	Chiedi al cliente di reinserire la carta nella pagina di aggiornamento
incorrect_number	Il numero di carta non è corretto	No	Chiedi una nuova carta
lost_card, stolen_card	Segnalata come smarrita o rubata; presentalo come rifiuto generico	No	Chiedi una nuova carta, senza citare il motivo
pickup_card	La carta non può essere usata per questo pagamento (forse segnalata come smarrita o rubata); contatta l’emittente	No	Chiedi una nuova carta
fraudulent	Stripe sospetta una frode; mostra lo stesso messaggio di un rifiuto generico	No	Gestisci con cautela; non rivelare il motivo
authentication_required	La banca richiede che il cliente si autentichi	Non senza il cliente	Invia un link per confermare il pagamento; vedi SCA sui rinnovi
revocation_of_authorization, stop_payment_order	Stripe li elenca con un motivo sconosciuto; il cliente contatta l’emittente	No	Chiedi un nuovo metodo di pagamento; verifica se il cliente voleva smettere di pagare
transaction_not_allowed	Non consentito su questa carta	No	Chiedi un’altra carta o un altro metodo di pagamento

Due punti sono facili da trascurare:

1. Alcuni motivi non vanno mostrati al cliente. Per lost_card, stolen_card e fraudulent, il riferimento di Stripe dice di presentare il rifiuto come rifiuto generico. La tua email di sollecito deve dire «il tuo pagamento è stato rifiutato», mai «la tua carta è stata segnalata come rubata».
2. «Contatta il tuo emittente» è un’istruzione vera. Per i rifiuti generici, una telefonata alla banca spesso sblocca la situazione. Va bene dirlo nell’email, in breve.

I limiti ai nuovi tentativi sono reali

Ritentare non è gratis, nemmeno per i soft decline. I circuiti delle carte limitano quanto spesso un merchant può ritentare una carta rifiutata, e gli emittenti possono considerare i tentativi eccessivi un segnale di frode.

Secondo l’articolo di supporto di Stripe sui pagamenti bloccati per tentativi eccessivi (consultato a novembre 2026), le regole di Visa vietano in linea generale più di 15 tentativi di un singolo pagamento in 30 giorni. Per le transazioni Visa con prezzo integrato, Stripe blocca i tentativi dopo il 15°, quando giudica bassa la probabilità di successo. I valori predefiniti di Stripe (8 tentativi per Smart Retries) restano ben sotto, ma una logica di nuovi tentativi personalizzata fuori da Stripe può superarli se non fai attenzione.

Il segnale equivalente di Mastercard è il Merchant Advice Code, che Stripe espone come network_advice_code. La documentazione dei processor, come il riferimento dei merchant advice code di Braintree, descrive codici che significano «non riprovare» e uno che significa che il titolare ha annullato il pagamento ricorrente. Quando li vedi, smetti di ritentare quella carta.

Regole pratiche:

• Conta ogni tentativo per fattura, compresi quelli avviati dal tuo codice.
• Fermati subito su un hard decline o su un advice do_not_try_again.
• Non ritentare la stessa carta più volte nello stesso giorno «per sicurezza».
• Distanzia i tentativi sui soft decline, e allineali a quando è probabile che ci siano soldi disponibili.

Cosa dire al cliente, per gruppo

La maggior parte dei team invia la stessa email per ogni fallimento. Qualche variante per gruppo di rifiuto funziona meglio e non richiede molto lavoro in più.

Gruppo	Codici	Messaggio dell’email
Fondi o limiti	insufficient_funds, card_velocity_exceeded	«Riproveremo il [data]. Se preferisci usare un’altra carta, aggiornala qui.»
Non chiaro	generic_decline, do_not_honor, processing_error	«La tua banca ha rifiutato il pagamento. Spesso è un blocco temporaneo; una breve telefonata alla banca, o un’altra carta, di solito risolve.»
Carta inutilizzabile	expired_card, lost_card, stolen_card, pickup_card, incorrect_number	«Ci serve una nuova carta per mantenere attivo il tuo abbonamento.» Nessun motivo indicato.
Autenticazione	authentication_required	«La tua banca ti chiede di confermare questo pagamento. Ci vuole un minuto.»
Dati della carta	incorrect_cvc, advice confirm_card_data	«Alcuni dati della carta non corrispondevano. Reinserisci la tua carta.»

Email pronte all’uso per ogni passaggio sono nei nostri modelli di email di sollecito.

Registrare bene i decline code

Non puoi migliorare ciò che non misuri. Per ogni rinnovo fallito, salva:

• ID della fattura, ID del cliente, importo e valuta.
• Numero e data del tentativo.
• decline_code, advice_code, network_decline_code, network_advice_code.
• Marchio della carta, tipo di finanziamento (credito, debito, prepagata) e paese.
• Esito: recuperato (e come: nuovo tentativo, nuova carta, autenticazione), o perso.

Con qualche mese di dati, puoi rispondere alle domande che contano: quali codici si recuperano con un nuovo tentativo e quali solo quando il cliente agisce, se le carte prepagate falliscono più spesso (vedi carte prepagate e virtuali), e se il grosso del lavoro lo fanno le tue email o i tuoi nuovi tentativi.

Raggruppare per i report

I codici grezzi sono troppo granulari per un report mensile. Raggruppali:

Gruppo di report	Codici
Soft: fondi	insufficient_funds, card_velocity_exceeded
Soft: non chiaro	generic_decline, do_not_honor, processing_error, try_again_later
Hard: carta	expired_card, lost_card, stolen_card, pickup_card, incorrect_number, incorrect_cvc
Hard: autorizzazione	revocation_of_authorization, revocation_of_all_authorizations, stop_payment_order, transaction_not_allowed
Autenticazione	authentication_required
Rischio	fraudulent, highest_risk_level

Tieni il codice grezzo nei tuoi dati così puoi raggruppare di nuovo in seguito. Stripe aggiunge e depreca codici nel tempo; il riferimento di Stripe ora segna alcuni codici più vecchi come deprecati a favore degli advice code.

Testare la gestione dei rifiuti

Stripe fornisce numeri di carta di test che generano decline code specifici. Prima di andare live con qualsiasi logica di recupero, fai passare ogni gruppo in modalità test:

• Un soft decline programma un nuovo tentativo e invia la prima email.
• Un hard decline invia un’email «serve una nuova carta» e non ritenta la stessa carta.
• authentication_required invia un link di conferma.
• lost_card e stolen_card producono un messaggio generico.
• Un pagamento riuscito (invoice.paid) ferma tutte le email e i nuovi tentativi.
• Ogni tentativo viene registrato con i suoi codici.

Errori comuni

• Trattare ogni rifiuto allo stesso modo. Ritentare otto volte una carta rubata non recupera nulla e può pesare contro di te con il circuito.
• Dire al cliente il motivo grezzo. «Do not honor» non significa nulla per i clienti, e alcuni motivi non vanno proprio comunicati.
• Ignorare gli advice code. Esistono proprio per dirti se ritentare.
• Leggere solo il primo fallimento. Il codice può cambiare tra un tentativo e l’altro; una carta può passare da insufficient_funds a expired_card in una lunga finestra di nuovi tentativi.
• Nessuna via d’uscita per gli hard decline. Se l’unica strada per il recupero è un nuovo tentativo, gli hard decline sono persi per costruzione.

Per il quadro completo del recupero dei pagamenti falliti, dai nuovi tentativi alle email alla misurazione, vedi come recuperare i pagamenti falliti su Stripe.

Come aiuta NoChurn

NoChurn legge il decline code di ogni rinnovo fallito e gestisce ogni gruppo in modo diverso. I soft decline vengono ritentati in momenti basati sui probabili giorni di paga e sull’ora locale del cliente (oppure tieni gli Smart Retries di Stripe). Gli hard decline e le richieste di autenticazione saltano i nuovi tentativi inutili e passano subito a un’email di recupero scritta dall’IA, controllata prima dell’invio, con un link a una pagina hosted di aggiornamento della carta. I motivi sensibili non vengono mai mostrati al cliente, e ogni decisione viene registrata con il suo codice.

Si collega a Stripe in un clic, e il prezzo dipende solo dall’MRR, senza alcuna quota dei ricavi recuperati. Vedi pagamenti falliti e prezzi.