Gérer les Échecs de Paiement

Lorsqu’un paiement échoue, Dodo Payments fournit un error_code standardisé et un error_message compréhensible. Ce guide explique comment lire ces champs, déterminer s’il faut réessayer et récupérer le paiement en toute sécurité.

Comment Dodo Payments Signale un Échec

Chaque paiement échoué contient ces champs dans l’objet de paiement :

Champ	Type	Description
`status`	string	`failed` pour un paiement échoué. Autres états sans succès : `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Motif d’échec standardisé, par exemple `INSUFFICIENT_FUNDS` ou `PROCESSING_ERROR`. Consultez Échecs de transaction pour obtenir la liste complète.
`error_message`	string \| null	Explication destinée au marchand avec l’action recommandée. Ne pas afficher aux clients.
`retry_attempt`	integer	`0` pour le débit initial. `1` ou supérieur pour les nouvelles tentatives de renouvellement d’un abonnement planifié.

error_code et error_message sont null jusqu’à l’échec d’un paiement. Vérifiez toujours status en premier.

error_message est destiné au marchand et peut révéler des motifs liés à la fraude. Ne l’affichez jamais aux clients. Associez plutôt error_code à un texte adapté aux clients (consultez Afficher les erreurs aux clients en toute sécurité).

Le webhook `payment.failed`

Le webhook payment.failed est le moyen le plus fiable de détecter un échec. L’événement contient 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 l’oriente en fonction de sa valeur :

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}

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.

Type de refus	Exemples	Action
Refus temporaire	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Réessayez après un délai ou une fois que le client a corrigé ses informations.
Refus définitif	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Ne réessayez pas avec la même carte. Demandez au client d’utiliser un autre moyen de paiement.

Consultez Échecs de transaction pour obtenir la liste complète des types de refus et des actions recommandées.

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 permettez-lui de réessayer ou d’utiliser une autre carte.

requires_payment_method — le client n’a jamais fourni de moyen de paiement. Il s’agit généralement d’un abandon du checkout, 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 nécessaire. Demandez au client de l’effectuer. Consultez 3D Secure.

Le client n’est pas présent. Lorsqu’un renouvellement échoue, l’abonnement passe à on_hold et subscription.on_hold est déclenché. Si votre entreprise prévoit une période de grâce, il passe d’abord à past_due (subscription.past_due) et l’accès est maintenu jusqu’à la fin de cette période.

Les refus temporaires font automatiquement l’objet de nouvelles tentatives si vous activez Nouvelles tentatives de paiement des abonnements (désactivé par défaut). Les nouvelles tentatives concernent uniquement les renouvellements planifiés, et non les débits à la demande.
Les refus définitifs (ainsi que les nouvelles tentatives épuisées) lors des renouvellements planifiés sont récupérés avec Relance des abonnements, qui envoie un e-mail au client pour mettre à jour son moyen de paiement. Pour les échecs de débit à la demande, consultez Abonnements à la demande.

Consultez Guide d’intégration des abonnements pour connaître le flux complet de mise en attente → réactivation.

Réessayer un paiement échoué

Abonnements : activez Nouvelles tentatives de paiement des abonnements pour récupérer automatiquement les refus temporaires. Pour réessayer immédiatement au lieu d’attendre la planification, utilisez Nouvelle tentative de paiement manuelle depuis le tableau de bord ou l’API. Vous pouvez également déclencher la récupération en demandant au client de mettre à jour son moyen de paiement via l’API de mise à jour du moyen de paiement, 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. 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 signalent les refus répétés comme abusifs, ce qui réduit votre taux d’autorisation.

Afficher les erreurs aux clients en toute sécurité

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

Sur les interfaces contrôlées par Dodo Payments (checkout, Customer Portal, e-mails de relance), cette correspondance est déjà effectuée pour vous, avec notamment un message générique de remplacement 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. Les afficher pourrait alerter un fraudeur. Affichez un message générique de refus et consignez uniquement en interne le error_code spécifique.

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 récupèrent 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