Guías

Webhooks

Cómo Inspow recibe los eventos de pago de la pasarela y actualiza Facturas y Suscripciones.

Inspow recibe eventos de pago desde la pasarela de pagos mediante un webhook. Cuando una transacción cambia de estado, la pasarela notifica a Inspow, que verifica la autenticidad del evento y actualiza la Factura y, si corresponde, la Suscripción asociada.

El endpoint

Los eventos llegan a POST /api/payments/<pasarela>/webhook, donde <pasarela> identifica el adaptador de la pasarela (por ejemplo /api/payments/wompi/webhook). Es un endpoint público (sin sesión de Usuario) y sin contexto de Organización, ya que la llamada proviene de la pasarela. Su ruta no lleva versión: no cambia aunque avance el versionado de la API. Si la pasarela no existe, responde 404.

Verificación de firma

Antes de procesar cualquier dato, Inspow valida la firma del evento con el secreto de la pasarela. Si la firma no es válida, la petición se rechaza con 401 y no se realiza ningún cambio.

Eventos procesados

Cada pasarela traduce sus eventos a un formato común. En el caso de Wompi, se atiende el evento transaction.updated; cualquier otro evento, o uno sin referencia o sin estado, se confirma como recibido (200) pero no genera cambios.

El estado de la transacción puede ser:

Estado	Efecto en la Factura
`APPROVED`	Pasa a pagada (`PAID`): se guardan la fecha de pago, el identificador de la transacción y el método de pago.
`DECLINED`	Pasa a fallida (`FAILED`) y se guarda el motivo del rechazo.
`VOIDED`	Pago anulado después de aprobado: vuelve a pendiente (`PENDING`).
`PENDING`	Pago en proceso (por ejemplo PSE): solo se registra el intento.
`ERROR`	Se confirma como recibido, sin cambios en la Factura.

Referencias de pago

La referencia de la transacción determina cómo se enruta el evento:

Referencia	Tratamiento
Comienza con `ONB-`	Pago del registro en línea: lo procesa el flujo de alta.
Cualquier otra	Pago de una Factura (sus referencias empiezan con `INV-`).

Reacción ante el evento

Para un pago de Factura, Inspow emite un evento interno que el módulo de facturación escucha para actualizar la Factura. Los errores internos se registran, pero la respuesta a la pasarela siempre es 200 una vez verificada la firma, para que no reintente sin fin.

Cuando se paga la primera Factura de una Suscripción que estaba pendiente de pago, la suscripción pasa a activa, lo que da acceso al Miembro/Estudiante/Paciente/Socio.