Gestione dei Fallimenti di Pagamento - Dodo Payments Documentation

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 fallito. Altri stati non di successo includono `cancelled`, `requires_customer_action`, e `requires_payment_method`.
`error_code`	string \| null	Il motivo standardizzato del fallimento, per esempio `INSUFFICIENT_FUNDS` o `PROCESSING_ERROR`. Vedi il riferimento Transaction Failures per la lista completa.
`error_message`	string \| null	Una spiegazione leggibile del fallimento.
`retry_attempt`	integer	`0` per l’addebito originale. `1` o superiore identifica un tentativo di rinnovo abbonamento programmato.

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

Il Webhook `payment.failed`

Il modo più affidabile per rilevare un fallimento è il webhook payment.failed. L’evento avvolge l’intero oggetto di 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 gestore minimale legge error_code e instrada su di esso:

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. Vedi la guida Webhooks per l’intero setup, compresa la verifica della firma e l’idempotenza.

Decidi se Riprovare: Declini Soft vs. Hard

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

Tipo di declino	Cosa significa	Cosa fare
Declino soft	Temporaneo o correggibile (per esempio `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Riprovare, dopo un ritardo o una volta che il cliente ha corretto il proprio input, può avere successo.
Declino hard	Terminale (per esempio `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Non riprovare con lo stesso carta. Chiedi al cliente un diverso metodo di pagamento.

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

Gestire i Fallimenti al Checkout vs. al Rinnovo

Come si recupera dipende dal fatto che il cliente sia presente.

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

Il cliente sta effettuando attivamente il checkout. Mostra un messaggio chiaro e lascia che riprovino immediatamente o utilizzino un’altra carta.

requires_payment_method — il cliente non ha mai fornito un metodo di pagamento: non ha inserito i dettagli della carta o è stato richiesto di farlo e non ha agito. Questo è di solito un abbandono del checkout, non un rifiuto: re-ingaggia il cliente per completare il pagamento (vedi Abandoned Cart Recovery).
requires_customer_action — è necessaria un’autenticazione aggiuntiva (come 3DS); fai completare al cliente. Vedi gestione 3D Secure.

Il cliente non è presente, quindi non puoi sollecitarlo in tempo reale. Quando un rinnovo fallisce, l’abbonamento passa a on_hold e subscription.on_hold si attiva.

Declini soft sono ritentati automaticamente da Subscription Payment Retries.
Declini hard (e riprove esaurite) sono meglio recuperati con Subscription Dunning, che invia un’email al cliente per aggiornare il proprio metodo di pagamento.

Vedi la Guida all’Integrazione degli Abbonamenti per il flusso completo da sospeso → riattivato.

Riprovare un Pagamento Fallito

Abbonamenti: Abilita Subscription Payment Retries per recuperare declini soft senza lavoro di integrazione. Puoi anche innescare il recupero facendo aggiornare al cliente il proprio metodo di pagamento tramite l’API di Aggiornamento Metodo di Pagamento, che addebita eventuali importi in sospeso.
Pagamenti una tantum: Invia nuovamente il checkout o payment_link affinché il cliente possa riprovare con un metodo diverso. Non esiste un ripetizione automatica per pagamenti una tantum.

Non riprovare declini hard con la stessa carta. Le reti di carte possono segnalare ripetuti declini come abusivi, il che riduce il tuo tasso di autorizzazione.

Comunicazione degli Errori ai Clienti in Sicurezza

Mostra ai clienti un messaggio amichevole — mai il vero error_code.

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 la vera ragione per STOLEN_CARD, LOST_CARD, PICKUP_CARD, o FRAUDULENT. Mostrare questi può avvisare un attore fraudolento. Mostra un messaggio di declino generico e registra solo il specifico error_code internamente.

Correlati

Transaction Failures

Ogni codice di declino, il suo tipo e l’azione raccomandata.

Error Codes

Errori di API e logica aziendale che non sono declini di carta.

Subscription Payment Retries

Recupero automatico dei declini soft sui rinnovi degli abbonamenti.

Subscription Dunning

Sequenze email che recuperano declini hard.

Payment Webhooks

Schema completo del payload per eventi di pagamento.

Testing Failures

Carte di test che simulano declini e fallimenti di rinnovo.

​Come Dodo Payments Riporta un Fallimento

​Il Webhook payment.failed

​Decidi se Riprovare: Declini Soft vs. Hard

​Gestire i Fallimenti al Checkout vs. al Rinnovo

​Riprovare un Pagamento Fallito

​Comunicazione degli 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`

Decidi se Riprovare: Declini Soft vs. Hard

Gestire i Fallimenti al Checkout vs. al Rinnovo

Riprovare un Pagamento Fallito

Comunicazione degli Errori ai Clienti in Sicurezza

Correlati