Recibes una transferencia en tu cuenta, pero tu ERP sigue mostrando la factura como impagada. Pasaron dos horas, tres, media mañana. Tu equipo administrativo llama al cliente creyendo que no pagó, cuando el dinero ya está en el banco. El problema no es el cobro: es que tu sistema de gestión no escucha cuándo llega.
Lo que te llevas de este artículo
- Escuchar el evento correcto: «pago acreditado» confirma que el dinero llegó; «pago iniciado» no es suficiente para aplicar.
- Implementar idempotencia guardando el ID único de cada webhook antes de procesarlo evita duplicar pagos por reintentos del servidor.
- Guardar RFC del pagador, referencia de transferencia, fecha-hora y factura vinculada crea un registro auditables para el SAT.
- Validar la firma del webhook antes de procesar asegura que solo transacciones legítimas actualicen tu ERP.
Por qué conectar cobros y ERP es un problema operativo, no técnico
La mayoría de las PyMEs y medianas empresas cobran por transferencia, pero el flujo entre el banco y el ERP sigue siendo manual o parcial. El cliente paga, aparece un depósito sin identificar en el estado de cuenta, alguien lo busca en una hoja de cálculo, lo concilia a mano, y recién entonces actualiza el estado de la factura. Mientras tanto, el cliente recibe recordatorios de pago, el área de cobranza duplica llamadas, y el cierre contable se retrasa.
Conectar el cobro al ERP significa que cuando llega dinero a tu cuenta, tres cosas suceden automáticamente: se identifica quién pagó, se marca la factura como pagada, y se genera un registro que después puedas auditar. Eso requiere que tu ERP escuche eventos específicos del proveedor de cobro, los procese sin duplicarlos y almacene los datos que necesitas para justificar cada movimiento ante un auditor o ante el SAT.
Qué necesitas tener listo antes de conectar
Antes de cualquier integración, define tres cosas:
- Qué identifica a cada cliente en tu ERP. ¿Es un RFC, un número de cliente, un correo? Ese dato debe estar en la orden de pago para que el webhook lo encuentre y lo asigne correctamente.
- Qué eventos necesitas escuchar. No todos los eventos de cobro importan igual. Algunos solo notifican que se inició una transferencia; otros confirman que el dinero llegó y se puede aplicar. Confundir uno con otro causa pagos fantasma o aplicaciones que después se revierten.
- Dónde guardarás cada webhook recibido. Si tu ERP falla o el servidor está fuera, el evento se pierde. Necesitas un registro paralelo que te permita recuperar qué pasó y reintentarlo sin duplicar.
Pasos para conectar cobros y ERP sin duplicar
- Identifica los eventos que tu proveedor de cobro emite. Generalmente son: «pago iniciado» (el cliente mandó la orden), «pago acreditado» (el dinero llegó a tu cuenta) y «CFDI timbrado» (la factura de recepción está lista). No todos aplican a tu flujo. Por ejemplo, si tu facturación es electrónica, el evento «CFDI timbrado» es el que cierra el ciclo; si usas facturación manual, te importa más «pago acreditado».
- Configura un endpoint en tu ERP que reciba webhooks. Es una URL que el proveedor de cobro llamará cada vez que ocurra un evento. Ese endpoint debe estar documentado: qué parámetros recibe, en qué formato, y qué respuesta espera el proveedor.
- Implementa un sistema de idempotencia. Cada webhook tiene un ID único. Antes de procesar, guarda ese ID en una tabla de «eventos procesados». Si llega el mismo webhook dos veces, la segunda vez lo rechazas sin tocar el ERP. Esto evita que un pago se aplique dos veces por un reintento del servidor.
- Mapea los datos del webhook a los campos de tu ERP. El webhook trae: monto, fecha, RFC del pagador, referencia de la transferencia, número de comprobante fiscal. Tu ERP necesita saber dónde va cada uno. Crea una tabla de correspondencia antes de escribir código.
- Guarda cada webhook recibido en un log inmutable. Antes de procesarlo, escríbelo en una base de datos o archivo de auditoría. Si después hay un reclamo, esa copia te permite reconstruir qué pasó exactamente y en qué momento.
- Prueba con pagos de prueba en ambiente de desarrollo. Usa las credenciales de prueba del proveedor, envía transferencias ficticias, y verifica que el webhook llegue, que el pago se aplique una sola vez, y que el registro de auditoría se genere.
- Activa en producción con monitoreo. Los primeros días, revisa cada webhook en el log. Verifica que los montos coincidan, que no haya duplicados, y que el ERP muestre el pago aplicado en la factura.
Qué debe hacer cada parte: proveedor, tu ERP y tu auditoría
| Componente | Responsabilidad | Dato crítico que genera |
|---|---|---|
| Proveedor de cobro (FinaxaPay) | Emitir webhooks cuando el pago llega a tu cuenta, asegurando que cada uno tenga un ID único y timestamp | ID del evento, monto, RFC del pagador, CLABE de origen, fecha-hora de acreditación |
| Tu endpoint (receptor) | Recibir el webhook, verificar que sea auténtico, guardar una copia, validar idempotencia | Copia íntegra del webhook, timestamp de recepción, resultado del procesamiento (éxito/error) |
| Tu ERP | Buscar la factura por RFC + monto, marcarla como pagada, generar asiento contable | Factura actualizada, asiento contable, vínculo entre la factura y el ID del evento de cobro |
| Log de auditoría | Guardar cada paso: qué webhook llegó, cuándo, qué se procesó, qué resultado tuvo | Registro inmutable con timestamp, usuario, acción, antes/después del cambio |
Errores que más cometen en esta integración
Procesar un webhook sin verificar su autenticidad. El proveedor firma cada webhook con una clave privada. Tu endpoint debe validar esa firma antes de tocar el ERP. Si no lo haces, cualquiera puede simular un pago y duplicar facturas.
Confundir «pago iniciado» con «pago acreditado». Un cliente puede iniciar una transferencia y cancelarla después. Si aplicas el pago apenas ve el evento «iniciado», después tienes que revertir. Espera siempre a «acreditado» o al evento que confirme que el dinero llegó a tu cuenta.
No guardar la referencia de la transferencia. El banco te da un número de referencia (SPEI, CLABE, etc.). Guárdalo junto con el pago. Si hay un reclamo, es el único dato que te permite rastrear la transferencia en el banco.
Procesar webhooks sin idempotencia. Si tu servidor tarda en responder, el proveedor reintenta. Sin un sistema de deduplicación, el pago se aplica dos, tres o más veces. El ERP queda corrupto y la auditoría es un caos.
Qué datos guardar de cada transacción para auditar después
Cuando llegue un pago, almacena estos campos en tu log de auditoría:
- ID único del evento (el que emite el proveedor)
- Monto y moneda
- RFC del pagador y del receptor (tu empresa)
- Fecha y hora de acreditación en tu cuenta
- Referencia de la transferencia (número SPEI, CLABE, etc.)
- Factura a la que se aplicó (número de documento)
- Timestamp de cuando tu sistema procesó el webhook
- Usuario o proceso que ejecutó la aplicación del pago
- Resultado: éxito, error, o reintento
Estos datos son tu defensa si el SAT audita, si un cliente reclama, o si tu contador necesita reconciliar.
Cómo empezar
La integración de cobros con ERP no es opcional si tu negocio crece. Cada pago manual que no se aplica automáticamente es una hora de trabajo administrativo que no genera valor. Comienza identificando qué eventos necesitas escuchar (generalmente «pago acreditado» es el primero), implementa idempotencia desde el inicio, y prueba con pagos de prueba antes de ir a producción.
FinaxaPay emite webhooks con ID único y timestamp para cada evento, y su API está documentada para que mapees cada campo a tu ERP. Consulta la documentación en https://finaxapay.site/docs para ver el formato exacto de los eventos y los parámetros que recibirás.
Preguntas frecuentes
¿Qué pasa si mi ERP está fuera de servicio cuando llega un webhook?
El proveedor reintenta el webhook varias veces durante horas. Mientras tanto, guarda una copia del webhook en tu log de auditoría. Cuando el ERP vuelva, procesa los webhooks pendientes usando el ID único para evitar duplicados.
¿Cómo distingo un webhook auténtico de uno falso?
El proveedor firma cada webhook con una clave privada. Tu endpoint debe validar esa firma usando la clave pública que el proveedor te proporciona. Si la firma no coincide, rechaza el webhook.
¿Qué hago si un cliente paga dos veces por error?
Tu log de auditoría mostrará dos eventos con IDs diferentes. Aplica el primer pago a la factura. El segundo queda como «pago excedente» o «anticipo» según tu política. Nunca duplicas la factura por idempotencia.
¿Puedo conectar mi ERP sin cambiar cómo recibo pagos?
Sí. La integración de webhooks es independiente del método de cobro. Sigas usando transferencias, depósitos o lo que uses, el webhook se emite igual cuando el dinero llega.
¿Qué pasa con el CFDI si el cliente pagó pero no lo recibió?
El evento «CFDI timbrado» es separado de «pago acreditado». Si el cliente pagó pero el CFDI aún no está listo, aplica el pago a la factura de todas formas. El comprobante de recepción se genera después, independientemente.