¿Cómo ocupar las APIs Forpay?

Autenticación

Para utilizar cualquier endpoint de la API V 2.0 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 /white/label/login.

Creación de Compromiso de Pago

La creación de cualquier compromiso de pago requiere una asociación con un usuario en Forpay. En caso de que el usuario no esté registrado en Forpay, el primer paso para crear un compromiso de pago consiste en la creación de dicho usuario. Si el usuario 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 usuario se debe consumir el endpoint /white/label/user.

Para llevar a cabo la creación de un compromiso de pago, se requiere utilizar el endpoint/white/label/payment-plan o /white/label/mandate, dependiendo del producto deseado, ya sea un plan de pago o un mandato, respectivamente.

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 usuario.

📘

¿Cómo crear un Mandato de Pago único?

Al configurar un mandato, también puedes especificar si se trata de un proceso de un único cargo automático.

• Para esto se debe configurar un mandato con los siguientes valores: type: PERMANENT , terminateWhenCharged: true y needPayNow: true. Además, todas las cuotas creadas deben tener el campo payNow con valor true, las que se intentaran cobrar automáticamente al enrolar el medio de pago.
• Si se desea configurar un pago único con múltiples cargos que se distribuya entre distintas tiendas con diferentes códigos comercio, es necesario crear el mandato con el campoisMall: true. En esta configuración cada cargo puede ser asociada a una tienda diferente. Para lograr esto, es necesario incluir en el campo installment.metadata la clavef_commerceCode con el código de comercio tienda al cual se desea hacer el cargo. Además, si se desea cobrar en más de una cuota comercio, es necesario incluir la clave f_installmentsNumber con la cantidad de cuotas comercio.

Activación de Compromiso de Pago

El proceso de activación de compromiso de pago se inicia por la acción de los usuarios, quienes autorizan el cobro mediante el medio de pago que han registrado.

Sus usuarios 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 usuario, permitiendo que el usuario lo abra desde allí.

El paso llamado Activation succeeded es un paso asincrónico en el que se notifica que su usuario ha completado exitosamente el proceso de activación al webhook: activationWebhook.

📘

activationWebhook

Las notificaciones sobre la activación o anulación de planes de pagos se realizan a un webhook que debe ser entregado en el campo activationWebhook a la hora de crear un compromiso de pago. Es decir, es un webhook dinámico configurado por cada compromiso.

Se solicitan dos url de webhook para que Forpay pueda enviar notificaciones. Uno para las notificaciones de cambios de estados de cuotas y otro para las notificaciones de cambios de estados de compromisos de pagos.

Cargo de cuotas a mandato

Para la carga de nuevas cuotas de un compromiso de pago tipo mandato se debe consumir el endpoint /white/label/installments según se ve en el siguiente flujo. Es posible agregar cuotas adicionales a un mandato en cualquier momento.

Cobro de cuotas

Proceso en el cual se gestionan los cobros a sus usuarios. Esto incluye tanto cobros recurrentes de las cuotas como pagos manuales. 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 sus usuarios.

📘

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 paymentWebhook a la hora de crear un compromiso de pago. Es decir, es un webhook dinámico configurado por cada compromiso.

Se solicitan dos url de webhook para que Forpay pueda enviar notificaciones. Uno para las notificaciones de cambios de estados de cuotas y otro para las notificaciones de cambios de estados de compromisos de pagos.

Actualización de estado de un compromiso de pago o cuota desde el comercio

Anulación de compromiso de pago

• Si se desea anular un mandato se debe consumir el endpoint de la API V2.0: /white/label/mandate/cancel/{mandateTypeId}/{mandateId}/{userTypeId}/{userId}
• Si se desea anular un plan de pago se debe consumir el endpoint de la API V1.0: /external/notification/state/payment-plan

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 de un mandato como anulada o pagada se debe consumir el endpoint de la API V2.0: /white/label/installments/status/change
• Si se desea marcar una cuota de un plan de pago como anulada o pagada se debe consumir el endpoint de la API V1.0: /external/notification/state/installment

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 trae toda la información del mandato, junto a la información de las cuotas y el usuario asociado.