Guía de integración de dispersiones BRE-B

Esta guía te lleva paso a paso por el proceso completo de integración de dispersiones a llaves BRE-B a través del API de Pagos a Terceros de Wompi. Al finalizar, tendrás un flujo funcional para enviar pagos usando llaves BRE-B.

¿Qué es BRE-B?

BRE-B (Brevete Electrónico Bancario) es un sistema de transferencias inmediatas que permite enviar pagos usando una llave única (email, teléfono, alias alfanumérico, documento de identidad o código de establecimiento) en lugar de los datos bancarios tradicionales. El beneficiario registra su llave en su entidad financiera, y los pagadores pueden enviar dinero usando solo esa llave.

Requisitos previos

Antes de comenzar la integración, asegúrate de tener:

Cuenta activa en Wompi con producto de Pagos a Terceros habilitado
Llaves de autenticación: x-api-key y user-principal-id (ver cómo obtenerlas)
URL de eventos (webhook) configurada en el dashboard (ver configuración)
Al menos una cuenta origen activa con saldo disponible
Generación de idempotency-key para cada solicitud de pago. Se usa para garantizar que el pago sea único y evitar duplicidad. Debe ser una llave que tenga de 1 a 64 caracteres, puede contener letras y números, el único caracter especial permitido dentro de la llave es el guion (-). Debe ser único y expira en 24 horas.

Paso 1: Previsualizar la llave BRE-B

Antes de ejecutar un pago, resuelve la llave BRE-B para obtener la información del titular. Esto permite confirmar al beneficiario con tu usuario y reducir pagos fallidos.

URL Base

Producción:

https://api.payouts.wompi.co/v2

Endpoint:

GET /breb/keys/resolve/{keyValue}?keyType={tipo}

Ejemplo:

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

x-api-key: TU_API_KEY
user-principal-id: TU_USER_PRINCIPAL_ID

Respuesta:

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

Presenta los datos del titular a tu usuario para que confirme visualmente que es el beneficiario correcto.

📖 Ver documentación completa de previsualización

Paso 2: Confirmar con el usuario

Con la información obtenida en el paso anterior, muestra a tu usuario:

Nombre del titular (enmascarado): JUA*** PER*** GAR***
Entidad financiera: BANCOLOMBIA
Tipo de llave: ALPHANUMERIC

Solicita confirmación antes de proceder con el pago. Este paso es responsabilidad de tu aplicación y reduce significativamente los pagos a beneficiarios incorrectos.

Paso 3: Crear la dispersión

Una vez confirmado el beneficiario, crea la dispersión enviando la llave BRE-B en el campo key:

Endpoint:

POST /v2/payouts

Headers:

x-api-key: TU_API_KEY
user-principal-id: TU_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"
    }
  ]
}

Respuesta exitosa (201):

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

Guarda el payoutId para consultas posteriores.

📖 Ver documentación completa de creación de dispersión

Paso 4: Recibir el evento de resultado

Wompi enviará un evento a tu URL de webhook cuando la transacción cambie de estado. Los eventos relevantes son:

Evento `transaction.updated`

Se dispara cuando una transacción individual cambia de estado (aprobada o fallida):

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

Evento `payout.updated`

Se dispara cuando el lote completo cambia de estado:

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

Estados posibles de una transacción

Estado	Descripción
`PENDING`	Transacción creada, pendiente de procesamiento
`PROCESSING`	En proceso de envío al banco
`APPROVED`	Pago exitoso, el beneficiario recibió el dinero
`FAILED`	Pago fallido (llave inválida, cuenta cerrada, etc.)
`REJECTED`	Rechazada por validación antes de procesamiento

Estados posibles de un lote

Estado	Descripción
`PENDING`	Lote creado, pendiente de procesamiento
`TOTAL_PAYMENT`	Todas las transacciones fueron aprobadas
`PARTIAL_PAYMENT`	Algunas transacciones aprobadas y otras fallidas
`REJECTED`	Lote rechazado (saldo insuficiente, límite alcanzado)

📖 Ver documentación completa de eventos BRE-B

Paso 5: Consultar estado (alternativa a eventos)

Si no puedes recibir eventos o como validación adicional, puedes consultar el estado:

Consultar lote:

GET /v2/payouts/{payoutId}

Consultar transacciones del lote:

GET /v2/payouts/{payoutId}/transactions

📖 Ver documentación de consultas

Checklist de go-live

Antes de pasar a producción, verifica:

Autenticación: Llaves de producción configuradas correctamente
Previsualización: Flujo de confirmación de beneficiario implementado
Idempotencia: Cada solicitud usa un idempotency-key único
Manejo de errores: Tu sistema captura y maneja todos los códigos de error (ver errores)
Webhook configurado: URL de producción configurada y recibiendo eventos
Montos en centavos: Verificado que los montos se envían correctamente en centavos
Pruebas en sandbox: Flujo completo probado exitosamente (ver sandbox)
Consulta de saldo: Verificando saldo antes de crear dispersiones

Errores comunes y soluciones

Problema	Causa probable	Solución
`EXC_034` al previsualizar	La llave no existe o no está activa	Confirmar con el beneficiario que su llave está registrada
`EXC_033` al previsualizar	Formato de llave incorrecto	Validar formato contra la tabla de tipos
`409` al crear dispersión	`idempotency-key` duplicada	Generar una nueva llave única
`EXC_008` al crear dispersión	Saldo insuficiente	Recargar la cuenta origen o reducir el monto
Transacción queda en `FAILED`	Llave resuelta pero pago rechazado por el banco	Verificar con el beneficiario el estado de su cuenta
No llegan eventos	URL de webhook no accesible	Verificar que la URL es pública, usa HTTPS y responde con 2xx

¿Qué es BRE-B?​

Requisitos previos​

Paso 1: Previsualizar la llave BRE-B​

Paso 2: Confirmar con el usuario​

Paso 3: Crear la dispersión​

Paso 4: Recibir el evento de resultado​

Evento transaction.updated​

Evento payout.updated​

Estados posibles de una transacción​

Estados posibles de un lote​

Paso 5: Consultar estado (alternativa a eventos)​

Checklist de go-live​

Errores comunes y soluciones​

Recursos adicionales​