Ir al contenido
Boost

Decisiones del webhook de pagos

Códigos de error · 12 códigos · catálogo del 2026-10-21

Cada aviso de la pasarela queda en payment_webhook_events con un decision_code (src/payments/entities/payment-webhook-event.entity.ts). El webhook nunca pierde un pago: lo que no puede aplicar lo guarda como REVIEW_* para revisión humana y lo que no entiende como REJECTED_*. ACCEPTED_APPLIED (el caso normal) no se lista.

Para toda la familia

Lo que un código no dice lo hereda de aquí.

Cómo se detecta
Base: SELECT decision_code, COUNT(*) FROM payment_webhook_events GROUP BY 1. Cada fila guarda el cuerpo recibido para revisarlo.
Qué hacer
REVIEW_*: alguien revisa el pago contra Zauru y la orden, y lo aplica a mano si corresponde. REJECTED_*: revisar la plantilla que manda la pasarela (Pabbly) si se repite.
12 códigos

Códigos

ACCEPTED_ALREADY_PAID

pago

Llegó otro aviso de un link que ya estaba pagado: no se asienta dos veces. Informativo.

REJECTED_INVALID_UUID

pago

El uuid del aviso no coincide con el del link (o llegó vacío). Es la única prueba de autenticidad del endpoint, así que el aviso se rechaza.

Causa típica
La plantilla del proveedor (Pabbly) manda mal la variable del uuid, o alguien llamó al webhook sin ser la pasarela.
Qué hacer
Si el uuid llegó vacío, revisar el paso que arma el cuerpo en la pasarela. Si no coincide, verificar con el proveedor que el cobro exista antes de hacer nada.

REJECTED_MALFORMED_PAYLOAD

pago

El cuerpo del aviso no se pudo leer o el monto no es un cobro (0 o negativo). No hay dinero que registrar.

Causa típica
La plantilla JSON del proveedor salió con huecos (variables sin llenar) o el proveedor mandó un aviso de prueba.
Cómo detectarlo
Base: payment_webhook_events con decision_code = 'REJECTED_MALFORMED_PAYLOAD'; decision_detail dice qué faltó. Es el rechazo más común en producción (14 al 30/09/2026).
Qué hacer
Revisar la plantilla del webhook en la pasarela (Pabbly) y que cada variable llegue llena.

REJECTED_STATUS_NOT_SUCCESS

pago

El proveedor avisó un estado que no es cobro exitoso (rechazado, cancelado…). El link queda failed; no hay nada que conciliar.

REVIEW_AMOUNT_BELOW_EXPECTED

pago

Link de varias órdenes: entró menos de lo esperado y no hay a qué orden cargarle lo que falta. Se guarda para revisión humana.

REVIEW_LINK_CANCELLED

pago

Llegó un pago para un link que ya estaba cancelado (p. ej. porque la cotización cambió). No se asienta: revisión humana.

REVIEW_LINK_NOT_FOUND

pago

Llegó un pago contra un link que no existe en esta base. No se asienta nada y el endpoint responde 404, pero la evidencia queda guardada.

Causa típica
Link borrado, ambiente cruzado (aviso de pruebas contra producción o al revés) o un cobro real que hay que explicar.
Cómo detectarlo
Render: [webhook] uid=<n> link inexistente. Base: payment_webhook_events con este decision_code y needs_reconciliation = 1.
Qué hacer
Verificar con el proveedor si el cobro ocurrió de verdad y a qué link o entidad corresponde.

REVIEW_ORDERS_CHANGED

pago

Link de varias órdenes: desde que se emitió, alguna orden se pagó por otro lado, se anuló o bajó su saldo. Asentar lo pondría doble: revisión humana.

REVIEW_PAYMENT_WITHOUT_ID

pago

Zauru aceptó el pago pero no devolvió su id, así que no se puede confirmar. El link queda failed y el pago para revisión.

REVIEW_STATUS_MISSING

pago

Llegó un aviso con el estado vacío: no se sabe si el cobro fue exitoso. El link queda intacto y el aviso para revisión.

Causa típica
La variable de estado no se llenó en el paso que arma el cuerpo del webhook en la pasarela.
Cómo detectarlo
Render: [webhook] uid=<n> llego con status vacio.
Qué hacer
Corregir la variable de estado en la pasarela y verificar con el proveedor si ese cobro ocurrió.

REVIEW_ZAURU_SYNC_FAILED

pago

El cobro llegó bien pero no se pudo asentar en Zauru (Zauru caído o sesión muerta). Se guarda la evidencia y se responde error para que el proveedor reintente.

Causa típica
Zauru no respondió o la sesión de servicio no estaba viva en ese momento.
Qué hacer
Si el proveedor no reintentó con éxito, asentar el pago a mano en Zauru con los datos de payment_webhook_events.

Texto generado desde el catálogo de errores de BoostAPI. Para corregirlo, se cambia allá y se sincroniza: verMantener esta documentación. También enMarkdown.