Una persona termina el pago y vuelve a la tienda, pero la página de confirmación no carga. O el proveedor de pagos envía la misma notificación más de una vez. En ambos casos, la tienda puede mostrar un estado que no refleja lo ocurrido en el proveedor. El riesgo no se resuelve confiando más en la pantalla de retorno: hace falta distinguir entre la respuesta del navegador, el estado real del pago y el estado del pedido.
Una confirmación de pagos en WooCommerce debe tratarse como un proceso de verificación y conciliación, no como una instrucción para cobrar de nuevo. El objetivo es que cada intento tenga identidad propia, que las notificaciones repetidas no generen efectos duplicados y que las discrepancias se revisen antes de modificar el pedido o activar acciones posteriores.
Por qué una respuesta tardía no debe cambiar el pedido por sí sola
El retorno del comprador al sitio y las notificaciones del proveedor cumplen funciones distintas. El retorno ayuda a informar al cliente, pero depende del navegador, la conexión y la sesión. Una notificación del proveedor —por ejemplo, un webhook— llega desde el sistema de pagos y puede enviarse con retraso o repetirse. Ninguna señal aislada debe interpretarse sin comprobar su origen, su relación con el intento de pago y su significado para la tienda.
Un retraso tampoco equivale a un pago fallido. Si la tienda vuelve a cobrar porque no recibió una respuesta inmediata, puede crear dos cargos. Del mismo modo, marcar el pedido como pagado solo porque el cliente llegó a una página de éxito puede conceder acceso o iniciar el despacho sin una transacción confirmada.
Conviene separar tres resultados: el estado de cada intento de pago, los eventos recibidos del proveedor y el estado operativo del pedido en WooCommerce. Un pedido puede seguir pendiente mientras un intento está en verificación; un intento anterior puede fallar y uno posterior completarse. Registrar esa secuencia evita reducir todo a una única etiqueta difícil de investigar.
Separar intento, notificación y estado del pedido
El pedido representa la compra y su ciclo comercial. El intento de pago representa una operación concreta ante la pasarela. La notificación es un mensaje sobre un evento, como autorización, captura, rechazo o reembolso. Estas entidades se relacionan, pero no son intercambiables. Cada intento debería conservar su identificador en el proveedor, importe, moneda, fecha y resultado conocido.
Antes de iniciar un nuevo intento, el flujo debe comprobar si ya existe uno en curso o un pago confirmado para ese pedido. Si se reintenta una operación hacia la pasarela, es preferible usar una clave de idempotencia compatible con el proveedor. Así, una repetición técnica de la misma solicitud puede reconocerse como la misma operación y no convertirse en un segundo cargo. La disponibilidad y el comportamiento de estas claves dependen de la integración y del proveedor; no se deben asumir.
Una notificación debe asociarse con un identificador de evento y con el identificador de transacción o intento correspondiente. Si el proveedor no ofrece un identificador único fiable, hay que definir una estrategia de deduplicación adecuada con los datos disponibles y documentar sus límites. No conviene deduplicar únicamente por pedido: un mismo pedido puede tener varios intentos legítimos.
Definir transiciones válidas y tratar eventos fuera de orden
Antes de actualizar pedidos, establezca qué transiciones son válidas para cada método de pago. Por ejemplo, un intento pendiente puede pasar a confirmado o fallido; una notificación antigua de pendiente no debería hacer retroceder un intento ya confirmado. Autorización y captura también pueden ser estados distintos: una autorización no siempre significa que el dinero se haya capturado.
La integración debe comparar el evento entrante con el estado registrado y con la transacción asociada. Si llega de nuevo un evento ya aplicado, se reconoce y se responde sin repetir efectos secundarios. Estos efectos pueden incluir reducir existencias, enviar correos, conceder acceso o avisar a un sistema externo. El cambio de estado y el registro de que se procesó el evento deben coordinarse para reducir la posibilidad de que un fallo intermedio deje el pedido actualizado, pero el evento sin marcar, o al contrario.
Los eventos fuera de orden requieren una regla explícita, no una comparación simple de fechas del servidor. Use la semántica de los estados del proveedor y, cuando sea necesario, consulte el estado actual de la transacción mediante su API. Si no se puede determinar una transición segura, conserve el estado conocido y envíe el caso a revisión en lugar de inferir un resultado.
Validar, registrar y actualizar con trazabilidad
Verifique que la notificación procede realmente del proveedor siguiendo el mecanismo documentado para esa integración, como la validación de firma. Compruebe también que la cuenta o el entorno corresponden a la tienda, y que importe, moneda, referencia y pedido coinciden con lo esperado. No acepte un mensaje solo porque contiene un identificador válido o llega a una URL difícil de adivinar.
Guarde un registro útil antes de aplicar cambios: identificador del evento, referencia del proveedor, pedido e intento relacionados, tipo de evento, resultado de validación, hora de recepción y decisión tomada. Proteja credenciales y datos personales: registre lo necesario para investigar, no números completos de tarjeta ni secretos. Evite incluir datos sensibles en registros de depuración accesibles a más personas de las necesarias.
Una discrepancia entre WooCommerce y el proveedor no se resuelve creando otra transacción. Consulte el estado de la operación en la herramienta o API del proveedor y compárelo con los registros de la tienda. Si se confirma el pago, actualice el pedido mediante el flujo compatible con la pasarela y compruebe que las acciones posteriores se ejecutan una sola vez. Si el resultado sigue siendo ambiguo, no marque el pedido como pagado ni inicie un nuevo cobro hasta aclararlo.
Crear una cola de revisión para las excepciones
Defina qué casos requieren revisión humana: importes o monedas diferentes, una referencia sin pedido asociado, una firma inválida, varios pagos confirmados para una compra, un reembolso inesperado o un estado que no admite transición. La cola debe mostrar las referencias necesarias, el último estado conocido y el motivo de la excepción, con permisos adecuados para investigar.
La revisión debe seguir pasos repetibles: consultar la transacción en el proveedor, verificar el pedido y sus intentos, decidir si corresponde actualizar, reembolsar o escalar, y dejar constancia de quién tomó la decisión. No resuelva discrepancias borrando registros ni modificando estados directamente en la base de datos; eso elimina contexto y puede desincronizar extensiones o tareas posteriores.
Probar retrasos, duplicados y fallos parciales
Pruebe en un entorno controlado las situaciones que rompen el flujo normal: retorno del navegador antes o después del webhook, notificaciones duplicadas, eventos fuera de orden, retraso prolongado, firma inválida y caída de la tienda durante el procesamiento. Incluya fallos parciales, como guardar el estado y perder la conexión antes de responder al proveedor, para comprobar que el reintento no duplica acciones.
Compruebe también que un intento fallido seguido de uno exitoso queda representado con claridad, que una notificación antigua no revierte el estado y que una solicitud repetida de cobro no crea otra transacción. Use los mecanismos de prueba de la pasarela y datos no productivos; no pruebe escenarios de cobro forzando pedidos reales. Verifique el resultado tanto en WooCommerce como en el panel o API del proveedor.
Lista operativa ante una posible discrepancia
- Identificar el pedido, cada intento y sus referencias de proveedor; no asumir que una referencia equivale a otra.
- Consultar el estado actual de la transacción con la fuente autorizada y comparar importe y moneda.
- Revisar si el evento fue autenticado, ya procesado o recibido fuera de orden.
- Confirmar si el pedido disparó efectos posteriores, como acceso, correo o preparación del envío.
- No volver a cobrar mientras exista un intento cuyo resultado no se haya aclarado.
- Documentar la decisión y escalar los casos ambiguos; si hubo dos cargos, seguir el procedimiento de reembolso del proveedor y comunicar el resultado al cliente.
Un flujo fiable no exige que cada respuesta llegue a tiempo: exige que los retrasos, duplicados y estados inciertos no desencadenen acciones irreversibles a ciegas. Separar los intentos del pedido, validar cada evento, aplicar transiciones idempotentes y revisar las excepciones permite investigar con evidencia y reduce el riesgo de cobros duplicados.
