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. Las rutas se presentan según la convención de URL base y rutas.
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 El cliente debe estar asociado al comercio en el ambiente correspondiente.
POST /userregistra al usuario que falta o gestiona su asociación. Si ya está asociado, una respuesta exitosa puede conservar su nombre y datos de contacto existentes.
Endpoint: POST /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 /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 envía el detalle de activación al activationWebhook configurado cuando ese evento está habilitado para el comercio.
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 /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 /mandate/internalId/{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).
La operación devuelve 204 No Content cuando finaliza satisfactoriamente.
Endpoint: PUT /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 /mandate/cancel/internalId/{mandateId}/internalUserId/{internalUserId}?description={motivo}
Envía description en la query como una cadena no vacía con el motivo de cancelación.
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]Pueden registrarse pagos y sus notificaciones antes de que el cliente inscriba un medio recurrente mediante el Magic Link. Por ejemplo, el cliente puede realizar un pago manual desde una notificación o desde el Portal de Pagos.