Webhooks de Pago (México)

Configurando tus webhooks

Para configurar tu URL de webhook:

Inicia sesión en tu Portal de Débito Directo. (Inicio de sesión Sandbox | Inicio de sesión Producción)
Ve a Desarrolladores -> Webhooks. (Webhooks Sandbox | Webhooks Producción)
Ingresa tu URL.
Haz clic en Set.

✅ Tu URL de webhook se ha agregado exitosamente.

Eventos de webhook

{
  "eventType": "payment_request_update", // Tipo de evento del recurso de la API
  "eventCode": "payment_request_successful", // Código del evento de webhook
  "datetime": "2022-01-01T12:34:56.789Z", // La marca de tiempo ISO-8601 cuando se envió el evento.
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // ID del objeto del recurso de la API.
    "reference": "your_reference_here", // Descripción opcional del objeto
    "status": "failed", // El estado del recurso
    "failedReason": "BANK_CODE", // Si status=failed, un código de falla
    "failedMessage": "A description of the error" // Si status=failed, una descripción de la falla.
  }
}

failedReason and failedMessage fields

Para obtener detalles sobre los failedReason y failedMessage esperados (incluida la lista de valores posibles), consulte nuestra guía de Errores Bancarios de Débito Directo.

Para obtener información sobre cargas útiles específicas para un recurso de API y código de webhook dado, simplemente haga clic en el Código del Evento de webhook en la tabla a continuación.

Recurso	Código del Evento	Enviado siempre que...
Métodos de Pago	`payment_method_registration_successful`	el registro del método de pago de débito directo fue exitoso.
Métodos de Pago	`payment_method_registration_failed`	el registro del método de pago de débito directo falló.
Métodos de Pago	`payment_method_registration_canceled`	el registro de débito directo fue cancelado (generalmente por el propietario).
Solicitudes de Pago	`payment_request_successful`	el pago fue exitoso y recibimos confirmación del proveedor de infraestructura de pago.
Solicitudes de Pago	`payment_request_failed`	un error es reportado por el proveedor de infraestructura de pago.
Solicitudes de Pago	`payment_request_chargeback`	se ha realizado un contracargo por parte de su cliente.

Mejores Prácticas

Cuando recibas un webhook de Belvo, asegúrate de responder con un código de estado 2XX (por ejemplo, un 200). Si el sistema de Belvo no recibe una respuesta 200 de tu servidor, automáticamente intentaremos enviar la solicitud nuevamente. Para más detalles, consulta nuestra sección de Política de reintentos.

Política de reintento

Cuando Belvo no recibe una respuesta 2XX de tu servidor, intentamos enviar el webhook cada 60 minutos hasta un máximo de 10 intentos.

Por ejemplo, si el primer intento (inicial) falla, nuestro sistema espera 60 minutos antes de intentar nuevamente y continuará con este patrón hasta que reciba una respuesta exitosa o alcance el máximo de 10 reintentos.

Métodos de Pago

payment_method_registration_failed

Puedes recibir un payment_method_registration_failed webhook cuando el registro del método de pago de débito directo falló para un paymentMethodId dado.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentMethodId
    "reference": "your_reference_here",
    "status": "error",
    "failedReason": "BANK_CODE",
    "failedMessage": "A description of the error"
  }
}

Proporcionamos información adicional sobre el fallo en las claves failedReason y failedMessage.

payment_method_registration_canceled

Puedes recibir un payment_method_registration_canceled webhook cuando se cancela el registro del método de pago de débito directo (generalmente por el propietario) para un paymentMethodId dado.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_canceled",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentMethodId
    "reference": "your_reference_here",
    "status": "canceled",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_method_registration_successful

Recibes un payment_method_registration_successful webhook cuando el registro del método de pago de débito directo es exitoso para un paymentMethodId dado.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentMethodId
    "reference": "your_reference_here",
    "status": "active",
    "failedReason": null,
    "failedMessage": null
  }
}

Solicitudes de Pago

payment_request_failed

Puedes recibir un payment_request_failed webhook cuando un error es reportado por el proveedor de infraestructura de pago para un paymentRequestId dado.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentRequestId
    "reference": "your_reference_here",
    "status": "failed",
    "failedReason": "BANK_CODE",
    "failedMessage": "A description of the error"
  }
}

payment_request_successful

Recibes un payment_request_successful webhook cuando el proveedor de infraestructura de pago confirma que el pago fue exitoso para un paymentRequestId dado.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentRequestId
    "reference": "your_reference_here",
    "status": "succesful",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_request_canceled

Recibes un webhook payment_request_canceled cuando la solicitud de pago fue cancelada por el cliente.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_canceled",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentRequestId
    "reference": "your_reference_here",
    "status": "canceled",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_request_chargeback

Recibes un payment_request_chargeback webhook cuando el proveedor de infraestructura de pago informa que el pago resultó en un contracargo por parte del cliente.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_chargeback",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // El paymentRequestId
    "reference": "your_reference_here",
    "status": "chargeback",
    "failedReason": null,
    "failedMessage": null
  }
}