Panoramica
Quando un tentativo di pagamento non va a buon fine, Dodo Payments restituisce un codice di errore standardizzato che ne indica il motivo. I codici sono gli stessi per tutti i metodi di pagamento e i processori di pagamento, quindi un unico insieme di regole di gestione copre tutti i pagamenti non riusciti. Il webhookpayment.failed e l’oggetto payment espongono questi campi per un pagamento non riuscito:
error_code: un codice di errore standardizzato dalla tabella seguente.error_message: una spiegazione scritta per te, il merchant. Quandoerror_codeè uno dei codici standardizzati riportati di seguito, si tratta di un titolo seguito dall’azione consigliata, non del testo grezzo restituito dal processore di pagamento.retry_attempt:0per l’addebito originale e1o un valore superiore per ogni nuovo tentativo di rinnovo programmato dell’abbonamento. I pagamenti che non sono rinnovi di abbonamenti mantengono il valore0.
Testo per il merchant vs. testo per il cliente
Ogni codice di errore standardizzato corrisponde a due messaggi, uno per te e uno per il tuo cliente: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 è uguale in entrambi i casi.Handle Payment Failures
Una guida per sviluppatori passo passo che spiega come leggere questi codici dai webhook e dall’API, mostrarli ai clienti e decidere quando riprovare.
Rifiuti temporanei e definitivi
Ogni codice di errore è un rifiuto temporaneo o definitivo. Il tipo indica se un tentativo successivo con gli stessi dati di pagamento può riuscire o se il cliente deve prima intervenire.
Per i rinnovi degli abbonamenti, Dodo Payments applica automaticamente questa classificazione. Subscription Payment Retries riprova i rifiuti temporanei. Un rifiuto definitivo interrompe immediatamente la catena di tentativi; recuperalo con Subscription Dunning.
Motivi del fallimento della transazione
La tabella seguente elenca tutti i codici di errore con il relativo tipo di rifiuto, indica se il cliente può risolvere il problema, fornisce una descrizione e l’azione consigliata.User Error indica se il cliente può risolvere il rifiuto.
Yes indica che il cliente può risolvere il problema, ad esempio inserendo correttamente i dati della carta. No indica che il rifiuto è stato causato da un problema a livello di sistema o da una restrizione della banca e che il cliente non può risolverlo direttamente.Una banca emittente può anche rifiutare una carta perché il proprio motore di rischio segnala il titolare della carta come ad alto rischio, indipendentemente dall’esercente o dai dettagli della transazione. Questi rifiuti vengono solitamente visualizzati come codici generici quali
DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED o FRAUDULENT. La banca non comunica il motivo specifico e né Dodo Payments né l’esercente possono ignorare la decisione. Chiedi al cliente di contattare la propria banca per risolvere il problema o 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 nella tabella e decidi se riprovare. Per i rinnovi degli abbonamenti, Dodo Payments riprova per te i rifiuti temporanei. Consulta Subscription Payment Retries.
Per gli errori dell’API e della logica aziendale che non sono rifiuti della carta, come PAYMENT_NOT_SUCCEEDED o REFUND_WINDOW_EXPIRED, 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.