Une erreur 500 sur le checkout WooCommerce n'est pas un simple refus de carte. Elle signale souvent une panne serveur, une erreur PHP fatale, un endpoint Ajax cassé, une initialisation de passerelle impossible ou un conflit plugin avant la création de commande.
Le client voit parfois seulement un spinner, une page blanche, une erreur interne ou un bouton commander qui ne termine jamais. La boutique peut rester en ligne pendant que le revenu est bloqué à l'étape censée encaisser.
Signaux d'une erreur technique checkout
Cherchez la première étape où le signal disparaît : page checkout en 500, `update_order_review` en erreur, Store API ou Ajax qui répond mal, moyens de paiement qui disparaissent après rafraîchissement du formulaire, ou page blanche après clic sur commander.
CashFlowCanary traite ces signaux comme un incident de conversion, pas comme un simple incident uptime. La surveillance checkout WooCommerce relie l'étape touchée, le signal attendu, la classe d'erreur observée, l'heure et la priorité, sans dump de données client.
Vérifier dans le bon ordre
Commencez par charger la page checkout avec un panier synthétique. Si la page elle-même renvoie 500, le problème se situe avant le paiement : thème, extension, template, shortcode, bloc, session ou initialisation WooCommerce.
Si la page charge mais que le recalcul échoue, observez `update_order_review`, les endpoints Store API et les changements de livraison, taxe ou coupon. Un statut 500 sur cette zone explique souvent un bouton final qui ne devient jamais utilisable.
Si l'erreur apparaît après clic sur commander, cherchez si une commande est créée, si la passerelle reçoit une tentative, et si le retour attend une confirmation. L'absence de commande, la commande en échec et la confirmation absente ne racontent pas la même panne.
| Symptôme observé | Où regarder | Ce que cela indique |
|---|---|---|
| La page checkout renvoie 500 | Thème, extension, template, bloc, session, initialisation WooCommerce | La panne est avant le paiement |
| La page charge, le recalcul échoue | `update_order_review`, endpoints Store API, livraison, taxe, coupon | Le bouton final ne devient jamais utilisable |
| L'erreur suit le clic sur commander | Commande créée, tentative reçue par la passerelle, confirmation attendue | Absence de commande, commande en échec et confirmation absente sont trois pannes différentes |
À distinguer d'un refus de paiement normal
Un refus normal concerne une tentative de paiement individuelle. Une erreur technique checkout touche la capacité du tunnel : moyens de paiement absents, commande non créée, confirmation jamais atteinte, ou même échec répété sur un parcours contrôlé.
Cette distinction accélère la triage. Le refus carte relève souvent du support paiement. L'erreur 500, fatale, Ajax ou page blanche relève plutôt de l'équipe technique ou de l'agence qui maintient la pile WooCommerce.
Interpréter les résultats
Une erreur visible dès le chargement oriente vers un changement récent de thème, plugin, PHP, cache objet ou compatibilité WooCommerce. Une erreur sur recalcul oriente vers livraison, taxes, panier, coupons ou fragments. Une erreur au paiement oriente vers gateway, script tiers, webhook, retour 3DS ou création de commande.
Ne concluez pas trop vite à une cause unique. L'objectif de la première preuve est de réduire le périmètre. Ensuite seulement, l'équipe peut inspecter logs applicatifs, journal WooCommerce, console navigateur et historique des déploiements.
Preuve utile pour développeur ou agence
La preuve doit répondre à quatre questions : quelle étape casse, quel résultat était attendu, quel résultat est observé, et pourquoi c'est prioritaire maintenant. Elle doit éviter secrets, noms clients, emails, contenu panier et captures contenant des données personnelles.
Pour le diagnostic global, commencez par le pilier checkout cassé. Pour les pannes de paiement, comparez avec paiement refusé WooCommerce.
Exemple documenté de laboratoire
Point de départ : boutique de test, montée de version PHP la veille, un plugin de taxe non retesté. Panne reproduite : le checkout charge correctement, puis la requête de recalcul renvoie une erreur serveur après sélection d'un mode de livraison. Le client voit un spinner qui ne termine pas. La home et la page produit restent vertes, donc un ping HTTP classique ne déclenche rien.
Hypothèses écartées : ce n'est pas un refus de carte (l'erreur précède l'étape de paiement), pas un problème de thème checkout (la page s'affiche), pas une panne globale (seul `update_order_review` échoue). Le journal WooCommerce confirme ensuite une erreur fatale dans le plugin de taxe. La preuve exploitable contient le timestamp, l'étape `recalcul checkout`, le statut d'échec, le contenu attendu, le signal réellement observé et la récupération après désactivation du plugin. Elle ne contient ni payload client ni données de paiement.
Confirmer le rétablissement
Surveiller cette classe de panne ne doit pas s'arrêter au fait que l'URL checkout répond. Il faut rejouer assez loin le parcours revenu pour vérifier que panier, checkout, paiement et confirmation restent cohérents.
Quand une erreur technique est détectée, CashFlowCanary garde l'incident ouvert jusqu'au retour au vert. L'équipe obtient une preuve courte de la panne, du signal de récupération et de ce qui peut être partagé sans exposer de données inutiles.
Prévenir la récidive
Une erreur 500 au checkout suit presque toujours un changement de pile : version de PHP, mise à jour de WooCommerce ou d'un plugin, bascule de cache objet. Retestez le parcours de commande complet après chaque changement de ce type sur un environnement de préproduction, gardez une trace datée des déploiements pour recouper avec l'heure de l'incident, et laissez un monitor sur `update_order_review` et sur la requête finale. Pour cadrer un premier site, demandez un audit gratuit ou consultez les tarifs.