Esta sección describe el flujo técnico completo para integrar con las APIs de Forpay: desde la autenticación hasta el cobro de cuotas y los procesos secundarios.
Ruta base
Todas las solicitudes a la API deben comenzar con:
https://devapi.forpayservices.cl/white/label1. Autenticación
Antes de consumir cualquier endpoint es necesario obtener un Bearer JWT. Este token tiene una duración de 30 minutos y se obtiene desde el endpoint de login.
GET /white/label/loginEl token debe incluirse en el header Authorization de todas las solicitudes posteriores:
Authorization: Bearer <tu_token>Ver Autenticación para el detalle completo del proceso de login con JWE.
2. Crear cliente
Si el cliente aún no existe en Forpay, créalo antes de crear cualquier compromiso de pago.
POST /white/label/userCampos obligatorios: nombre, apellido, RUT y correo electrónico. El RUT es el identificador único del cliente y no puede duplicarse.
3. Crear compromiso de pago
Crea el mandato asociando al cliente previamente creado. En el body debes incluir:
- El tipo de mandato (
type):DYNAMIC,PERMANENToSUBSCRIPTION. - Las URLs de webhook:
activationWebhookypaymentWebhook. - El parámetro
white_labelpara controlar quién gestiona las notificaciones al cliente (ver Parámetro white_label). - Las cuotas iniciales (para Mandato Permanente) o el contrato base (para Mandato Dinámico).
POST /white/label/mandateLa respuesta incluirá el Magic Link para que el cliente active su compromiso.
4. Activación del compromiso
El cliente accede al Magic Link y registra su medio de pago. Este proceso es asincrónico: cuando el cliente completa la activación, Forpay envía una notificación al activationWebhook que configuraste al crear el mandato.
Ver Notificaciones de Activación para los payloads según el medio de pago.
5. Cargar cuotas (Mandato Dinámico)
Para mandatos de tipo dinámico, puedes agregar cuotas en cualquier momento después de la creación:
POST /white/label/installmentsEs posible agregar múltiples cuotas en una sola llamada y en cualquier momento del ciclo de vida del mandato.
6. Cobro de cuotas
El motor de cobros de Forpay procesa automáticamente las cuotas cuya fecha de vencimiento corresponda al día. Tras cada intento, Forpay notifica el resultado al paymentWebhook sin importar si el cobro fue exitoso o no.
Ver Notificaciones de Pago para los payloads según el medio de pago y el estado.
Procesos secundarios
Anular un compromiso de pago
DELETE /white/label/mandate/cancel/{mandateTypeId}/{mandateId}/USERTYPEID/USERIDCancela el compromiso y detiene futuros cobros. Forpay notifica la anulación al activationWebhook.
Cambiar el estado de una cuota
POST /white/label/installments/status/changePermite marcar una cuota como pagada (state: 2) o anulada (state: 6) desde tu sistema. El nuevo estado es notificado al paymentWebhook.
Consultar un mandato
GET /white/label/mandate/internalId/{mandateId} // ID generado por Forpay
GET /white/label/mandate/id/{mandateExternalId} // ID asignado por tiRetorna toda la información del compromiso: datos del cliente, estado del mandato, cuotas y sus estados. La búsqueda puede hacerse por IDs internos de Forpay o por los IDs externos de tu sistema.
Diagrama de flujo completo
┌───────────────────────────────────────────────────────── ┐
│ Tu sistema Forpay │
├───────────────────────────────────────────────────────── ┤
│ GET /login → Obtiene JWT │
│ POST /user → Crea cliente │
│ POST /mandate → Crea mandato │
│ ← Retorna Magic Link │
│ (envías link al cliente) │
│ (cliente abre Magic Link y activa medio de pago) │
│ ← POST activationWebhook │
│ POST /installments → Agrega cuotas (dinámico) │
│ ← Motor cobra cuotas │
│ ← POST paymentWebhook │
│ GET /mandate/{id} → Consulta estado │
│ POST /installments/... → Cambia estado cuota │
│ DELETE /mandate/cancel/ → Anula mandato │
│ ← POST activationWebhook │
└───────────────────────────────────────────────────────── ┘