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 standardizzato del fallimento dalla tabella seguente.error_message— una spiegazione comprensibile scritta per te, il merchant. Quandoerror_codeè uno dei codici standardizzati riportati di seguito, si tratta di un titolo seguito dall’azione consigliata, anziché del testo grezzo restituito dal processore dei pagamenti.retry_attempt—0per l’addebito originale,1o superiore per ogni nuovo tentativo programmato di rinnovo dell’abbonamento.
Testo per il merchant vs. testo per il cliente
Ogni codice di fallimento standardizzato corrisponde a due messaggi diversi, così il pubblico appropriato visualizza il livello di dettaglio corretto:Il Customer Portal restituisce il testo destinato al cliente in
error_message, mentre l’API del merchant restituisce il testo destinato al merchant per lo stesso pagamento. error_code è identico in entrambi.Handle Payment Failures
Una guida per sviluppatori, passo dopo passo, su come leggere questi codici dai webhook e dall’API, mostrarli ai clienti e decidere quando riprovare.
Rifiuti temporanei e definitivi
Ogni codice di fallimento rientra in una delle due categorie. Questa distinzione determina se riprovare con lo stesso metodo di pagamento o chiedere al cliente di utilizzarne uno nuovo.
Per i rinnovi degli abbonamenti, Dodo Payments applica automaticamente questa distinzione: i rifiuti temporanei vengono ritentati da Subscription Payment Retries, mentre i rifiuti definitivi interrompono immediatamente la sequenza di nuovi tentativi e vengono gestiti al meglio con Subscription Dunning.
Motivi del fallimento della transazione
La tabella seguente elenca ogni codice di fallimento, il relativo tipo di rifiuto, la possibilità per il cliente di risolverlo, una descrizione e l’azione consigliata.Errore dell’utente indica se il rifiuto del pagamento può essere risolto dal cliente. Quando
Yes, il cliente può agire per risolvere il problema (ad esempio, inserendo correttamente i dati della carta). Quando No, il rifiuto è dovuto a problemi a livello di sistema o a restrizioni della banca che il cliente non può risolvere direttamente.Una carta può essere rifiutata anche quando il motore di valutazione del rischio della banca emittente identifica il titolare come cliente ad alto rischio, indipendentemente dal merchant o dai dettagli della transazione. Questi rifiuti vengono generalmente restituiti come codici generici quali
DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED o FRAUDULENT. In questi casi la banca non condivide il motivo specifico e né Dodo Payments né il merchant possono annullare la decisione. Chiedi al cliente di contattare la propria banca per risolvere il problema oppure di utilizzare una carta o un metodo di pagamento diverso.Gestione programmatica dei fallimenti
Leggierror_code dal webhook payment.failed o dall’oggetto payment, assoc ialo all’azione consigliata sopra e decidi se riprovare. Per i rinnovi degli abbonamenti, i rifiuti temporanei vengono ritentati automaticamente per te — consulta Subscription Payment Retries.
Per gli errori a livello di API e di logica aziendale (come PAYMENT_NOT_SUCCEEDED o REFUND_WINDOW_EXPIRED) che non sono rifiuti della carta, consulta il riferimento Error Codes.
Correlati
Handle Payment Failures
Guida end-to-end per rilevare, mostrare e ritentare i pagamenti non riusciti.
Error Codes
Codici di errore dell’API e della logica aziendale per i fallimenti che non sono rifiuti.
Subscription Payment Retries
Nuovi tentativi automatici che recuperano i rifiuti temporanei sui rinnovi degli abbonamenti.
Subscription Dunning
Sequenze di email che recuperano i rifiuti definitivi chiedendo di aggiornare il metodo di pagamento.