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 webhookpayment.failed e l’oggetto di pagamento espongono:
error_code— un motivo di fallimento standardizzato dalla tabella sottostante.error_message— una spiegazione comprensibile.retry_attempt—0per l’addebito originale,1o superiore per ogni tentativo di rinnovo abbonamento programmato.
Handle Payment Failures
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 |
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.Gestione dei Fallimenti in Modo Programmatico
Leggierror_code dal webhook payment.failed o dall’oggetto di pagamento, mappalo con l’azione consigliata sopra, e decidi se riprovare. Per i rinnovi di abbonamento, i rifiuti soft sono riprovati automaticamente per te — vedi Ripetizioni Pagamento Abbonamento.
Per errori a livello di API e di logica aziendale (come PAYMENT_NOT_SUCCEEDED o REFUND_WINDOW_EXPIRED) che non sono rifiuti di carta, vedi il riferimento Error Codes.
Correlati
Handle Payment Failures
Guida completa per rilevare, mostrare e riprovare i pagamenti falliti.
Error Codes
Codici di errore di API e logica aziendale per fallimenti non di rifiuto.
Subscription Payment Retries
Ripetizioni automatiche che recuperano i rifiuti soft sui rinnovi di abbonamento.
Subscription Dunning
Sequenze email che recuperano i rifiuti hard sollecitando un aggiornamento del metodo di pagamento.