Gérer les Échecs de Paiement

Lorsqu’un paiement échoue, Dodo Payments vous indique pourquoi grâce à un error_code standardisé et une error_message lisible par l’homme. Ce guide montre comment lire ces champs, décider si un nouvel essai est valable, et récupérer le paiement sans exposer d’informations sensibles aux clients.

Comment Dodo Payments Signale un Échec

Chaque paiement échoué — qu’il s’agisse d’un achat unique ou d’un renouvellement d’abonnement — comporte les mêmes champs d’échec sur l’objet de paiement :

Field	Type	Description
`status`	string	`failed` pour un paiement échoué. Les autres états sans succès incluent `cancelled`, `requires_customer_action` et `requires_payment_method`.
`error_code`	string \| null	Le motif d’échec standardisé, par exemple `INSUFFICIENT_FUNDS` ou `PROCESSING_ERROR`. Consultez la référence Transaction Failures pour obtenir la liste complète.
`error_message`	string \| null	Une explication lisible de l’échec, rédigée pour vous et non pour votre client. Pour un `error_code` standardisé, il s’agit d’un titre accompagné de l’action recommandée, et non du texte brut du processeur.
`retry_attempt`	integer	`0` pour le débit d’origine. `1` ou une valeur supérieure identifie une nouvelle tentative planifiée de renouvellement d’abonnement.

error_code et error_message sont null jusqu’à ce qu’un paiement échoue réellement. Vérifiez toujours d’abord status, puis lisez les champs d’erreur.

Le error_message de l’API marchand est un contenu destiné au marchand. Il peut indiquer le motif réel d’un refus, y compris les motifs liés à la fraude. Ne l’affichez donc jamais directement à un client. Associez plutôt error_code à votre propre formulation sécurisée pour les clients, comme indiqué dans Afficher les erreurs aux clients en toute sécurité.

Le webhook `payment.failed`

Le moyen le plus fiable de détecter un échec est le webhook payment.failed. L’événement encapsule l’objet de paiement complet dans 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 gestionnaire minimal lit error_code et effectue un routage en fonction de celui-ci :

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}

Vérifiez toujours la signature du webhook avant tout traitement. Consultez le guide Webhooks pour la configuration complète, notamment la vérification de signature et l’idempotence.

Décider s’il faut réessayer : refus temporaires ou définitifs

Le error_code vous indique s’il est utile de réessayer avec le même moyen de paiement.

Decline type	What it means	What to do
Refus temporaire	Temporaire ou corrigeable (par exemple `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Une nouvelle tentative — après un délai ou une fois que le client a corrigé ses informations — peut aboutir.
Refus définitif	Irréversible (par exemple `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Ne réessayez pas avec la même carte. Demandez au client d’utiliser un autre moyen de paiement.

La référence Transaction Failures répertorie le type de refus et l’action recommandée pour chaque error_code.

Gérer les échecs lors du paiement initial ou du renouvellement

La façon dont vous récupérez l’échec dépend de la présence ou non du client.

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

Le client est en train d’effectuer son paiement. Affichez un message clair et laissez-le réessayer immédiatement ou utiliser une autre carte.

requires_payment_method — le client n’a jamais fourni de moyen de paiement : il n’a pas saisi les informations de sa carte ou a été invité à le faire sans donner suite. Il s’agit généralement d’un abandon lors du paiement, et non d’un refus : relancez le client pour qu’il termine son paiement (consultez Récupération des paniers abandonnés).
requires_customer_action — une authentification supplémentaire (telle que 3DS) est requise ; demandez au client de l’effectuer. Consultez Gestion de 3D Secure.

Le client n’est pas présent, vous ne pouvez donc pas lui demander d’intervenir en temps réel. Lorsqu’un renouvellement échoue, l’abonnement passe à on_hold et subscription.on_hold est déclenché.

Les refus temporaires font automatiquement l’objet de nouvelles tentatives par Nouvelles tentatives de paiement d’abonnement.
Les refus définitifs (ainsi que les nouvelles tentatives épuisées) sont mieux récupérés avec Relances d’abonnement, qui envoie un e-mail au client pour l’inviter à mettre à jour son moyen de paiement.

Consultez le guide d’intégration des abonnements pour découvrir le flux complet de mise en attente → réactivation.

Réessayer un paiement échoué

Abonnements : activez Nouvelles tentatives de paiement d’abonnement pour récupérer les refus temporaires sans travail d’intégration. Vous pouvez également déclencher la récupération en demandant au client de mettre à jour son moyen de paiement via l’API Update Payment Method, qui débite les sommes dues.
Paiements ponctuels : renvoyez le checkout ou payment_link afin que le client puisse réessayer avec un autre moyen de paiement. Les paiements ponctuels ne font l’objet d’aucune nouvelle tentative automatique.

Ne réessayez pas les refus définitifs avec la même carte. Les réseaux de cartes peuvent considérer les refus répétés comme abusifs, ce qui nuit à votre taux d’autorisation.

Afficher les erreurs aux clients en toute sécurité

Affichez aux clients un message convivial — jamais le error_code brut et jamais le error_message destiné au marchand.

Sur les interfaces contrôlées par Dodo Payments — le checkout, le Customer Portal et les e-mails de relance — cette correspondance est déjà effectuée pour vous, y compris le recours à un message générique pour les refus liés à la fraude. Vous n’avez besoin de la correspondance ci-dessous que lorsque vous affichez les échecs dans votre propre produit.

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.";
}

Ne révélez jamais le motif réel de STOLEN_CARD, LOST_CARD, PICKUP_CARD ou FRAUDULENT. Leur affichage pourrait alerter un acteur frauduleux. Affichez un message de refus générique et consignez uniquement le error_code spécifique en interne.

Articles associés

Transaction Failures

Chaque code de refus, son type et l’action recommandée.

Error Codes

Erreurs d’API et de logique métier qui ne sont pas des refus de carte.

Subscription Payment Retries

Récupération automatique des refus temporaires lors des renouvellements d’abonnement.

Subscription Dunning

Séquences d’e-mails qui permettent de récupérer les refus définitifs.

Payment Webhooks

Schéma complet de la charge utile des événements de paiement.

Testing Failures

Cartes de test qui simulent les refus et les échecs de renouvellement.

Integration Guides

Billing Deconstructions

Cookbooks

Comment Dodo Payments Signale un Échec

Le webhook `payment.failed`

Décider s’il faut réessayer : refus temporaires ou définitifs

Gérer les échecs lors du paiement initial ou du renouvellement

Réessayer un paiement échoué

Afficher les erreurs aux clients en toute sécurité

Articles associés

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Comment Dodo Payments Signale un Échec

​Le webhook payment.failed

​Décider s’il faut réessayer : refus temporaires ou définitifs

​Gérer les échecs lors du paiement initial ou du renouvellement

​Réessayer un paiement échoué

​Afficher les erreurs aux clients en toute sécurité

​Articles associés

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Comment Dodo Payments Signale un Échec

Le webhook `payment.failed`

Décider s’il faut réessayer : refus temporaires ou définitifs

Gérer les échecs lors du paiement initial ou du renouvellement

Réessayer un paiement échoué

Afficher les erreurs aux clients en toute sécurité

Articles associés