# Webhooks de Pago (México)

Un **webhook** es una devolución de llamada web que Belvo utiliza para enviar notificaciones sobre un enlace específico. Necesitarás configurar webhooks para poder usar las APIs de Belvo.

## Configurando tus webhooks

Para configurar tu URL de webhook:

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


✅ Tu URL de webhook se ha agregado exitosamente.

## Payload del Webhook

Ejemplo de Payload del Webhook (Éxito)

```json Ejemplo de Payload del Webhook (Éxito)
{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "successful",
    "failedReason": null,
    "failedMessage": null
  }
}
```

Ejemplo de Payload del Webhook (Fallo)

```json Ejemplo de Payload del Webhook (Fallo)
{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "failed",
    "failedReason": "01",
    "failedMessage": "Cuenta inexistente"
  }
}
```

Ejemplo de Payload del Webhook (Cliente)

```json Ejemplo de Payload del Webhook (Cliente)
{
  "eventType": "customer_update",
  "eventCode": "customer_blocked",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "documentNumber": "RFC/CURP of Customer"
  }
}
```

| Parámetro  | Tipo | Descripción |
|  --- | --- | --- |
| `eventType` | string | El tipo de evento del recurso de la API. Puede ser uno de: `customer_update`, `payment_method_update`, o `payment_request_update`. |
| `eventCode` | string | El código del evento del webhook. Para detalles sobre los posibles valores, por favor consulta la sección de Códigos de Eventos del Webhook a continuación. |
| `datetime` | string | La marca de tiempo ISO-8601 cuando el evento fue enviado. |
| `details` | object | Un objeto que contiene datos específicos sobre el evento. |
| `details.id` | string | El ID de Belvo del recurso de la API (Cliente, Método de Pago, o Solicitud de Pago) al que el evento está relacionado. |
| `details.reference` | string | Si proporcionaste una `reference` al crear el recurso, una descripción opcional del objeto. |
| `details.status` | string | El estado del recurso. |
| `details.failedReason`
 | string
 | Si el estado es `failed`, este campo contiene un código de fallo. Este campo es `null` si el `status` no es `failed`.
Para detalles sobre el `failedReason` y `failedMessage` esperados (incluyendo la lista de posibles valores), por favor consulta nuestra guía de Errores de Débito Directo Bancario.
 |
| `details.failedMessage`
 | string
 | Si el estado es `failed`, este campo contiene una descripción del fallo. Este campo es `null` si el `status` no es `failed`.
Para detalles sobre el `failedReason` y `failedMessage` esperados (incluyendo la lista de posibles valores), por favor consulta nuestra guía de Errores de Débito Directo Bancario.
 |
| `details.documentNumber` | string | Si el evento está relacionado con un cliente, este campo contiene el RFC o CURP del cliente relacionado con el método de pago de débito directo. **Este campo solo está disponible para eventos relacionados con clientes.** |


Para información sobre payloads específicos para un recurso de la API dado y código de webhook, simplemente haz clic en el **Código de Evento** del webhook en la tabla a continuación.

## Códigos de Eventos de Webhook

| Recurso | Tipo de Evento  | Código de Evento  | Enviado cuando... |
|  --- | --- | --- | --- |
| Clientes | `customer_update` | `customer_blocked` | el cliente relacionado con el método de pago por débito directo fue bloqueado debido a actividad sospechosa. |
| Clientes | `customer_update` | `customer_unblocked` | el cliente relacionado con el método de pago por débito directo fue desbloqueado después de la revisión por las partes relevantes. |
| Métodos de Pago | `payment_method_update` | `payment_method_registration_successful` | el registro del método de pago por débito directo fue exitoso. |
| Métodos de Pago | `payment_method_update` | `payment_method_registration_failed` | el registro del método de pago por débito directo falló. |
| Métodos de Pago | `payment_method_update` | `payment_method_registration_canceled` | el registro de débito directo fue cancelado (generalmente por el propietario). |
| Solicitudes de Pago | `payment_request_update` | `payment_request_successful` | el pago fue exitoso y recibimos confirmación del proveedor de infraestructura de pago. |
| Solicitudes de Pago | `payment_request_update` | `payment_request_failed` | un error es reportado por el proveedor de infraestructura de pago. |
| Solicitudes de Pago | `payment_request_update` | `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 reenviar la solicitud. Para más detalles, consulta nuestra sección de Política de reintento.

## Política de reintento

Cuando Belvo no recibe una respuesta `2XX` de tu servidor, reintentamos 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.