Botón de Pago - Hook

Los botones de pago personalizados ofrecen la posibilidad de enviar notificaciones cuando se realiza un pago exitoso, esto se logra mediante la configuración de un hook.

Activar Hook para un Botón de Pago

Activar un hook toma solo 2 pasos:

Definir la credencial predeterminada para hooks, que se utilizará para firmar cada solicitud y te permitirá validar la autenticidad de la información.
Configurar el URL al cual enviaremos las solicitudes.

Para utilizar el Hook, primero debes crear un botón de pago dinámico: Ver Tutorial

1. Definir una Credencial Predeterminada para Hooks

Para definirla ingresa en Configuración > Credenciales API



En el ejemplo de arriba podemos ver la opción donde escogeremos de una lista desplegable, la credencial que usaremos por defecto para los hooks.

2. Configurar el URL de tu Sistema

El segundo paso es configurar la ruta a la cual se harán las solicitudes cada vez que se reciban pagos exitosos en un botón de pago personalizado. Algunas consideraciones a tener presente:

Debe ser una ruta pública (accesible desde Internet).
Debe tener un certificado de seguridad válido (ruta debe utilizar HTTPS).

Para configurar el URL, simplemente ingresa a el/los botones de pago en los que quieres activar el Hook, haz click en editar y posteriormente en “Opciones Avanzadas”.

Una vez en las Opciones Avanzadas encontrarás un campo llamado “URL del Hook” donde podrás colocar la ruta.

Referencia Técnica

Cuando se activa un Hook, Fygaro enviará una solicitud tipo “POST” al URL configurado cada vez que se procese un pago exitoso en el botón de pago respectivo. La solicitud tendrá un contenido de tipo JSON con la siguiente estructura:

{ “reference”: (string), “customReference”: (string), “createdAt”: (int), “jwt”: (string)}

"reference" contiene el identificador único de referencia que se asigna a toda transacción en Fygaro.

"customReference" contiene la referencia dinámica asignada al crear o compartir el botón de pago por un parámetro del URL.

"createdAt" contiene el timestamp que refleja con el momento en el que el cliente inició el pago.

"jwt" contiene un token en formato “Json Web Token” (JWT por sus siglas) con la información detallada de la transacción.

*

Campos Deprecados:

No utilizar, serán eliminados en el futuro.

"transactionReference" contiene el "auth code" del banco adquirente (si aplica). Se recomienda utilizar como alternativa el campo "reference" como identificador único.

El formato JWT te permitirá garantizar la integridad y fuente de la información suministrada gracias a la firma que se crea utilizando la credencial definida en el capítulo anterior. Para más información sobre el formato, puede visitar: https://jwt.io/.

Antes de obtener la información contenida dentro del JWT, se recomienda validar el mismo utilizando las credenciales previamente definidas. Una vez se determina válido, puede acceder al cuerpo del token, donde encontrará la siguiente información:

{ "reference": (string),    "customReference": (string),   "authCode": (string),    "currency": (string),    "amount": (string),    "gratuity_amount": (string),    "createdAt": (int),    "clientData": (dict),      "transactionId": (string)}

"reference" es una copia validada del campo anteriormente descrito.

"customReference" es una copia validada del campo anteriormente descrito.

"authCode" contiene el "auth code" provisto por el banco adquirente. En caso de no poseer ese valor, el campo se asigna a null.

"createdAt" es una copia validada del campo anteriormente descrito.

"currency" contiene el código alfabético ISO de 3 caracteres que representa la divisa utilizada en el pago (ej: “USD”).

"amount" contiene el monto de la transacción en formato “Decimal” de hasta 2 caracteres.

"gratuity_amount" (si disponible) contiene el monto de la propina de la transacción en formato “Decimal” de hasta 2 caracteres.

"transactionId" un UUID que identifica la transacción.

"clientData" es un diccionario que contiene la información del cliente que realizó la compra. Su estructura es la siguiente:

{    "name": (string),    "email": (string),     "phone": (string)}

"name": nombre y apellido ingresado por el cliente al realizar el pago.

"email": Correo electrónico ingresado por el cliente al realizar el pago.

"phone": Teléfono ingresado por el cliente al realizar el pago.

*

Campos Deprecados:

No utilizar, serán eliminados en el futuro.

"transactionReference" es una copia validada del campo anteriormente descrito. Se recomienda utilizar en su lugar el campo "reference" (identificador único) y el campo "authCode" ("auth code" del banco adquirente, si hay) en su lugar.

Respuesta al Hook

Las solicitudes realizadas al URL solicitado esperan una respuesta de éxito utilizando el status 200. Cualquier otro status de respuesta o time-out será considerado un fallo y la solicitud será re-intentada posteriormente.

Una misma solicitud se intentará hasta 4 veces, cada intento con más tiempo de separación que el anterior para permitir a su sistema recuperarse en caso de errores o caídas.

Favor tome en cuenta que múltiples solicitudes consecutivas fallidas pueden causar una suspensión temporal en el envío de nuevas solicitudes del mismo botón de pago. Suspensiones reiterativas pueden generar un bloqueo permanente del Hook.

Actualizado el: 30/04/2025