El checkout de WooCommerce no funciona: cómo diagnosticar la causa raíz

Síntomas

• El indicador de carga del checkout no se detiene tras pulsar Realizar pedido.
• Pulsar Realizar pedido no hace nada.
• Aparece un error genérico: Ha ocurrido un error al procesar tu pedido, No hemos podido procesar tu pedido, inténtalo de nuevo, o un aviso rojo vacío.
• El checkout funciona para unos clientes y no para otros: invitados, un método de pago, un país, solo móvil.
• El pedido se crea como Pendiente de pago o Fallido, pero el cliente nunca llega a la página de pago ni a la de agradecimiento.

Causas más comunes

1. Un error fatal de PHP en un hook del checkout: código de cargos, campos, envíos o validación a medida que falla con la versión actual de WooCommerce o de PHP.
2. Avisos o notices de PHP impresos en la respuesta, que corrompen el JSON que espera el script del checkout.
3. Un error de JavaScript que detiene el script del checkout antes de enviar la petición: scripts del tema, plugins de optimización que difieren o combinan scripts, herramientas de consentimiento que bloquean los scripts de pago.
4. El checkout en caché, sirviendo nonces caducados o datos de sesión de otra persona.
5. Una capa de seguridad que bloquea la petición: plugins de seguridad, reglas de ModSecurity, una regla de CDN o WAF, o restricciones de la REST API (que afectan al bloque de Checkout).
6. Errores de la pasarela devueltos al procesar el pedido: claves incorrectas, mezcla de modo prueba y real, validaciones de divisa o de importe.
7. Límites del servidor: tiempo de ejecución o memoria de PHP, o procesos de PHP-FPM agotados con carga.

Diagnóstico

1. Identifica qué checkout usa la tienda

El checkout clásico (shortcode [woocommerce_checkout]) actualiza los totales con ?wc-ajax=update_order_review y crea el pedido con ?wc-ajax=checkout. El bloque de Checkout crea los pedidos mediante la Store API, con un POST a /wp-json/wc/store/v1/checkout. Saber cuál tienes te dice qué petición buscar, y por qué una regla que bloquea la REST API solo rompe el bloque.

2. Reproduce el fallo con el panel de red abierto

Abre las herramientas de desarrollo del navegador en la pestaña Red, conserva el registro y haz un pedido de prueba: en una copia de staging si puedes o, si no, con un producto barato o un método de pago de prueba.

3. Lee el error a la hora exacta del fallo

Apunta la hora del pedido de prueba fallido y revisa:

• WooCommerce → Estado → Registros: el origen fatal-errors y el registro propio de la pasarela de pago.
• El log de errores PHP del panel del hosting, o wp-content/debug.log si el registro de depuración de WordPress está activo.
• La consola del navegador en busca de errores de JavaScript cuando no se envía ninguna petición.

4. Relaciónalo con los cambios recientes

Haz una lista de todo lo que cambió antes de que empezara el problema: actualizaciones de WooCommerce, extensiones y tema, versión de PHP, plugins nuevos, ajustes de caché o CDN, reglas de seguridad, ajustes de la pasarela de pago. La mayoría de los fallos de checkout empiezan justo después de un cambio.

5. Aísla en staging, no en producción

Si las evidencias apuntan a una interacción y no a un único error, reprodúcelo en una copia de staging y aíslalo allí: cambia a un tema por defecto como Storefront y desactiva plugins por mitades hasta que el fallo desaparezca. El modo de resolución de problemas del plugin Health Check & Troubleshooting hace esto solo para tu sesión del navegador, sin afectar a los clientes.

Registros y comprobaciones técnicas

• WooCommerce → Estado → Estado del sistema: versión de WooCommerce, versión y límites de PHP, y la lista de plantillas sobrescritas marcadas como desactualizadas.
• Registros: fatal-errors, el origen de registro de la pasarela, el log de errores PHP y el log de errores del servidor web para respuestas 403 y 5xx.
• Caché: confirma que /carrito/, /finalizar-compra/ y /mi-cuenta/ (o sus slugs en tu tienda) están excluidas de la caché de páginas, de la CDN y de cualquier optimización del HTML.
• Seguridad: registros del plugin de seguridad, eventos del WAF o bloqueos de ModSecurity sobre wc-ajax=checkout o /wp-json/wc/store/.
• Cuerpo de la respuesta de la petición que falla: cópialo entero. Una sola línea Warning: antes del JSON basta para romper el checkout clásico.

Soluciones

• Arregla el código que falla, no el síntoma: una función de cargos o de validación que lanza un TypeError en PHP 8 necesita un arreglo con tipos correctos, no más memoria.
• Revierte la actualización concreta que introdujo el fallo mientras se prepara el arreglo real en staging.
• Excluye el checkout de la caché y de la optimización, incluidas la combinación y el diferido de los scripts de pago.
• Permite los endpoints del checkout en el plugin de seguridad o el WAF, limitado a esas rutas, en lugar de desactivar la protección.
• Actualiza las plantillas sobrescritas desactualizadas del tema, o elimina las que ya no hagan falta.
• Saca las llamadas externas lentas (tarifas de envío, servicios de impuestos, consultas al ERP) de la petición del checkout, o cachéalas.

// Una función de cargos que no rompe con valores inesperados en PHP 8.
add_action( 'woocommerce_cart_calculate_fees', function ( WC_Cart $cart ) {
    $rate = (float) get_option( 'my_handling_rate', 0 ); // antes: TypeError string + float
    if ( $rate <= 0 ) {
        return;
    }
    $cart->add_fee( __( 'Gastos de gestión', 'my-store' ), $cart->get_subtotal() * $rate );
} );

Qué no hacer

• No desactives plugins uno a uno en la tienda en producción en horario comercial: rompe otros flujos y pierde pedidos en curso.
• No actives WP_DEBUG_DISPLAY en producción. Registra los errores; nunca los muestres a los clientes.
• No edites archivos del núcleo de WooCommerce ni copies plantillas del núcleo en el tema para «arreglar» el checkout.
• No subas a ciegas los límites de memoria y tiempo. Si una petición del checkout necesita 60 segundos, algo dentro de ella está mal.
• No cambies de pasarela ni reinstales WooCommerce antes de conocer la causa.

Cuándo recurrir a un experto

Recurre a un ingeniero cuando el error apunta a código a medida que no puedes cambiar con seguridad, cuando el checkout falla de forma intermitente sin un error claro, cuando se cobran pagos pero los pedidos fallan, o cuando la tienda está perdiendo pedidos ahora mismo y cada minuto cuenta.

Problemas relacionados

• WooCommerce / Pagos WooCommerce: el pago falla pero al cliente se le ha cobrado Cuando la pasarela cobra el pago pero el pedido se queda pendiente o fallido, revisa el traspaso de callbacks y webhooks antes de tocar el pedido. →
• WooCommerce / Errores Error fatal en WooCommerce: guía práctica para resolverlo Lee bien el error fatal (archivo, línea, traza) y relaciónalo con el cambio que lo provocó. →
• WooCommerce / Errores Conflicto de plugins en WooCommerce: cómo encontrar la causa Parte de las evidencias (el error, el momento, la petición) y aísla en staging por mitades, no plugin a plugin en producción. →
• WooCommerce / Rendimiento Checkout lento en WooCommerce: qué revisar Separa el tiempo de PHP, las consultas a la base de datos y las llamadas a APIs externas antes de cambiar la caché o el hosting. →

Preguntas frecuentes