> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errori di Transazione
> Comprendi ogni codice di errore di transazione di Dodo Payments, se si tratta di un rifiuto temporaneo (soft) o definitivo (hard), e l'azione consigliata per recuperare il pagamento.
## Panoramica
Dodo Payments restituisce un motivo dettagliato di fallimento ogni volta che un tentativo di pagamento non ha successo. Questi motivi sono standardizzati tra i vari metodi di pagamento e fornitori, così puoi implementare una gestione coerente nella tua applicazione.
Quando un pagamento fallisce, il webhook `payment.failed` e l'oggetto di pagamento espongono:
* `error_code` — un motivo di fallimento standardizzato dalla tabella sottostante.
* `error_message` — una spiegazione comprensibile.
* `retry_attempt` — `0` per l'addebito originale, `1` o superiore per ogni tentativo di rinnovo abbonamento programmato.
Comprendere questi motivi di fallimento ti consente di fornire un feedback chiaro ai clienti, decidere se vale la pena riprovare e recuperare più entrate.
Una guida passo-passo per gli sviluppatori per leggere questi codici dai webhook e dall'API, mostrarli ai clienti e decidere quando riprovare.
## Rifiuti Soft vs. Rifiuti Hard
Ogni codice di fallimento rientra in una delle due categorie. Questa distinzione determina se dovresti riprovare con lo stesso metodo di pagamento o chiedere al cliente un nuovo metodo.
| Tipo di rifiuto | Cosa significa | Cosa fare | Esempi |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rifiuto soft** | Temporaneo o correggibile — la stessa carta può avere successo in un tentativo successivo o se il cliente corregge il suo input. | Sicuro da riprovare (dopo un ritardo, o una volta che il cliente corregge i suoi dettagli). | `INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER` |
| **Rifiuto hard** | Terminale — riprovare con la stessa carta non cambierà il risultato. | Non riprovare la stessa carta. Chiedi al cliente di utilizzare un altro metodo di pagamento o contattare la sua banca. | `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT` |
Per i rinnovi di abbonamento, Dodo Payments applica automaticamente questa distinzione: i rifiuti soft vengono ri-tentati da [Ripetizioni Pagamento Abbonamento](/features/recovery/payment-retries), mentre i rifiuti hard terminano immediatamente la catena di rifiuti e vengono gestiti al meglio con [Gestione dei Solleciti di Abbonamento](/features/recovery/subscription-dunning).
**Non rivelare mai al cliente il vero motivo per `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD` o `FRAUDULENT`.** Mostrare questi motivi può avvisare un attore fraudolento. Mostrare sempre al cliente un messaggio di rifiuto generico (ad esempio, \*"La tua carta è stata rifiutata. Si prega di contattare la banca o utilizzare un'altra carta.") e registrare solo internamente il codice specifico.
## Motivi di Fallimento delle Transazioni
La seguente tabella elenca ogni codice di fallimento, il tipo di rifiuto, se il cliente può risolverlo, una descrizione e l'azione consigliata.
| Codice di Fallimento | Tipo | Errore Utente | Descrizione | Azione Consigliata |
| ---------------------------------- | ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `AUTHENTICATION_FAILURE` | Soft | Sì | L'autenticazione non è riuscita durante la transazione | Chiedi al cliente di riprovare e completare l'autenticazione 3DS, o utilizzare un'altra carta |
| `AUTHENTICATION_REQUIRED` | Soft | Sì | È necessaria un'ulteriore autenticazione per completare la transazione | Sollecita il cliente a completare l'autenticazione 3DS. Per i rinnovi di abbonamento, chiedi al cliente di tornare e autenticarsi |
| `AUTHENTICATION_TIMEOUT` | Soft | Sì | Il processo di autenticazione è scaduto | Chiedi al cliente di riprovare e completare prontamente l'autenticazione |
| `CARD_DECLINED` | Soft | No | La carta è stata rifiutata dalla banca emittente senza un motivo specifico (rifiuto generico) | Chiedi al cliente di riprovare, contattare la banca, o utilizzare un'altra carta |
| `CARD_NOT_ACTIVATED` | Soft | Sì | La carta non è stata attivata dal titolare della carta | Chiedi al cliente di attivare la carta con la sua banca, poi riprovare |
| `CARD_VELOCITY_EXCEEDED` | Soft | Sì | Troppi tentativi di transazioni in un breve periodo | Chiedi al cliente di attendere e riprovare più tardi, o contattare la banca riguardo ai limiti |
| `CUSTOMER_CANCELLED` | Soft | Sì | Il cliente ha annullato la transazione | Consenti al cliente di ricominciare il checkout quando è pronto |
| `DO_NOT_HONOR` | Hard | No | La banca emittente ha rifiutato esplicitamente la transazione (codice ISO 8583 05 — non onorare); le reti lo trattano come terminale | Chiedi al cliente di contattare la sua banca; non riprovare la stessa carta |
| `EXPIRED_CARD` | Hard | Sì | La carta è scaduta | Chiedi al cliente di utilizzare una carta con una data di scadenza valida |
| `FRAUDULENT` | Hard | Sì | La transazione è stata segnalata come potenzialmente fraudolenta | Mostra al cliente un messaggio di rifiuto generico — non rivelare il motivo. Chiedi loro di utilizzare un'altra carta |
| `GENERIC_DECLINE` | Soft | No | La transazione è stata rifiutata per un motivo non specificato | Chiedi al cliente di contattare la sua banca o provare un'altra carta |
| `INCORRECT_CVC` | Soft | Sì | Il codice CVC fornito era errato | Chiedi al cliente di inserire nuovamente il CVC corretto |
| `INCORRECT_NUMBER` | Soft | Sì | Il numero della carta è stato inserito in modo errato | Chiedi al cliente di inserire nuovamente il numero corretto della carta |
| `INSUFFICIENT_FUNDS` | Soft | Sì | Il conto non ha fondi sufficienti per completare la transazione | Chiedi al cliente di utilizzare un altro metodo di pagamento o riprovare una volta che i fondi sono disponibili |
| `INVALID_ACCOUNT` | Hard | Sì | I dettagli del conto forniti sono non validi | Chiedi al cliente di contattare la banca o utilizzare un'altra carta |
| `INVALID_AMOUNT` | Soft | Sì | L'importo della transazione non è valido | Verifica l'importo e eventuali limiti di acquisto con il cliente |
| `INVALID_CARD_NUMBER` | Soft | Sì | Il formato del numero di carta è non valido | Chiedi al cliente di inserire nuovamente un numero di carta valido |
| `INVALID_CARD_OWNER` | Soft | Sì | Le informazioni del titolare della carta non sono valide | Chiedi al cliente di correggere il nome del titolare della carta |
| `INVALID_CVC` | Soft | Sì | Il formato del CVC è non valido | Chiedi al cliente di inserire nuovamente un CVC valido |
| `INVALID_EXPIRY_YEAR` | Soft | Sì | L'anno di scadenza della carta è non valido | Chiedi al cliente di inserire una data di scadenza valida |
| `INVALID_PIN` | Soft | Sì | Il PIN fornito è errato | Chiedi al cliente di inserire nuovamente il PIN corretto |
| `INVALID_REQUEST` | Soft | Sì | La richiesta di transazione contiene dati non validi | Controlla i campi della richiesta di pagamento e invia nuovamente con dati validi |
| `INVALID_UPI_ID` | Soft | Sì | L'ID UPI fornito è non valido | Chiedi al cliente di inserire un ID UPI valido |
| `LIMIT_EXCEEDED` | Soft | Sì | La transazione supera il limite della carta o del conto | Chiedi al cliente di contattare la banca riguardo ai limiti, o utilizzare un altro metodo |
| `LIVE_MODE_TEST_CARD` | Hard | Sì | È stata usata una carta di test in modalità live | Usa una carta reale — riprovare la carta di test fallirà sempre in modalità live |
| `LOST_CARD` | Hard | Sì | La carta è stata segnalata come persa | Mostra al cliente un messaggio di rifiuto generico — non rivelare il motivo. Chiedi loro di utilizzare un'altra carta |
| `MANDATE_INVALID` | Soft | Sì | Il mandato di pagamento è non valido | Chiedi al cliente di configurare nuovamente il mandato di pagamento |
| `MANDATE_REQUIRED` | Soft | Sì | È richiesto un mandato per questa transazione | Configura un mandato e chiedi al cliente di autorizzarlo prima dell'addebito |
| `MANDATE_REQUIRED_SYSTEM` | Hard | No | Il sistema richiede un mandato per questo tipo di transazione | Assicurati che il flusso di configurazione del mandato sia completato prima dell'addebito |
| `NETWORK_ERROR` | Soft | No | Si è verificato un errore di rete durante la transazione | Transitorio — riprovare il pagamento dopo un breve ritardo |
| `NETWORK_TIMEOUT` | Soft | No | La richiesta di rete è scaduta | Transitorio — riprovare il pagamento dopo un breve ritardo |
| `ORDER_ALREADY_EXISTS` | Soft | No | Un ordine esiste già per questa transazione (creazione ordine duplicata) | Verifica lo stato dell'ordine esistente prima di riprovare; contatta il supporto se persiste |
| `ORDER_CREATION_FAILED` | Soft | No | Impossibile creare l'ordine per la transazione | Errore transitorio/sistema — riprovare il pagamento; contatta il supporto se persiste |
| `PAYMENT_METHOD_PROVIDER_DECLINED` | Hard | Sì | Il fornitore del metodo di pagamento ha rifiutato la transazione | Chiedi al cliente di contattare il fornitore o utilizzare un altro metodo di pagamento |
| `PAYMENT_METHOD_UNSUPPORTED` | Hard | Sì | Il metodo di pagamento non è supportato per questa transazione | Chiedi al cliente di utilizzare un metodo di pagamento supportato |
| `PICKUP_CARD` | Hard | Sì | La carta è stata segnalata come persa o rubata e contrassegnata per il ritiro | Mostra al cliente un messaggio di rifiuto generico — non rivelare il motivo. Chiedi loro di utilizzare un'altra carta |
| `PROCESSING_ERROR` | Soft | No | Si è verificato un errore durante l'elaborazione della transazione | Transitorio — riprovare il pagamento; se persiste, chiedi al cliente di contattare la banca |
| `PROVIDER_UNSUPPORTED` | Hard | No | Il fornitore di pagamento non supporta questo tipo di transazione | Chiedi al cliente di utilizzare un altro metodo di pagamento |
| `REENTER_TRANSACTION` | Soft | Sì | È necessario reinserire la transazione | Chiedi al cliente di riprovare il pagamento |
| `REVOCATION_OF_AUTHORIZATION` | Hard | Sì | L'autorizzazione per la transazione è stata revocata | Chiedi al cliente di utilizzare un altro metodo di pagamento |
| `STOLEN_CARD` | Hard | Sì | La carta è stata segnalata come rubata | Mostra al cliente un messaggio di rifiuto generico — non rivelare il motivo. Chiedi loro di utilizzare un'altra carta |
| `SUBSCRIPTION_NOT_ACTIVE` | Hard | No | L'abbonamento non è attivo, quindi l'addebito ricorrente non è stato possibile | Riattiva l'abbonamento (ad esempio, aggiornando il metodo di pagamento) prima di tentare nuovamente l'addebito |
| `TRANSACTION_NOT_ALLOWED` | Hard | Sì | La transazione non è consentita per questa carta o conto | Chiedi al cliente di contattare la sua banca per consentire questo tipo di transazione, o utilizzare un'altra carta |
| `TRANSACTION_NOT_APPROVED` | Hard | Sì | La transazione non è stata approvata | Chiedi al cliente di contattare la sua banca o provare un'altra carta |
| `TRY_AGAIN_LATER` | Soft | No | La transazione dovrebbe essere ritentata più tardi | Transitorio — riprovare il pagamento più tardi |
| `UNKNOWN_ERROR` | Soft | No | Si è verificato un errore sconosciuto | Riprovare il pagamento; se persiste, contatta il supporto |
**Errore Utente** indica se il rifiuto del pagamento può essere risolto dal cliente. Quando `Yes`, il cliente può agire per risolvere il problema (ad esempio, inserire i dettagli della carta corretti). Quando `No`, il rifiuto è dovuto a problemi a livello di sistema o restrizioni bancarie che il cliente non può risolvere direttamente.
Una carta può anche essere rifiutata quando il motore di rischio della banca emittente segnala il titolare come un cliente ad alto rischio — indipendentemente dal commerciante o dai dettagli della transazione. Questi rifiuti appaiono tipicamente come codici generici come `DO_NOT_HONOR`, `GENERIC_DECLINE`, `CARD_DECLINED`, `TRANSACTION_NOT_APPROVED` o `FRAUDULENT`. In questi casi, la banca non comunica la ragione specifica e né Dodo Payments né il commerciante possono annullare la decisione. Chiedi al cliente di contattare la sua banca per risolvere la segnalazione o di utilizzare un'altra carta o metodo di pagamento.
## Gestire i fallimenti programmaticamente
Leggi `error_code` dal webhook `payment.failed` o dall'oggetto di pagamento, mappalo all'azione consigliata sopra e decidi se riprovare. Per i rinnovi degli abbonamenti, i rifiuti "soft" vengono riprovati automaticamente — vedi [Riprova Pagamenti Abbonamento](/features/recovery/payment-retries).
Per gli errori a livello API e logica di business (come `PAYMENT_NOT_SUCCEEDED` o `REFUND_WINDOW_EXPIRED`) che non sono rifiuti di carta, vedi il riferimento su [Codici Errore](/api-reference/error-codes).
## Correlati
Guida completa alla rilevazione, emersione e riprova dei pagamenti falliti.
Codici d'errore API e logica di business per i fallimenti non di rifiuto.
Riprovi automatici che recuperano i fallimenti "soft" nei rinnovi degli abbonamenti.
Sequenze di email che recuperano rifiuti duri invitando un aggiornamento del metodo di pagamento.
## Supporto
Per ulteriore aiuto con i fallimenti delle transazioni o problemi di integrazione, ti preghiamo di contattare il nostro team di supporto a [support@dodopayments.com](mailto:support@dodopayments.com).