BRE-B disbursement integration guide

This guide takes you step by step through the complete integration process of BRE-B key disbursements through the Wompi Third-Party Payments API. By the end, you will have a functional flow to send payments using BRE-B keys.

What is BRE-B?

BRE-B (Brevete Electrónico Bancario) is an instant transfer system that allows sending payments using a unique key (email, phone, alphanumeric alias, identification document or establishment code) instead of traditional banking data. The beneficiary registers their key at their financial institution, and payers can send money using only that key.

Prerequisites

Before starting the integration, make sure you have:

Active Wompi account with Third-Party Payments product enabled
Authentication keys: x-api-key and user-principal-id (see how to obtain them)
Event URL (webhook) configured in the dashboard (see configuration)
At least one active source account with available balance
idempotency-key generation for each payment request. Used to ensure payment uniqueness and avoid duplication. Must be a key between 1 and 64 characters, can contain letters and numbers, the only special character allowed is the hyphen (-). Must be unique and expires in 24 hours.

Step 1: Preview the BRE-B key

Before executing a payment, resolve the BRE-B key to obtain the holder's information. This allows you to confirm the beneficiary with your user and reduce failed payments.

Endpoint:

GET /v2/breb/keys/resolve/{keyValue}?keyType={type}

Example:

GET https://api.payouts.wompi.co/v2/breb/keys/resolve/@JUANPEREZ?keyType=ALPHANUMERIC

x-api-key: YOUR_API_KEY
user-principal-id: YOUR_USER_PRINCIPAL_ID

Response:

{
  "status": 200,
  "code": "OK",
  "data": {
    "holderName": "JUA*** PER*** GAR***",
    "financialEntity": {
      "name": "BANCOLOMBIA",
      "code": "001"
    },
    "keyType": "ALPHANUMERIC",
    "keyValue": "@JUA***"
  }
}

Present the holder's data to your user so they can visually confirm it is the correct beneficiary.

📖 See complete preview documentation

Step 2: Confirm with the user

With the information obtained in the previous step, show your user:

Holder name (masked): JUA*** PER*** GAR***
Financial institution: BANCOLOMBIA
Key type: ALPHANUMERIC

Request confirmation before proceeding with the payment. This step is your application's responsibility and significantly reduces payments to incorrect beneficiaries.

Step 3: Create the disbursement

Once the beneficiary is confirmed, create the disbursement by sending the BRE-B key in the key field:

Endpoint:

POST /v2/payouts

Headers:

x-api-key: YOUR_API_KEY
user-principal-id: YOUR_USER_PRINCIPAL_ID
idempotency-key: payout-unique-key-001
Content-Type: application/json

Body:

{
  "reference": "payout-breb-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactions": [
    {
      "amount": 150000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@JUANPEREZ"
    }
  ]
}

Successful response (201):

{
  "status": 201,
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "payoutId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transactions": 1,
    "success": 1,
    "failed": 0
  }
}

Save the payoutId for subsequent queries.

📖 See complete disbursement creation documentation

Step 4: Receive the result event

Wompi will send an event to your webhook URL when the transaction changes status. The relevant events are:

`transaction.updated` event

Triggered when an individual transaction changes status (approved or failed):

{
  "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-15T10:05:30.000Z",
      "createdAt": "2026-06-15T10:05:00.000Z"
    }
  },
  "signature": {
    "properties": [
      "transaction.id",
      "transaction.status",
      "transaction.amountInCents"
    ],
    "checksum": "b18bg9c2312f69599c6c170762ebb398f715dfc527705dde674d901326b6ac93"
  },
  "timestamp": 1781056530000,
  "sentAt": "2026-06-15T10:05:30.500Z"
}

`payout.updated` event

Triggered when the complete batch changes status:

{
  "event": "payout.updated",
  "data": {
    "payout": {
      "id": "c57a05b0-646c-11f1-8436-6ca5ce550b83",
      "reference": "payout-breb-001",
      "amountInCents": 150000,
      "paymentType": "PROVIDERS",
      "status": "TOTAL_PAYMENT",
      "totalTransactions": 1,
      "currency": "COP",
      "approvedAt": "2026-06-15T10:05:30.000Z",
      "createdAt": "2026-06-15T10:05:00.000Z"
    }
  },
  "signature": {
    "properties": ["payout.id", "payout.status", "payout.amountInCents"],
    "checksum": "639dc6bd2ac0104f090651c07773b6537f935623cf0ed04894f0687d4c9eebc7"
  },
  "timestamp": 1781056530000,
  "sentAt": "2026-06-15T10:05:30.500Z"
}

Possible transaction statuses

Status	Description
`PENDING`	Transaction created, pending processing
`PROCESSING`	Being sent to the bank
`APPROVED`	Successful payment, beneficiary received the money
`FAILED`	Failed payment (invalid key, closed account, etc.)
`REJECTED`	Rejected by validation before processing

Possible batch statuses

Status	Description
`PENDING`	Batch created, pending processing
`TOTAL_PAYMENT`	All transactions were approved
`PARTIAL_PAYMENT`	Some transactions approved and others failed
`REJECTED`	Batch rejected (insufficient balance, limit reached)

📖 See complete BRE-B events documentation

Step 5: Query status (alternative to events)

If you cannot receive events or as additional validation, you can query the status:

Query batch:

GET /v2/payouts/{payoutId}

Query batch transactions:

GET /v2/payouts/{payoutId}/transactions

📖 See queries documentation

Go-live checklist

Before going to production, verify:

Authentication: Production keys correctly configured
Preview: Beneficiary confirmation flow implemented
Idempotency: Each request uses a unique idempotency-key
Error handling: Your system captures and handles all error codes (see errors)
Webhook configured: Production URL configured and receiving events
Signature verification: Validating the signature of received events
Retries: Exponential backoff implemented for technical errors (503)
Amounts in cents: Verified that amounts are sent correctly in cents
Sandbox testing: Complete flow successfully tested (see sandbox)
Balance check: Verifying balance before creating disbursements
Logs: Saving trace_id from each response for traceability

Common errors and solutions

Problem	Probable cause	Solution
`EXC_034` on preview	The key does not exist or is not active	Confirm with the beneficiary that their key is registered
`EXC_033` on preview	Incorrect key format	Validate format against the types table
`409` on disbursement creation	Duplicate `idempotency-key`	Generate a new unique key
`EXC_008` on disbursement creation	Insufficient balance	Recharge the source account or reduce the amount
Transaction stays in `FAILED`	Key resolved but payment rejected by bank	Verify with the beneficiary the status of their account
Events not arriving	Webhook URL not accessible	Verify the URL is public, uses HTTPS and responds with 2xx

What is BRE-B?​

Prerequisites​

Step 1: Preview the BRE-B key​

Step 2: Confirm with the user​

Step 3: Create the disbursement​

Step 4: Receive the result event​

transaction.updated event​

payout.updated event​

Possible transaction statuses​

Possible batch statuses​

Step 5: Query status (alternative to events)​

Go-live checklist​

Common errors and solutions​

Additional resources​