Vai al contenuto principale

​
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.

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. Per i rinnovi di abbonamento, Dodo Payments applica automaticamente questa distinzione: i rifiuti soft vengono ri-tentati da Ripetizioni Pagamento Abbonamento, mentre i rifiuti hard terminano immediatamente la catena di rifiuti e vengono gestiti al meglio con Gestione dei Solleciti di Abbonamento.
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.
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. 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.

​
Correlati

Handle Payment Failures

Guida completa alla rilevazione, emersione e riprova dei pagamenti falliti.

Error Codes

Codici d’errore API e logica di business per i fallimenti non di rifiuto.

Subscription Payment Retries

Riprovi automatici che recuperano i fallimenti “soft” nei rinnovi degli abbonamenti.

Subscription Dunning

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.
Ultima modifica il 26 giugno 2026