Gestione dei Fallimenti di Pagamento

Quando un payment fallisce, Dodo Payments fornisce un error_code standardizzato e un error_message leggibile. Questa guida mostra come leggere questi campi, decidere se ritentare e recuperare il payment in sicurezza.

Come Dodo Payments Riporta un Fallimento

Ogni payment fallito contiene questi campi nell’oggetto payment:

Campo	Tipo	Descrizione
`status`	string	`failed` per un payment fallito. Altri stati diversi da success: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Motivo standardizzato del fallimento, ad esempio `INSUFFICIENT_FUNDS` o `PROCESSING_ERROR`. Consulta Transaction Failures per l’elenco completo.
`error_message`	string \| null	Spiegazione rivolta al merchant con l’azione consigliata. Non destinata ai clienti.
`retry_attempt`	integer	`0` per l’addebito originale. `1` o superiore per i retry programmati del rinnovo di una subscription.

error_code e error_message sono null finché un payment non fallisce. Controlla sempre prima status.

error_message è rivolto al merchant e può rivelare motivi legati alla frode. Non mostrarlo mai ai clienti. Associa invece error_code a un testo sicuro per il cliente (consulta Surface Errors to Customers Safely).

Il webhook `payment.failed`

Il webhook payment.failed è il metodo più affidabile per rilevare un fallimento. L’evento include l’intero oggetto payment 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 instrada 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 payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      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 payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            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 decline	Esempi	Azione
Soft decline	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Ritenta dopo un intervallo o quando il cliente corregge i dati inseriti.
Hard decline	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Non ritentare con la stessa carta. Chiedi al cliente un metodo di pagamento diverso.

Consulta Transaction Failures per l’elenco completo dei tipi di decline e delle azioni consigliate.

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 completando attivamente il checkout. Mostra un messaggio chiaro e consentigli di ritentare o usare un’altra carta.

requires_payment_method — il cliente non ha mai fornito un metodo di pagamento. Di solito si tratta di un abbandono del checkout, non di un decline. Ricontatta il cliente per completare il payment (consulta Abandoned Cart Recovery).
requires_customer_action — è necessaria un’autenticazione aggiuntiva (ad esempio 3DS). Chiedi al cliente di completarla. Consulta 3D Secure.

Il cliente non è presente. Quando un rinnovo fallisce, la subscription passa a on_hold e viene attivato subscription.on_hold. Se la tua attività prevede un periodo di tolleranza, passa prima a past_due (subscription.past_due) e mantiene l’accesso fino al termine del periodo di tolleranza.

I soft decline vengono ritentati automaticamente se attivi Subscription Payment Retries (disattivato per impostazione predefinita). I retry riguardano solo i rinnovi programmati, non gli addebiti on-demand.
Gli hard decline (e i retry esauriti) sui rinnovi programmati vengono recuperati con Subscription Dunning, che invia un’email al cliente per aggiornare il metodo di pagamento. Per i fallimenti degli addebiti on-demand, consulta On-Demand Subscriptions.

Consulta Subscription Integration Guide per il flusso completo da on-hold a reactivate.

Riprovare un pagamento non riuscito

Subscriptions: attiva Subscription Payment Retries per recuperare automaticamente i soft decline. Per ritentare immediatamente invece di attendere la pianificazione, usa Manual Payment Retry dalla dashboard o dall’API. Puoi anche attivare il recupero chiedendo al cliente di aggiornare il metodo di pagamento tramite Update Payment Method API, che addebita eventuali importi dovuti. One-time payments: invia nuovamente il checkout o payment_link affinché il cliente possa riprovare con un metodo diverso. Non esiste un retry automatico per i pagamenti una tantum.

Non ritentare gli hard decline sulla stessa carta. I circuiti delle carte contrassegnano i decline ripetuti come abusivi, danneggiando il tuo tasso di autorizzazione.

Mostrare gli errori ai clienti in sicurezza

Mostra ai clienti un messaggio chiaro e amichevole, mai il valore grezzo di error_code o di error_message rivolto al merchant.

Sulle superfici gestite da Dodo Payments (checkout, Customer Portal, email di dunning), questa associazione è già configurata per te, incluso il fallback a un messaggio generico per i decline legati alla frode. Ti serve l’associazione 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. Mostrarlo può informare un attore fraudolento. Mostra un messaggio generico di decline e registra internamente solo il valore specifico di error_code.

Correlati

Transaction Failures

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

Error Codes

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

Subscription Payment Retries

Recupero automatico dei soft decline sui rinnovi delle subscription.

Subscription Dunning

Sequenze di email che recuperano gli hard decline.

Payment Webhooks

Schema completo del payload per gli eventi di payment.

Testing Failures

Carte di test che simulano decline 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 sicurezza

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 sicurezza

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

Correlati