Gestione dei Fallimenti di Pagamento

Quando un pagamento fallisce, Dodo Payments ti comunica perché attraverso un error_code standardizzato e un error_message leggibile. Questa guida mostra come leggere quei campi, decidere se vale la pena riprovare e recuperare il pagamento senza esporre informazioni sensibili ai clienti.

Come Dodo Payments Riporta un Fallimento

Ogni pagamento fallito — sia un checkout una tantum che un rinnovo di abbonamento — porta gli stessi campi di fallimento sull’oggetto di pagamento:

Campo	Tipo	Descrizione
`status`	string	`failed` per un pagamento non riuscito. Altri stati non riusciti includono `cancelled`, `requires_customer_action` e `requires_payment_method`.
`error_code`	string \| null	Il motivo standardizzato del fallimento, ad esempio `INSUFFICIENT_FUNDS` o `PROCESSING_ERROR`. Consulta il riferimento Transaction Failures per l’elenco completo.
`error_message`	string \| null	Una spiegazione leggibile del fallimento, scritta per te e non per il cliente. Per un `error_code` standardizzato, si tratta di un titolo seguito dall’azione consigliata, non del testo grezzo del processore.
`retry_attempt`	integer	`0` per l’addebito originale. `1` o un valore superiore identifica un tentativo di rinnovo programmato di un abbonamento.

error_code e error_message sono null finché un pagamento non fallisce effettivamente. Controlla sempre prima status, poi leggi i campi di errore.

error_message proveniente dall’API merchant è un testo rivolto al merchant. Può indicare il motivo reale di un rifiuto, inclusi quelli correlati alle frodi, quindi non mostrarlo mai direttamente al cliente. Mappa invece error_code su un testo sicuro per il cliente, come illustrato in Mostrare gli errori ai clienti in modo sicuro.

Il webhook `payment.failed`

Il modo più affidabile per rilevare un fallimento è il webhook payment.failed. L’evento include l’intero oggetto del pagamento in data:

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

Un handler minimale legge error_code e applica il routing in base a tale valore:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription renewal — Dodo retries soft declines for you
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription renewal — Dodo retries soft declines for you
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

Verifica sempre la firma del webhook prima di elaborarlo. Consulta la guida sui webhook per la configurazione completa, inclusa la verifica della firma e l’idempotenza.

Decidere se riprovare: rifiuti soft e hard

error_code indica se vale la pena riprovare con lo stesso metodo di pagamento.

Tipo di rifiuto	Significato	Cosa fare
Rifiuto soft	Temporaneo o risolvibile (ad esempio `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Un nuovo tentativo — dopo un intervallo o dopo che il cliente ha corretto i dati inseriti — può riuscire.
Rifiuto hard	Definitivo (ad esempio `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Non riprovare con la stessa carta. Chiedi al cliente di usare un metodo di pagamento diverso.

Il riferimento Transaction Failures elenca il tipo di rifiuto e l’azione consigliata per ogni error_code.

Gestire i fallimenti al checkout e durante il rinnovo

Il modo in cui recuperi il pagamento dipende dalla presenza o meno del cliente.

At checkout (customer present)
On subscription renewal (customer not present)

Il cliente sta effettuando attivamente il checkout. Mostra un messaggio chiaro e consenti di riprovare immediatamente o di usare un’altra carta.

requires_payment_method — il cliente non ha mai fornito un metodo di pagamento: non ha inserito i dati della carta oppure gli è stato richiesto di inserirli ma non ha eseguito alcuna azione. Di solito si tratta di un abbandono del checkout, non di un rifiuto: coinvolgi nuovamente il cliente per completare il pagamento (consulta Recupero dei carrelli abbandonati).
requires_customer_action — è necessaria un’autenticazione aggiuntiva (ad esempio 3DS); chiedi al cliente di completarla. Consulta Gestione di 3D Secure.

Il cliente non è presente, quindi non puoi chiedergli di intervenire in tempo reale. Quando un rinnovo non riesce, l’abbonamento passa a on_hold e viene attivato subscription.on_hold.

I rifiuti soft vengono sottoposti automaticamente a un nuovo tentativo da Subscription Payment Retries.
I rifiuti hard (e i tentativi esauriti) si recuperano al meglio con Subscription Dunning, che invia un’e-mail al cliente chiedendogli di aggiornare il metodo di pagamento.

Consulta la guida all’integrazione degli abbonamenti per il flusso completo di sospensione → riattivazione.

Riprovare un pagamento non riuscito

Abbonamenti: abilita Subscription Payment Retries per recuperare i rifiuti soft senza interventi di integrazione. Puoi anche attivare il recupero chiedendo al cliente di aggiornare il metodo di pagamento tramite l’API Update Payment Method, che addebita gli importi ancora dovuti.
Pagamenti una tantum: invia nuovamente il checkout o payment_link affinché il cliente possa riprovare con un metodo diverso. Non è previsto alcun nuovo tentativo automatico per i pagamenti una tantum.

Non riprovare i rifiuti hard con la stessa carta. I circuiti delle carte possono segnalare i rifiuti ripetuti come attività abusiva, danneggiando il tuo tasso di autorizzazione.

Mostrare gli errori ai clienti in modo sicuro

Mostra ai clienti un messaggio chiaro e cordiale — mai il valore grezzo di error_code e mai error_message, che è rivolto al merchant.

Nelle superfici gestite da Dodo Payments — checkout, Customer Portal ed e-mail di dunning — questa mappatura è già effettuata per te, incluso il fallback a un messaggio generico per i rifiuti correlati alle frodi. Ti serve la mappatura seguente solo quando mostri i fallimenti nel tuo prodotto.

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

Non rivelare mai il motivo reale di STOLEN_CARD, LOST_CARD, PICKUP_CARD o FRAUDULENT. Mostrarli può fornire informazioni utili a un autore di frodi. Mostra un messaggio generico di rifiuto e registra internamente solo il valore specifico di error_code.

Correlati

Transaction Failures

Ogni codice di rifiuto, il relativo tipo e l’azione consigliata.

Error Codes

Errori dell’API e della logica di business che non sono rifiuti della carta.

Subscription Payment Retries

Recupero automatico dei rifiuti soft durante i rinnovi degli abbonamenti.

Subscription Dunning

Sequenze di e-mail che recuperano i rifiuti hard.

Payment Webhooks

Schema completo del payload per gli eventi di pagamento.

Testing Failures

Carte di test che simulano rifiuti e fallimenti dei rinnovi.

Integration Guides

Billing Deconstructions

Cookbooks

Come Dodo Payments Riporta un Fallimento

Il webhook `payment.failed`

Decidere se riprovare: rifiuti soft e hard

Gestire i fallimenti al checkout e durante il rinnovo

Riprovare un pagamento non riuscito

Mostrare gli errori ai clienti in modo sicuro

Correlati

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Come Dodo Payments Riporta un Fallimento

​Il webhook payment.failed

​Decidere se riprovare: rifiuti soft e hard

​Gestire i fallimenti al checkout e durante il rinnovo

​Riprovare un pagamento non riuscito

​Mostrare gli errori ai clienti in modo sicuro

​Correlati

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Come Dodo Payments Riporta un Fallimento

Il webhook `payment.failed`

Decidere se riprovare: rifiuti soft e hard

Gestire i fallimenti al checkout e durante il rinnovo

Riprovare un pagamento non riuscito

Mostrare gli errori ai clienti in modo sicuro

Correlati