Le checkout WooCommerce ne fonctionne pas : trouver la cause racine

Symptômes

• L’indicateur de chargement du checkout tourne sans fin après un clic sur Commander.
• Cliquer sur Commander ne fait rien.
• Une erreur générique s’affiche : Une erreur s’est produite lors du traitement de votre commande, Nous n’avons pas pu traiter votre commande, veuillez réessayer, ou un bandeau rouge vide.
• Le checkout fonctionne pour certains clients et pas pour d’autres : invités, un moyen de paiement, un pays, mobile uniquement.
• La commande est créée En attente de paiement ou Échouée, mais le client n’atteint jamais la page de paiement ni la page de remerciement.

Causes les plus fréquentes

1. Une erreur fatale PHP dans un hook du checkout : du code de frais, de champs, de livraison ou de validation sur mesure qui casse avec la version actuelle de WooCommerce ou de PHP.
2. Des avertissements ou notices PHP imprimés dans la réponse, qui corrompent le JSON attendu par le script du checkout.
3. Une erreur JavaScript qui arrête le script du checkout avant l’envoi de la requête : scripts du thème, extensions d’optimisation qui diffèrent ou combinent les scripts, outils de consentement qui bloquent les scripts de paiement.
4. Un checkout mis en cache, qui sert des nonces expirés ou les données de session de quelqu’un d’autre.
5. Une couche de sécurité qui bloque la requête : extensions de sécurité, règles ModSecurity, une règle CDN ou WAF, ou des restrictions de la REST API (qui touchent le bloc de validation de commande).
6. Des erreurs de passerelle renvoyées pendant le traitement de la commande : mauvaises clés, mélange des modes test et production, validations de devise ou de montant.
7. Des limites serveur : temps d’exécution ou mémoire PHP, ou workers PHP-FPM saturés sous la charge.

Diagnostic

1. Identifiez le checkout utilisé par la boutique

Le checkout classique (shortcode [woocommerce_checkout]) met à jour les totaux avec ?wc-ajax=update_order_review et crée la commande avec ?wc-ajax=checkout. Le bloc de validation de commande crée les commandes via la Store API, par un POST vers /wp-json/wc/store/v1/checkout. Savoir lequel vous utilisez indique quelle requête chercher, et pourquoi une règle qui bloque la REST API ne casse que le bloc.

2. Reproduisez l’échec avec le panneau Réseau ouvert

Ouvrez les outils de développement du navigateur sur l’onglet Réseau, conservez le journal et passez une commande de test : sur une préproduction si possible, sinon avec un produit peu cher ou un moyen de paiement de test.

3. Lisez l’erreur à l’heure exacte de l’échec

Notez l’heure de la commande de test échouée et consultez :

• WooCommerce → État → Journaux : la source fatal-errors et le journal propre à la passerelle de paiement.
• Le journal d’erreurs PHP dans le panneau de l’hébergeur, ou wp-content/debug.log si la journalisation de débogage de WordPress est active.
• La console du navigateur pour les erreurs JavaScript quand aucune requête n’est envoyée.

4. Rapprochez-la des changements récents

Listez tout ce qui a changé avant le début du problème : mises à jour de WooCommerce, des extensions et du thème, version de PHP, nouvelles extensions, réglages de cache ou de CDN, règles de sécurité, réglages de la passerelle de paiement. La plupart des pannes de checkout commencent juste après un changement.

5. Isolez en préproduction, pas en production

Si les éléments pointent vers une interaction plutôt qu’une erreur unique, reproduisez le problème sur une préproduction et isolez-le là : passez à un thème par défaut comme Storefront et désactivez les extensions par moitiés jusqu’à ce que l’échec disparaisse. Le mode de dépannage de l’extension Health Check & Troubleshooting le fait pour votre seule session de navigateur, sans toucher les clients.

Journaux et vérifications techniques

• WooCommerce → État → État du système : version de WooCommerce, version et limites de PHP, et la liste des modèles surchargés signalés comme obsolètes.
• Journaux : fatal-errors, la source de journal de la passerelle, le journal d’erreurs PHP et le journal d’erreurs du serveur web pour les réponses 403 et 5xx.
• Cache : vérifiez que /panier/, /commande/ et /mon-compte/ (ou leurs slugs sur votre boutique) sont exclus du cache de pages, de la CDN et de toute optimisation HTML.
• Sécurité : journaux de l’extension de sécurité, événements WAF ou blocages ModSecurity sur wc-ajax=checkout ou /wp-json/wc/store/.
• Corps de la réponse de la requête en échec : copiez-le en entier. Une seule ligne Warning: avant le JSON suffit à casser le checkout classique.

Solutions

• Corrigez le code en échec, pas le symptôme : une fonction de frais ou de validation qui lève un TypeError sous PHP 8 a besoin d’une correction de types, pas de plus de mémoire.
• Revenez sur la mise à jour précise qui a introduit l’échec, le temps de préparer la vraie correction en préproduction.
• Excluez le checkout du cache et de l’optimisation, y compris la combinaison et le différé des scripts de paiement.
• Autorisez les points d’accès du checkout dans l’extension de sécurité ou le WAF, limités à ces chemins, au lieu de désactiver la protection.
• Mettez à jour les modèles surchargés obsolètes du thème, ou supprimez ceux qui ne sont plus nécessaires.
• Sortez les appels externes lents (tarifs de livraison, services de taxes, requêtes ERP) de la requête de commande, ou mettez-les en cache.

// Une fonction de frais qui ne casse pas avec des valeurs inattendues sous PHP 8.
add_action( 'woocommerce_cart_calculate_fees', function ( WC_Cart $cart ) {
    $rate = (float) get_option( 'my_handling_rate', 0 ); // avant : TypeError string + float
    if ( $rate <= 0 ) {
        return;
    }
    $cart->add_fee( __( 'Frais de gestion', 'my-store' ), $cart->get_subtotal() * $rate );
} );

Ce qu’il ne faut pas faire

• Ne désactivez pas les extensions une par une sur la boutique en production pendant les heures d’activité : cela casse d’autres parcours et fait perdre des commandes en cours.
• N’activez pas WP_DEBUG_DISPLAY en production. Journalisez les erreurs, ne les affichez jamais aux clients.
• Ne modifiez pas les fichiers du cœur de WooCommerce et ne copiez pas les modèles du cœur dans le thème pour « réparer » le checkout.
• N’augmentez pas les limites de mémoire et de temps à l’aveugle. Si une requête de commande a besoin de 60 secondes, quelque chose cloche à l’intérieur.
• Ne changez pas de passerelle et ne réinstallez pas WooCommerce avant de connaître la cause.

Quand faire appel à un expert

Faites appel à un ingénieur quand l’erreur pointe vers du code sur mesure que vous ne pouvez pas modifier sans risque, quand le checkout échoue de façon intermittente sans erreur claire, quand des paiements sont encaissés mais que les commandes échouent, ou quand la boutique perd des commandes en ce moment et que chaque minute compte.

Problèmes liés

• WooCommerce / Paiements WooCommerce : paiement échoué mais client débité Quand la passerelle encaisse le paiement mais que la commande reste en attente ou échouée, vérifiez le relais des callbacks et des webhooks avant de toucher à la commande. →
• WooCommerce / Erreurs Erreur fatale WooCommerce : guide de dépannage pratique Lisez correctement l’erreur fatale (fichier, ligne, trace) et rattachez-la au changement qui l’a déclenchée. →
• WooCommerce / Erreurs Conflit d’extensions WooCommerce : comment trouver la cause Partez des preuves (l’erreur, le moment, la requête) et isolez en préproduction par moitiés, pas extension par extension en production. →
• WooCommerce / Performance Checkout WooCommerce lent : quoi vérifier Séparez le temps PHP, les requêtes en base de données et les appels d’API externes avant de changer de cache ou d’hébergement. →

Questions fréquentes