Eventos de dispersiones BRE-B

Cuando creas dispersiones a llaves BRE-B, Wompi envía eventos a tu URL de webhook para notificarte el resultado de cada transacción. Los eventos de dispersiones BRE-B utilizan el mismo mecanismo de webhook que las dispersiones bancarias, pero el payload incluye información adicional sobre la llave BRE-B resuelta.

tip

Si ya tienes configurados webhooks para dispersiones bancarias, los eventos BRE-B llegarán a la misma URL. Solo necesitas manejar la estructura adicional del objeto payee.

Evento transaction.updated para BRE-B

Se dispara cuando una transacción BRE-B cambia de estado. A diferencia de una transacción bancaria, el objeto payee incluye los campos key, keyType, keyResolutionId y paymentMethodType.

Estructura del payload

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
      "id": "7ee824ed-6450-49d8-8b4c-cca181414f5f",
      "payoutId": "c57a05b0-646c-11f1-8436-6ca5ce550b83",
      "amountInCents": 10,
      "status": "FAILED",
      "payee": {
        "key": "@elias123",
        "name": "Elias P",
        "email": "test@wompi.com",
        "keyType": "ALPHANUMERIC",
        "legalId": "******4155",
        "personType": "NATURAL",
        "accountType": "AHORROS",
        "legalIdType": "CC",
        "accountNumber": "**2893",
        "keyResolutionId": "c6dc06b0-646c-11f1-82b1-1bb0e4b41a19",
        "paymentMethodType": "SAVING_ACCOUNT"
      },
      "failureReason": {
        "code": "MOL-5021",
        "description": "El monto ingresado es menor al mínimo permitido. El valor mínimo es $1."
      },
      "currency": "COP",
      "appliedAt": "2026-06-10T01:36:25.264Z",
      "createdAt": "2026-06-10T01:36:17.498Z"
    }
  },
  "signature": {
    "properties": [
      "transaction.id",
      "transaction.status",
      "transaction.amountInCents"
    ],
    "checksum": "a07af8b1201e58488b5b060651daa297d9a807282b83d13c763805e891197ab5"
  },
  "timestamp": 1781055385651,
  "sentAt": "2026-06-10T01:36:25.871Z"
}

Campos del objeto transaction

Campo	Tipo	Descripción
id	string (UUID)	Identificador único de la transacción
payoutId	string (UUID)	ID del lote al que pertenece la transacción
amountInCents	integer	Monto de la transacción en centavos COP
status	string	Estado actual: APPROVED, FAILED, REJECTED
payee	object	Información del beneficiario (ver detalle abajo)
failureReason	object	Razón del fallo (solo presente si status es FAILED)
currency	string	Moneda: COP
appliedAt	string (ISO 8601)	Fecha en que se aplicó el cambio de estado
createdAt	string (ISO 8601)	Fecha de creación de la transacción

Campos del objeto payee (BRE-B)

Campo	Tipo	Descripción
key	string	Llave BRE-B utilizada para el pago
name	string	Nombre del beneficiario
email	string	Email del beneficiario
keyType	string	Tipo de llave: ALPHANUMERIC, MAIL, PHONE, IDENTIFICATION, ESTABLISHMENT_CODE
legalId	string	Documento del beneficiario (enmascarado)
personType	string	Tipo de persona: NATURAL, JURIDICA
accountType	string	Tipo de cuenta resuelta: AHORROS, CORRIENTE
legalIdType	string	Tipo de documento: CC, CE, NIT, PP, TI
accountNumber	string	Número de cuenta (enmascarado)
keyResolutionId	string (UUID)	Identificador de la resolución de la llave BRE-B
paymentMethodType	string	Tipo de método de pago resuelto: SAVING_ACCOUNT, CHECKING_ACCOUNT

Diferencia con transacciones bancarias

En transacciones bancarias, el objeto payee contiene bank, document, accountType y accountNumber. En BRE-B, además de la información bancaria resuelta, se incluyen key, keyType, keyResolutionId y paymentMethodType.

Campos del objeto failureReason

Solo presente cuando status es FAILED:

Campo	Tipo	Descripción
code	string	Código del error que causó el fallo
description	string	Descripción legible del motivo de fallo

Ejemplo: transacción BRE-B aprobada

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "payoutId": "c57a05b0-646c-11f1-8436-6ca5ce550b83",
      "amountInCents": 150000,
      "status": "APPROVED",
      "payee": {
        "key": "@juanperez",
        "name": "Juan Perez",
        "email": "juan@example.com",
        "keyType": "ALPHANUMERIC",
        "legalId": "******7890",
        "personType": "NATURAL",
        "accountType": "AHORROS",
        "legalIdType": "CC",
        "accountNumber": "**4321",
        "keyResolutionId": "d7ed17c1-757d-22f2-93c2-2cc1f5c52b2a",
        "paymentMethodType": "SAVING_ACCOUNT"
      },
      "currency": "COP",
      "appliedAt": "2026-06-10T02:15:30.000Z",
      "createdAt": "2026-06-10T02:15:00.000Z"
    }
  },
  "signature": {
    "properties": [
      "transaction.id",
      "transaction.status",
      "transaction.amountInCents"
    ],
    "checksum": "b18bg9c2312f69599c6c170762ebb398f715dfc527705dde674d901326b6ac93"
  },
  "timestamp": 1781055930000,
  "sentAt": "2026-06-10T02:15:30.500Z"
}

Ejemplo: transacción BRE-B fallida

{
  "event": "transaction.updated",
  "data": {
    "transaction": {
      "id": "7ee824ed-6450-49d8-8b4c-cca181414f5f",
      "payoutId": "c57a05b0-646c-11f1-8436-6ca5ce550b83",
      "amountInCents": 10,
      "status": "FAILED",
      "payee": {
        "key": "@elias123",
        "name": "Elias P",
        "email": "test@wompi.com",
        "keyType": "ALPHANUMERIC",
        "legalId": "******4155",
        "personType": "NATURAL",
        "accountType": "AHORROS",
        "legalIdType": "CC",
        "accountNumber": "**2893",
        "keyResolutionId": "c6dc06b0-646c-11f1-82b1-1bb0e4b41a19",
        "paymentMethodType": "SAVING_ACCOUNT"
      },
      "failureReason": {
        "code": "MOL-5021",
        "description": "El monto ingresado es menor al mínimo permitido. El valor mínimo es $1."
      },
      "currency": "COP",
      "appliedAt": "2026-06-10T01:36:25.264Z",
      "createdAt": "2026-06-10T01:36:17.498Z"
    }
  },
  "signature": {
    "properties": [
      "transaction.id",
      "transaction.status",
      "transaction.amountInCents"
    ],
    "checksum": "a07af8b1201e58488b5b060651daa297d9a807282b83d13c763805e891197ab5"
  },
  "timestamp": 1781055385651,
  "sentAt": "2026-06-10T01:36:25.871Z"
}

Validación de firma

La validación de firma para eventos BRE-B funciona exactamente igual que para eventos bancarios. Las propiedades usadas para la firma son:

• transaction.id
• transaction.status
• transaction.amountInCents

Pasos para validar

1. Extraer los valores de las propiedades listadas en signature.properties, en orden.
2. Concatenar los valores sin separadores.
3. Concatenar el campo timestamp.
4. Concatenar tu secreto de eventos.
5. Generar el hash con SHA256.
6. Comparar con signature.checksum.

Ejemplo con el evento fallido anterior:

Propiedades: 7ee824ed-6450-49d8-8b4c-cca181414f5f + FAILED + 10
Timestamp: 1781055385651
Secreto: prod_events_XXXXXXXXXX

Cadena a hashear: 7ee824ed-6450-49d8-8b4c-cca181414f5fFAILED101781055385651prod_events_XXXXXXXXXX

SHA256 → a07af8b1201e58488b5b060651daa297d9a807282b83d13c763805e891197ab5

📖 Ver guía completa de validación de firma

Política de reintentos

Si tu endpoint no responde con un código HTTP 2xx, Wompi reintentará el envío hasta 3 veces adicionales.

Intento	Comportamiento
1	Envío inmediato
2	Primer reintento
3	Segundo reintento
4	Tercer y último reintento

Después del cuarto intento fallido, el evento se descarta. Puedes consultar el estado de la transacción manualmente con GET /payouts/{payoutId}/transactions.

Códigos de fallo comunes en BRE-B

Estos son algunos códigos que pueden aparecer en failureReason.code:

Código	Descripción
MOL-5021	El monto ingresado es menor al mínimo permitido
C01	La cuenta no existe o está inactiva
C02	Cuenta cerrada
C03	Cuenta no encontrada
C05	Débito no autorizado

Requisitos de tu endpoint

• Método: POST
• Protocolo: HTTPS obligatorio
• Accesibilidad: Público desde internet
• Respuesta: Código HTTP 2xx (idealmente 200 OK)
• Timeout: Responder en menos de 10 segundos
• Idempotencia: Tu endpoint debe ser idempotente (puede recibir el mismo evento más de una vez)

Configuración de la URL de eventos

La URL de webhook se configura desde el dashboard de Wompi:

1. Ir a Desarrollo > Programadores
2. Seleccionar Pagos a Terceros
3. Ingresar la URL pública
4. Guardar cambios

La misma URL recibe eventos de transacciones bancarias y BRE-B. Diferencia entre ambos verificando la presencia del campo payee.key en el payload.

📖 Ver configuración detallada