Ruta Base
Todas las solicitudes a las APIs de Forpay deben comenzar con la ruta base /white/label.
Esta ruta es el punto de entrada común para acceder a las distintas funcionalidades que ofrecemos. Asegúrate de incluirla en cada una de tus peticiones para garantizar una correcta integración con nuestra plataforma.
Autenticación
Para utilizar cualquier endpoint de la API de Forpay es necesario acceder con un Bearer Token. Este Token tiene una duración de 30 minutos y se genera al consumir el endpoint /login.
Creación de Compromiso de Pago
La creación de cualquier Compromiso de pago requiere una asociación con un cliente en Forpay. En caso de que el cliente no esté registrado en Forpay, el primer paso para crear un Compromiso de pago consiste en la creación de dicho cliente. Si el cliente al que se planea asociar el compromiso de pago ya está registrado, es posible proceder con la creación del compromiso de pago correspondiente.
Para la creación del cliente se debe consumir el endpoint /user.
Para llevar a cabo la creación de un Compromiso de pago, se requiere utilizar el endpoint/mandate, dependiendo del producto deseado, ya sea un mandato dinámico o permanente.
La respuesta entregada en la creación del Compromiso de pago incluirá la url del Magic Link (punto de contacto para la activación del compromiso). Adicionalmente, se puede solicitar que se envíe dicha url al email registrado en la creación del cliente.
Activación de Compromiso de Pago
El proceso de activación del Compromiso de pago se inicia por la acción de los clientes, quienes autorizan el cobro mediante el medio de pago que han registrado.
Los clientes realizan este proceso mediante el Magic Link de Forpay. Este enlace puede ser accedido desde su portal (como se ilustra en el diagrama) o enviado al correo electrónico registrado durante la creación del cliente, permitiendo que el cliente lo abra desde allí.
activationWebhook
Las notificaciones sobre la activación o anulación de Compromisos de Pago se envían a un webhook que debe proporcionarse en el campo
activationWebhookal momento de crear el compromiso. Este webhook es dinámico y se configura para cada compromiso de manera individual.En el diagrama anterior, este proceso corresponde al paso 'Activation succeeded', que notifica la activación exitosa del Compromiso de pago por parte del cliente.
Cargo de cuotas a mandato
Para agregar nuevas cuotas a un compromiso de pago de tipo Mandato Dinámico, es necesario utilizar el endpoint /installments, como se detalla en el siguiente flujo. Este proceso permite añadir cuotas adicionales a un Mandato Dinámico en cualquier momento, proporcionando flexibilidad en la gestión de los pagos.
Cobro de cuotas
Proceso en el cual se realizan los cobros de las cuotas a los clientes según corresponda. Esto incluye tanto intentos de cobros realizados por el motor de cobros de Forpay, como pagos manuales realizados por clientes.
Cada vez que se realiza un intento de cobro se notifica el resultado del cobro y el estado de la cuota al webhook: paymentWebhook, sin importar cuál haya sido el resultado. Esto permite que sea posible identificar si hay problemas al intentar cobrarle a algún cliente.
paymentWebhook
Las notificaciones sobre los estados de cuotas tras el intento de cobro se realizan a un webhook que debe ser entregado en el campo
paymentWebhooka la hora de crear un compromiso de pago. Es decir, es un webhook dinámico configurado por cada compromiso.
Procesos secundarios
Anulación de compromiso de pago
- Si se desea anular un Compromiso de pago se debe consumir el endpoint de la API V2.0:
/mandate/cancel/{mandateTypeId}/{mandateId}/{userTypeId}/{userId}
Si se cumplen los requisito de anulación, se enviará una notificación al webhook: activationWebhook.
Cambio de estado de cuota
- Si se desea marcar una cuota como anulada o pagada se debe consumir el endpoint de la API V2.0:
/installments/status/change
La diferenciación entre anular o marcar una cuota como pagada se realiza a través del body. Este proceso se explicará en detalle más adelante en la documentación.
Si se cumplen los requisito de cambio de estado, se enviará una notificación con el nuevo estado de la cuota al webhook: paymentWebhook.
Búsqueda de información de un mandato
Para obtener la información de un mandato se debe consumir el endpoint llamado Find dentro de la carpetea Mandate. Esta búsqueda se puede hacer utilizando los id's internos de Forpay o los id's propios del Comercio y traer toda la información del Compromiso de pago, junto a la información de las cuotas y el cliente asociado. La ruta cambiará dependiendo que id se utilice, lo que se explica en mayor profundidad más adelante.