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/label

1. 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/login

El 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/user

Campos 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, PERMANENT o SUBSCRIPTION.
Las URLs de webhook: activationWebhook y paymentWebhook.
El parámetro white_label para 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/mandate

La 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/installments

Es 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}/{userId}

Cancela el compromiso y detiene futuros cobros. Forpay notifica la anulación al activationWebhook.

Cambiar el estado de una cuota

POST /white/label/installments/status/change

Permite 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 ti

Retorna 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      │
└───────────────────────────────────────────────────────── ┘