Webhooks

Los webhooks de TropiPay te permiten recibir notificaciones en tiempo real sobre eventos que ocurren en tu cuenta. Esto es especialmente útil para mantener tus sistemas sincronizados con los eventos de TropiPay, como pagos recibidos, transacciones completadas, cambios de estado de tarjetas y más.

¿Qué son los webhooks?

Los webhooks son callbacks HTTP que se envían a una URL específica cuando ocurren ciertos eventos en tu cuenta de TropiPay. En lugar de tener que consultar constantemente la API para verificar si algo ha cambiado, los webhooks te notifican automáticamente cuando ocurre algo relevante.

Beneficios de usar webhooks

Tiempo real: Recibe notificaciones inmediatas cuando ocurren eventos
Eficiencia: Reduce la necesidad de sondeos periódicos de la API
Automatización: Permite flujos de trabajo automatizados basados en eventos de TropiPay
Sincronización: Mantén tus sistemas actualizados con los datos más recientes

El objeto Webhook Event

Todas las notificaciones webhook tienen la siguiente estructura básica:

{
  "event": "payment.completed",
  "data": {
    "id": "pay_123456789",
    "amount": 10000,
    "currency": "EUR",
    "status": "completed",
    "created_at": "2023-07-22T12:30:00.000Z",
    "completed_at": "2023-07-22T12:34:56.789Z",
    "metadata": {
      "order_id": "order_987654321"
    }
  },
  "timestamp": "2023-07-22T12:34:56.789Z"
}

Atributos

Atributo	Tipo	Descripción
`event`	string	Nombre del evento que disparó el webhook
`data`	object	Payload de datos específico del evento
`timestamp`	string	Marca temporal ISO 8601 de cuándo ocurrió el evento

Tipos de eventos

Eventos de pago

Evento	Descripción
`payment.created`	Se ha creado un nuevo pago
`payment.completed`	Un pago se ha completado exitosamente
`payment.failed`	Un pago ha fallado
`payment.refunded`	Un pago ha sido reembolsado

Eventos de tarjeta

Evento	Descripción
`card.created`	Se ha creado una nueva tarjeta
`card.activated`	Una tarjeta ha sido activada
`card.blocked`	Una tarjeta ha sido bloqueada
`card.transaction`	Se ha realizado una transacción con una tarjeta

Eventos de cuenta

Evento	Descripción
`account.updated`	Los datos de la cuenta han sido actualizados
`account.verified`	La cuenta ha sido verificada
`account.login`	Ha ocurrido un inicio de sesión en la cuenta

Hooks de comerciante

Los hooks de comerciante son webhooks gestionados a nivel del comerciante/negocio. Estos endpoints te permiten gestionar las suscripciones a webhooks para tu cuenta de comerciante.

Listar hooks de comerciante

Devuelve una lista de todos los eventos a los que el comerciante está suscrito mediante webhooks.

GET/merchant/hooks

curl -X GET https://sandbox.tropipay.me/api/v3/merchant/hooks \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json"

Respuesta

[
  {
    "event": "user_signup",
    "target": "email",
    "value": "user@example.com",
    "createdAt": "2021-02-13T21:30:59.154Z",
    "updatedAt": "2021-02-13T21:30:59.154Z"
  },
  {
    "event": "payment_created",
    "target": "web",
    "value": "https://example.com/webhooks/payment-created",
    "createdAt": "2021-02-13T21:30:59.154Z",
    "updatedAt": "2021-02-13T21:30:59.154Z"
  }
]

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`event`	string	Nombre del evento suscrito
`target`	string	Tipo de objetivo del webhook (`web`, `email`)
`value`	string	Valor del objetivo (URL para web, dirección de correo para email)
`createdAt`	string	Marca temporal ISO 8601 de creación de la suscripción
`updatedAt`	string	Marca temporal ISO 8601 de la última actualización de la suscripción

Suscribirse a un evento de merchant

Permite a un comerciante suscribirse a un evento, especificando las opciones para recibir la información en el momento en que se dispara.

POST/merchant/hooks

curl -X POST https://sandbox.tropipay.me/api/v3/merchant/hooks \
  -H "Authorization: Bearer {merchant-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "event": "user_signup",
    "target": "web",
    "value": "https://www.merchant_domain.com/api/user/signup/listen"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
`event`	string	Sí	Cadena que representa el nombre del evento. Debes seleccionar de la lista de eventos disponibles; de lo contrario, no producirá un error pero no se ejecutará. Para la lista completa de eventos disponibles consulta el endpoint `GET /hook/events`.
`target`	string	Sí	Cadena que representa el tipo de evento soportado. Actualmente disponibles: `web` (permite recibir información en una URL), `email` (permite recibir información en una dirección de correo electrónico).
`value`	string	Sí	Cadena que representa el valor dependiendo del tipo de evento seleccionado determinado por la propiedad 'target'. Por ejemplo, si el 'target' seleccionado es `email` el valor sería una dirección de correo electrónico; así mismo, si el 'target' seleccionado es `web` el valor esperado corresponde a una URL que recibe información a través del método HTTP POST.

Respuesta

Código de estado: 200 OK

{
  "action": "update",
  "status": "success",
  "details": "user_signup"
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`action`	string	La acción realizada (por ejemplo, "update")
`status`	string	Estado de la operación ("success" o "error")
`details`	string	Detalles adicionales sobre la operación, típicamente el nombre del evento

Actualizar suscripción de hook de comerciante

Permite a un comerciante actualizar una suscripción a un evento, especificando las opciones para recibir la información en el momento en que se dispara. Ten en cuenta que no se puede modificar el valor del nombre o denominación del evento. En caso de que sea necesario cambiar este campo, se recomienda eliminarlo y crear una nueva suscripción.

PUT/merchant/hooks

curl -X PUT https://sandbox.tropipay.me/api/v3/merchant/hooks \
  -H "Authorization: Bearer {merchant-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "event": "user_signup",
    "target": "email",
    "value": "merchant@example.com"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
`event`	string	Sí	Cadena que representa el nombre del evento. Este campo no puede ser modificado; si necesitas cambiar el evento, elimina la suscripción y crea una nueva.
`target`	string	Sí	Cadena que representa el tipo de evento soportado. Actualmente disponibles: `web` (permite recibir información en una URL), `email` (permite recibir información en una dirección de correo electrónico).
`value`	string	Sí	Cadena que representa el valor dependiendo del tipo de evento seleccionado determinado por la propiedad 'target'. Por ejemplo, si el 'target' seleccionado es `email` el valor sería una dirección de correo electrónico; así mismo, si el 'target' seleccionado es `web` el valor esperado corresponde a una URL.

Respuesta

Código de estado: 200 OK

{
  "action": "update",
  "status": "success",
  "details": "user_signup"
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`action`	string	La acción realizada ("update")
`status`	string	Estado de la operación ("success" o "error")
`details`	string	Detalles adicionales sobre la operación, típicamente el nombre del evento

Eliminar suscripción de hook de comerciante

Permite a un comerciante darse de baja de un evento por nombre o denominación.

DELETE/merchant/hooks

curl -X DELETE https://sandbox.tropipay.me/api/v3/merchant/hooks \
  -H "Authorization: Bearer {merchant-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "event": "user_signup"
  }'

Parámetros

Parámetro	Tipo	Requerido	Descripción
`event`	string	Sí	Cadena que representa el nombre del evento del cual darse de baja

Respuesta

Código de estado: 200 OK

{
  "action": "update",
  "status": "success",
  "details": "user_signup"
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`action`	string	La acción realizada ("update")
`status`	string	Estado de la operación ("success" o "error")
`details`	string	Detalles adicionales sobre la operación, típicamente el nombre del evento

Obtener eventos disponibles para merchant

Endpoint para obtener la lista completa de eventos disponibles que permiten suscripción para los hooks de comerciante.

GET/merchant/hooks/events

curl -X GET https://sandbox.tropipay.me/api/v3/merchant/hooks/events \
  -H "Authorization: Bearer {merchant-token}" \
  -H "Accept: application/json"

Respuesta

Código de estado: 200 OK

[
  {
    "name": "user_signup",
    "description": "Event launched once a user completes registration on the TropiPay platform."
  },
  {
    "name": "user_login",
    "description": "Event launched once a user completes login on the TropiPay platform."
  },
  {
    "name": "user_kyc",
    "description": "Event launched once a user completes KYC process, indicated in each case the process status."
  },
  {
    "name": "payment_in_state_change",
    "description": "The event is fired once a user changes their status payment in entry method."
  },
  {
    "name": "payment_out_state_change",
    "description": "The event is fired once a user changes their status payment out entry method."
  }
]

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`name`	string	El nombre del evento al cual se puede suscribir
`description`	string	Descripción detallada de cuándo se dispara el evento

Eventos disponibles

Los eventos están compuestos por un objeto con dos propiedades fundamentales (name, description):

user_signup: Evento lanzado una vez que un usuario completa el registro en la plataforma TropiPay.
user_login: Evento lanzado una vez que un usuario completa el inicio de sesión en la plataforma TropiPay.
user_kyc: Evento lanzado una vez que un usuario completa el proceso KYC, indicando en cada caso el estado del proceso. El payload de respuesta incluye:
```
{
  "userId": "string",
  "status": "string",
  "event": "string",
  "user": {}
}
```
payment_in_state_change: El evento se dispara cuando un usuario cambia el estado de su método de pago de entrada.
payment_out_state_change: El evento se dispara cuando un usuario cambia el estado de su método de pago de salida.

Hooks de usuario

Los hooks de usuario son webhooks gestionados a nivel de usuario individual. Estos endpoints permiten a los usuarios gestionar sus suscripciones personales a webhooks.

Listar hooks de usuario

Devuelve una lista de suscripciones a hooks de usuario para el usuario autenticado.

GET/user/hooks

curl -X GET https://sandbox.tropipay.me/api/v3/user/hooks \
  -H "Authorization: Bearer {user-token}" \
  -H "Accept: application/json"

Respuesta

Código de estado: 200 OK

[
  {
    "event": "user_login",
    "target": "web",
    "value": "https://webhook.site/680826a5-199e-4455-babc-f47b7f26ee7e",
    "createdAt": "2022-02-11T18:36:48.300Z",
    "updatedAt": "2022-02-11T18:36:48.300Z"
  },
  {
    "event": "user_kyc",
    "target": "email",
    "value": "user@example.com",
    "createdAt": "2022-02-11T18:53:30.397Z",
    "updatedAt": "2022-02-11T18:53:30.397Z"
  },
  {
    "event": "beneficiary_added",
    "target": "email",
    "value": "user@example.com",
    "createdAt": "2022-02-11T18:53:54.027Z",
    "updatedAt": "2022-02-11T18:53:54.027Z"
  }
]

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`event`	string	Nombre del evento suscrito
`target`	string	Tipo de objetivo del webhook (`web`, `email`)
`value`	string	Valor del objetivo (URL para web, dirección de correo para email)
`createdAt`	string	Marca temporal ISO 8601 de creación de la suscripción
`updatedAt`	string	Marca temporal ISO 8601 de la última actualización de la suscripción

Crear hook de usuario

Inserta un hook de usuario para suscribirse a eventos webhook.

POST/user/hooks

curl -X POST https://sandbox.tropipay.me/api/v3/user/hooks \
  -H "Authorization: Bearer {user-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "event": "user_login",
    "target": "web",
    "value": "https://webhook.site/680826a5-199e-4455-babc-f47b7f26ee7e"
  }'

Parámetros

Los eventos están compuestos por un objeto con tres propiedades fundamentales (event, target, value):

Parámetro	Tipo	Requerido	Descripción
`event`	string	Sí	Cadena que representa el nombre del evento. Debes seleccionar de la lista de eventos disponibles; de lo contrario, no producirá un error pero no se ejecutará. Para la lista completa de eventos disponibles consulta el endpoint `GET /user/hooks/events`.
`target`	string	Sí	Cadena que representa el tipo de evento soportado. Actualmente disponibles: `web` (permite recibir información en una URL), `email` (permite recibir información en una dirección de correo electrónico).
`value`	string	Sí	Cadena que representa el valor dependiendo del tipo de evento seleccionado determinado por la propiedad 'target'. Por ejemplo, si el 'target' seleccionado es `email` el valor sería una dirección de correo electrónico; así mismo, si el 'target' seleccionado es `web` el valor esperado corresponde a una URL que recibe información a través del método HTTP POST.

Respuesta

Código de estado: 200 OK

En general, las respuestas válidas se definen como un objeto con tres propiedades elementales:

{
  "action": "subscribe",
  "status": "success",
  "details": "user_login"
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`action`	string	Representa el tipo de operación que se acaba de ejecutar
`status`	string	Representa el estado de la operación, tomando el valor `success` en caso de que todo vaya bien
`details`	string	Muestra valores adicionales relacionados con la operación, normalmente devuelve el nombre del evento

Actualizar hook de usuario

Actualización explícita de hook en el payload de la solicitud.

PUT/user/hooks

curl -X PUT https://sandbox.tropipay.me/api/v3/user/hooks \
  -H "Authorization: Bearer {user-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "event": "user_login",
    "target": "email",
    "value": "user@example.com"
  }'

Parámetros

Los eventos están compuestos por un objeto con tres propiedades fundamentales (event, target, value):

Parámetro	Tipo	Requerido	Descripción
`event`	string	Sí	Cadena que representa el nombre del evento. Debes seleccionar de la lista de eventos disponibles; de lo contrario, no producirá un error pero no se ejecutará. Para la lista completa de eventos disponibles consulta el endpoint `GET /user/hooks/events`.
`target`	string	Sí	Cadena que representa el tipo de evento soportado. Actualmente disponibles: `web` (permite recibir información en una URL), `email` (permite recibir información en una dirección de correo electrónico).
`value`	string	Sí	Cadena que representa el valor dependiendo del tipo de evento seleccionado determinado por la propiedad 'target'. Por ejemplo, si el 'target' seleccionado es `email` el valor sería una dirección de correo electrónico; así mismo, si el 'target' seleccionado es `web` el valor esperado corresponde a una URL que recibe información a través del método HTTP POST.

Respuesta

Código de estado: 200 OK

En general, las respuestas válidas se definen como un objeto con tres propiedades elementales:

{
  "action": "update",
  "status": "success",
  "details": "user_login"
}

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`action`	string	Representa el tipo de operación que se acaba de ejecutar
`status`	string	Representa el estado de la operación, tomando el valor `success` en caso de que todo vaya bien
`details`	string	Muestra valores adicionales relacionados con la operación, normalmente devuelve el nombre del evento

Obtener eventos disponibles para usuario

Obtiene la lista de eventos de hook de usuario.

GET/user/hooks/events

curl -X GET https://sandbox.tropipay.me/api/v3/user/hooks/events \
  -H "Authorization: Bearer {user-token}" \
  -H "Accept: application/json"

Respuesta

Código de estado: 200 OK

[
  {
    "name": "user_signup",
    "description": "Event launched once a user completes registration on the TropiPay platform."
  },
  {
    "name": "user_login",
    "description": "Event launched once a user completes login on the TropiPay platform."
  },
  {
    "name": "user_kyc",
    "description": "Event launched once a user completes kyc process."
  },
  {
    "name": "payment_in_state_change",
    "description": "The event is fired once a user changes their status payment in entry method."
  },
  {
    "name": "payment_out_state_change",
    "description": "The event is fired once a user changes their status payment out entry method."
  },
  {
    "name": "beneficiary_added",
    "description": "Launched after new beneficiary is created."
  },
  {
    "name": "beneficiary_updated",
    "description": "Launched after a beneficiary is modified."
  },
  {
    "name": "beneficiary_deleted",
    "description": "Launched after a beneficiary is deleted."
  }
]

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`name`	string	El nombre del evento al cual se puede suscribir
`description`	string	Descripción detallada de cuándo se dispara el evento

Eventos disponibles

Los siguientes eventos están disponibles para suscripciones de hooks de usuario:

user_signup: Evento lanzado una vez que un usuario completa el registro en la plataforma TropiPay.
user_login: Evento lanzado una vez que un usuario completa el inicio de sesión en la plataforma TropiPay.
user_kyc: Evento lanzado una vez que un usuario completa el proceso KYC.
payment_in_state_change: El evento se dispara cuando un usuario cambia el estado de su método de pago de entrada.
payment_out_state_change: El evento se dispara cuando un usuario cambia el estado de su método de pago de salida.
beneficiary_added: Lanzado después de que se crea un nuevo beneficiario.
beneficiary_updated: Lanzado después de que se modifica un beneficiario.
beneficiary_deleted: Lanzado después de que se elimina un beneficiario.

Obtener hook de usuario específico

Selecciona todos los hooks suscritos a un nombre de evento dado. La URL para un cierto nombre de evento sería la siguiente /user/hooks/user_login. Para el caso anterior, se obtendrían todos los hooks asociados al evento user_login, donde básicamente se devolvería una lista en la que cambiarían el target y el valor asociado.

GET/user/hooks/{event_name}

curl -X GET https://sandbox.tropipay.me/api/v3/user/hooks/user_login \
  -H "Authorization: Bearer {user-token}" \
  -H "Accept: application/json"

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`event_name`	string	Sí	El nombre del evento para el cual recuperar los hooks (por ejemplo, `user_login`, `user_signup`, `beneficiary_added`)

Respuesta

Código de estado: 200 OK

[
  {
    "event": "user_login",
    "target": "web",
    "value": "https://webhook.site/680826a5-199e-4455-babc-f47b7f26ee7e",
    "createdAt": "2022-02-11T18:36:48.300Z",
    "updatedAt": "2022-02-11T18:36:48.300Z"
  },
  {
    "event": "user_login",
    "target": "email",
    "value": "user@example.com",
    "createdAt": "2022-02-11T18:43:24.882Z",
    "updatedAt": "2022-02-11T18:43:24.882Z"
  }
]

Parámetros de la respuesta

Parámetro	Tipo	Descripción
`event`	string	Nombre del evento suscrito
`target`	string	Tipo de objetivo del webhook (`web`, `email`)
`value`	string	Valor del objetivo (URL para web, dirección de correo para email)
`createdAt`	string	Marca temporal ISO 8601 de creación de la suscripción
`updatedAt`	string	Marca temporal ISO 8601 de la última actualización de la suscripción

¿Qué son los webhooks?​

Beneficios de usar webhooks​

El objeto Webhook Event​

Atributos​

Tipos de eventos​

Eventos de pago​

Eventos de tarjeta​

Eventos de cuenta​

Hooks de comerciante​

Listar hooks de comerciante​

Respuesta​

Parámetros de la respuesta​

Suscribirse a un evento de merchant​

Parámetros​

Respuesta​

Parámetros de la respuesta​

Actualizar suscripción de hook de comerciante​

Parámetros​

Respuesta​

Parámetros de la respuesta​

Eliminar suscripción de hook de comerciante​

Parámetros​

Respuesta​

Parámetros de la respuesta​

Obtener eventos disponibles para merchant​

Respuesta​

Parámetros de la respuesta​

Eventos disponibles​

Hooks de usuario​

Listar hooks de usuario​

Respuesta​

Parámetros de la respuesta​

Crear hook de usuario​

Parámetros​

Respuesta​

Parámetros de la respuesta​

Actualizar hook de usuario​

Parámetros​

Respuesta​

Parámetros de la respuesta​

Obtener eventos disponibles para usuario​

Respuesta​

Parámetros de la respuesta​

Eventos disponibles​

Obtener hook de usuario específico​

Parámetros de ruta​

Respuesta​

Parámetros de la respuesta​

¿Qué son los webhooks?

Beneficios de usar webhooks

El objeto Webhook Event

Atributos

Tipos de eventos

Eventos de pago

Eventos de tarjeta

Eventos de cuenta

Hooks de comerciante

Listar hooks de comerciante

Respuesta

Parámetros de la respuesta

Suscribirse a un evento de merchant

Parámetros

Respuesta

Parámetros de la respuesta

Actualizar suscripción de hook de comerciante

Parámetros

Respuesta

Parámetros de la respuesta

Eliminar suscripción de hook de comerciante

Parámetros

Respuesta

Parámetros de la respuesta

Obtener eventos disponibles para merchant

Respuesta

Parámetros de la respuesta

Eventos disponibles

Hooks de usuario

Listar hooks de usuario

Respuesta

Parámetros de la respuesta

Crear hook de usuario

Parámetros

Respuesta

Parámetros de la respuesta

Actualizar hook de usuario

Parámetros

Respuesta

Parámetros de la respuesta

Obtener eventos disponibles para usuario

Respuesta

Parámetros de la respuesta

Eventos disponibles

Obtener hook de usuario específico

Parámetros de ruta

Respuesta

Parámetros de la respuesta