Las APIs de Forpay te permiten automatizar el ciclo de vida completo de los compromisos de pago de tus clientes: desde su creación hasta el cobro y la gestión de estados. A continuación se describen las operaciones principales y adicionales disponibles.
Operaciones principales
1. Crear clientes
Registra en Forpay a los clientes a los que deseas cobrar. Los datos obligatorios son nombre, apellido, RUT y correo electrónico. El RUT es el identificador único del cliente en la plataforma.
Nota: Este proceso se realiza una sola vez por cliente. Si un mismo cliente tiene más de un compromiso de pago, no es necesario volver a crearlo.
Endpoint: POST /white/label/user
2. Crear compromisos de pago
Una vez registrado el cliente, crea el compromiso de pago que define las condiciones del cobro: tipo de mandato, cuotas, montos, fechas y medios de pago permitidos. La respuesta incluye el Magic Link para que el cliente active su medio de pago.
Endpoint: POST /white/label/mandate
3. Activación por el cliente
El cliente accede al Magic Link y registra su medio de pago preferido. Una vez completado este paso, Forpay notifica a tu sistema vía activationWebhook con el detalle de la activación.
4. Cobro automático de cuotas
El motor de cobros de Forpay procesa diariamente las cuotas vencidas de los compromisos activos. Tras cada intento de cobro, se notifica el resultado al paymentWebhook independientemente del resultado (exitoso, rechazado, en proceso, etc.).
5. Carga de cuotas (solo Mandato Dinámico)
Para compromisos de tipo Mandato Dinámico, puedes agregar nuevas cuotas al compromiso en cualquier momento, incluso después de que el cliente lo haya activado.
Endpoint: POST /white/label/installments
Operaciones adicionales
Consultar información de un mandato
Obtén toda la información asociada a un compromiso de pago: datos del cliente, estado del mandato, cuotas y su estado. La búsqueda puede hacerse por IDs internos de Forpay o por los IDs propios de tu sistema.
Endpoint: GET /white/label/mandate/{mandateTypeId}/{mandateId}
Cambiar estado de una cuota
Permite marcar manualmente una cuota como pagada o anulada desde tu sistema. Es útil para conciliar pagos realizados fuera del flujo automático de Forpay (por ejemplo, pagos presenciales o por transferencia manual).
Tras el cambio de estado, Forpay notifica el nuevo estado al paymentWebhook.
Endpoint: POST /white/label/installments/status/change
Anular un compromiso de pago
Cancela definitivamente un compromiso de pago activo. Una vez anulado, no se realizarán más cobros y Forpay notificará el cambio al activationWebhook.
Endpoint: DELETE /white/label/mandate/cancel/{mandateTypeId}/{mandateId}/USERTYPEID/USERID
Resumen del ciclo completo
[Empresa crea cliente]
↓
[Empresa crea mandato] ←── incluye activationWebhook y paymentWebhook
↓
[Magic Link → Cliente activa medio de pago]
↓
[Forpay notifica activación → activationWebhook]
↓
[Motor de cobros procesa cuotas diariamente]
↓
[Forpay notifica resultado → paymentWebhook]
↓
[Empresa gestiona estados, conciliación y anulaciones]Es importante considerar que pueden existir pagos —y sus respectivas notificaciones— antes de que el cliente utilice el Magic Link para enrolar su medio de pago, dado que el pago también puede realizarse de forma manual mendiante notificaciones o por el Portal de Pagos.