BRE-B disbursement events

When you create BRE-B disbursements, Wompi sends events to your webhook URL to notify you of the result of each transaction. BRE-B disbursement events use the same webhook mechanism as bank disbursements, but the payload includes additional information about the resolved BRE-B key.

tip

If you already have webhooks configured for bank disbursements, BRE-B events will arrive at the same URL. You only need to handle the additional structure of the payee object.

transaction.updated event for BRE-B

Triggered when a BRE-B transaction changes status. Unlike a bank transaction, the payee object includes the key, keyType, keyResolutionId and paymentMethodType fields.

Payload structure

{
  "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"
}

transaction object fields

Field	Type	Description
id	string (UUID)	Unique transaction identifier
payoutId	string (UUID)	Batch ID the transaction belongs to
amountInCents	integer	Transaction amount in COP cents
status	string	Current status: APPROVED, FAILED, REJECTED
payee	object	Beneficiary information (see detail below)
failureReason	object	Failure reason (only present if status is FAILED)
currency	string	Currency: COP
appliedAt	string (ISO 8601)	Date when the status change was applied
createdAt	string (ISO 8601)	Transaction creation date

payee object fields (BRE-B)

Field	Type	Description
key	string	BRE-B key used for the payment
name	string	Beneficiary name
email	string	Beneficiary email
keyType	string	Key type: ALPHANUMERIC, MAIL, PHONE, IDENTIFICATION, ESTABLISHMENT_CODE
legalId	string	Beneficiary document (masked)
personType	string	Person type: NATURAL, JURIDICA
accountType	string	Resolved account type: AHORROS, CORRIENTE
legalIdType	string	Document type: CC, CE, NIT, PP, TI
accountNumber	string	Account number (masked)
keyResolutionId	string (UUID)	BRE-B key resolution identifier
paymentMethodType	string	Resolved payment method type: SAVING_ACCOUNT, CHECKING_ACCOUNT

Difference from bank transactions

In bank transactions, the payee object contains bank, document, accountType and accountNumber. In BRE-B, in addition to the resolved banking information, key, keyType, keyResolutionId and paymentMethodType are included.

failureReason object fields

Only present when status is FAILED:

Field	Type	Description
code	string	Error code that caused the failure
description	string	Human-readable description of the failure reason

Example: approved BRE-B transaction

{
  "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"
}

Example: failed BRE-B transaction

{
  "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"
}

Signature validation

Signature validation for BRE-B events works exactly the same as for bank events. The properties used for the signature are:

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

Validation steps

1. Extract the values of the properties listed in signature.properties, in order.
2. Concatenate the values without separators.
3. Concatenate the timestamp field.
4. Concatenate your event secret.
5. Generate the hash with SHA256.
6. Compare with signature.checksum.

Example with the failed event above:

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

String to hash: 7ee824ed-6450-49d8-8b4c-cca181414f5fFAILED101781055385651prod_events_XXXXXXXXXX

SHA256 → a07af8b1201e58488b5b060651daa297d9a807282b83d13c763805e891197ab5

📖 See complete signature validation guide

Retry policy

If your endpoint does not respond with an HTTP 2xx code, Wompi will retry sending up to 3 additional times.

Attempt	Behavior
1	Immediate send
2	First retry
3	Second retry
4	Third and final retry

After the fourth failed attempt, the event is discarded. You can manually query the transaction status with GET /payouts/{payoutId}/transactions.

Common BRE-B failure codes

These are some codes that may appear in failureReason.code:

Code	Description
MOL-5021	The amount entered is less than the minimum allowed
C01	The account does not exist or is inactive
C02	Account closed
C03	Account not found
C05	Unauthorized debit

Endpoint requirements

• Method: POST
• Protocol: HTTPS mandatory
• Accessibility: Publicly accessible from the internet
• Response: HTTP 2xx code (ideally 200 OK)
• Timeout: Respond in less than 10 seconds
• Idempotency: Your endpoint must be idempotent (it may receive the same event more than once)

Event URL configuration

The webhook URL is configured from the Wompi dashboard:

1. Go to Development > Developers
2. Select Third-Party Payments
3. Enter the public URL
4. Save changes

The same URL receives both bank and BRE-B transaction events. Differentiate between them by checking for the presence of the payee.key field in the payload.

📖 See detailed configuration