Introducción a Webhooks

Los webhooks de Forpay son notificaciones HTTP en tiempo real que se envían a las URLs que tú defines cuando ocurre un evento relevante en el ciclo de vida de un compromiso de pago. Esto permite que tu sistema reaccione de forma inmediata a las activaciones y cobros, sin necesidad de consultar activamente el estado de cada operación.

¿Cómo funciona?

Cuando integras con Forpay, proporcionas dos URLs de callback durante la creación de cada mandato:

activationWebhook: Recibe una notificación cuando un cliente completa el enrolamiento de su medio de pago (tarjeta, cuenta bancaria, etc.).
paymentWebhook: Recibe una notificación cada vez que se procesa el cobro de una cuota (exitosa, rechazada, en proceso, etc.).

Forpay realizará un POST con un cuerpo JSON a cada una de estas URLs según el evento correspondiente.

Tipos de eventos

Webhook de Activación

Se dispara cuando un compromiso de pago cambia de estado. El caso más común es la activación del mandato tras el enrolamiento exitoso del medio de pago del cliente.

Los métodos de pago que generan este evento son:

Método de Pago	ID
Tarjeta de Crédito	3
Tarjeta de Débito	4
Tarjeta de Prepago	11
Débito Directo (PAC / Fintoc)	5
EPAC / ForPAC	6
EPAC Directo	14

Webhook de Pagos

Se dispara cada vez que una cuota de un mandato activo es procesada. Puede indicar que el cobro fue exitoso, rechazado, está en proceso o ha sido revertido.

Flujo general de integración

Tu sistema                       Forpay
─────────────────────────────────────────────────────
1. Autenticación        →   GET /login  →  Obtiene JWT
2. Crear usuario        →   POST /user
3. Crear mandato        →   POST /mandate
   (incluye activationWebhook y paymentWebhook)
4. Cliente enrola       ←   Forpay envía POST a activationWebhook
5. Cobro procesado      ←   Forpay envía POST a paymentWebhook

Consideraciones importantes

Todas las notificaciones incluyen un campo signature con una firma HMAC-SHA256 que debes validar para garantizar que el mensaje proviene legítimamente de Forpay. Ver Verificación HMAC.
Tu endpoint debe responder con un código HTTP 2xx para que Forpay registre la notificación como entregada exitosamente.
Si tu endpoint no responde o devuelve un error, Forpay realizará reintentos.
Los datos sensibles (como fileBase64 en activaciones EPAC) deben ser procesados y almacenados de forma segura.