Crear dispersión con llave BRE-B

El endpoint de creación de dispersiones permite enviar pagos a beneficiarios identificados por su llave BRE-B, sin necesidad de conocer los datos bancarios tradicionales (banco, tipo de cuenta, número de cuenta). También soporta lotes mixtos donde se combinan transacciones BRE-B con transacciones bancarias en una misma solicitud.

Buena práctica

Antes de crear una dispersión BRE-B, usa el endpoint de previsualización para resolver la llave y confirmar al beneficiario con tu usuario. Esto reduce pagos fallidos.

Endpoint Crear dispersión con llave BRE-B

URL Base

Producción:

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

POST /v2/payouts

Cabeceras (Headers)

Header	Requerido	Descripción
x-api-key	Sí	API Key del comercio para autenticación
user-principal-id	Sí	Identificador único del usuario (UUID)
idempotency-key	Sí	Clave única para evitar pagos duplicados. Solo letras, números y guiones. Máximo 64 caracteres. Expira en 24 horas.
Content-Type	Sí	application/json
business-application-id	No	Identificador de la aplicación de negocio. Valor: WOMPI_PAYOUTS

x-api-key: exMsrSQwTL2vgrIQ2RdNL5MOlmNfOt7taSyMgzlJ
user-principal-id: 63416484-e3e2-48ff-8f0d-20877cd0d161
idempotency-key: payout-breb-unique-key-001
Content-Type: application/json

Cuerpo de la solicitud (Body)

Campos del lote

Campo	Tipo	Requerido	Descripción
reference	string	Sí	Referencia única del lote de pagos
accountId	string	Sí	ID de la cuenta origen. Obtener del endpoint GET /accounts
paymentType	string	Sí	Tipo de pago: PAYROLL, PROVIDERS, OTHER
transactions	array	Sí	Lista de transacciones del lote (mínimo 1)
dispersionDatetime	string	No	Fecha programada en formato YYYY-MM-DDTHH:mm. Si no se envía, el pago es inmediato
recurring	object	No	Configuración de recurrencia (ver Pagos recurrentes)

Campos de cada transacción BRE-B

Para enviar un pago usando llave BRE-B, se utiliza el campo key en lugar de los campos bancarios tradicionales.

Campo	Tipo	Requerido	Descripción
key	string	Sí	Llave BRE-B del beneficiario. Al enviar este campo, no se requieren bankId, accountType ni accountNumber
amount	integer	Sí	Monto en centavos (COP). Debe ser positivo. Ej: $1.000 = 100000
name	string	Sí	Nombre del beneficiario
email	string	Sí	Correo electrónico del beneficiario
legalIdType	string	No	Tipo de documento: CC, CE, NIT, PP, TI, DNI
legalId	string	No	Número de documento del beneficiario
phone	string	No	Teléfono del beneficiario
description	string	No	Descripción del pago
personType	string	No	Tipo de persona: NATURAL, JURIDICA
reference	string	No	Referencia individual de la transacción. Máximo 40 caracteres, solo letras, números y guiones

Diferencia con pago bancario

En un pago bancario tradicional se envían bankId, accountType, accountNumber, legalIdType y legalId. Con BRE-B, el campo key reemplaza los datos bancarios. El sistema resuelve la llave y direcciona el pago automáticamente.

Pagos inmediatos

Ejemplo de dispersión inmediata con llave BRE-B:

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

Ejemplo con múltiples transacciones BRE-B

{
  "reference": "payout-breb-002",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PAYROLL",
  "transactions": [
    {
      "amount": 250000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    },
    {
      "amount": 180000,
      "name": "Maria Lopez",
      "email": "maria@example.com",
      "key": "maria@email.com"
    },
    {
      "amount": 320000,
      "name": "Carlos Gomez",
      "email": "carlos@example.com",
      "key": "3001234567"
    }
  ]
}

Ejemplo de lote mixto (BRE-B + cuenta bancaria)

Puedes combinar transacciones BRE-B y bancarias en el mismo lote:

{
  "reference": "payout-mixed-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "transactions": [
    {
      "amount": 150000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    },
    {
      "amount": 250000,
      "name": "Carlos Gomez",
      "email": "carlos@example.com",
      "legalIdType": "CC",
      "legalId": "1234567890",
      "bankId": "9183a03b-cd82-451a-a6c7-6a9ab406a477",
      "accountType": "AHORROS",
      "accountNumber": "9876543210"
    }
  ]
}

Pagos programados

Para programar un pago a una fecha futura, agrega el campo dispersionDatetime:

{
  "reference": "payout-breb-scheduled-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PROVIDERS",
  "dispersionDatetime": "2025-07-15T10:00",
  "transactions": [
    {
      "amount": 500000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    }
  ]
}

info

La fecha de programación debe ser mínimo al siguiente día de la solicitud. De lo contrario, el pago es rechazado.

Pagos recurrentes

Para crear pagos recurrentes, agrega dispersionDatetime y el objeto recurring:

Campo	Tipo	Requerido	Descripción
recurring.interval	string	Sí	Intervalo: biweek (quincenal), month (mensual)
recurring.months	integer	Sí	Duración en meses: 3, 6, 12
recurring.description	string	No	Descripción de la recurrencia

{
  "reference": "payout-breb-recurring-001",
  "accountId": "84a339e8-c277-45bd-b652-50f0b689edf7",
  "paymentType": "PAYROLL",
  "dispersionDatetime": "2025-07-15T10:00",
  "recurring": {
    "interval": "month",
    "months": 6,
    "description": "Pago mensual a proveedor"
  },
  "transactions": [
    {
      "amount": 350000,
      "name": "Juan Perez",
      "email": "juan@example.com",
      "key": "@juanperez"
    }
  ]
}

Respuesta exitosa

HTTP 201 Created

{
  "status": 201,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "OK",
  "message": "Solicitud ejecutada correctamente.",
  "data": {
    "payoutId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transactions": 3,
    "success": 3,
    "failed": 0
  }
}

Campo	Descripción
data.payoutId	Identificador único del lote creado (UUID)
data.transactions	Total de transacciones enviadas en el lote
data.success	Transacciones aceptadas para procesamiento
data.failed	Transacciones rechazadas por validación

Respuestas de error

400 — Error de validación

Se retorna cuando los campos requeridos faltan o tienen un formato inválido.

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "400",
  "message": [
    "reference must be a string",
    "reference should not be empty"
  ],
  "data": {
    "message": [
      "reference must be a string",
      "reference should not be empty"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
}

Idempotency key inválida

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "400",
  "message": [
    "The key can only contain letters, numbers, and hyphens"
  ],
  "data": {
    "message": [
      "The key can only contain letters, numbers, and hyphens"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
}

Acción recomendada: Verificar que todos los campos requeridos estén presentes y con el formato correcto. La idempotency-key solo admite letras, números y guiones.

401 — No autorizado

Se retorna cuando la x-api-key es inválida o no fue proporcionada.

{
  "message": "Unauthorized"
}

Acción recomendada: Verificar que estás enviando la x-api-key correcta en los headers.

403 — Prohibido

Se retorna cuando el payer no se encuentra registrado, no tiene permisos o no tiene producto activo.

{
  "status": 403,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "403",
  "message": "Payer not found",
  "data": {
    "message": "Payer not found",
    "error": "Forbidden",
    "statusCode": 403
  }
}

Posibles mensajes:

• Payer not found — El user-principal-id no corresponde a un payer registrado
• Customer is employed and not allowed — El cliente no tiene permisos de dispersión
• Payer not have active product — El payer no tiene el producto de Pagos a Terceros activo

Acción recomendada: Verificar que el user-principal-id corresponde a un payer activo con producto de Pagos a Terceros habilitado.

409 — Idempotencia duplicada

Se retorna cuando la idempotency-key ya fue procesada previamente.

{
  "status": 409,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_032",
  "message": "La llave de idempotencia ya fue procesada.",
  "type": "Business"
}

Acción recomendada: Usar una nueva idempotency-key. Cada llave expira en 24 horas y no puede reutilizarse dentro de ese periodo.

500 — Error interno

Se retorna cuando ocurre un error no esperado en el servidor.

{
  "status": 500,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_001",
  "message": "Se presentó error interno procesando la solicitud."
}

Acción recomendada: Reintentar la solicitud. Si el error persiste, contactar a soporte con el trace_id.

Tipos de llave BRE-B soportados

Tipo	Formato	Ejemplo de key
Alfanumérica	@ + 5 a 20 caracteres alfanuméricos	@JUANPEREZ
Email	Email válido	juan@email.com
Teléfono	10 dígitos, inicia con 3	3001234567
Documento de identidad	1 a 18 caracteres alfanuméricos	1234567890
Código de establecimiento	8 dígitos	12345678

Consideraciones

• Idempotencia: Cada solicitud debe incluir un idempotency-key único. Si se envía la misma llave dentro de 24 horas, se retorna error 409.
• Montos en centavos: El campo amount se expresa en centavos COP. Por ejemplo, $10.000 COP se representa como 1000000.
• Lotes mixtos: Un mismo lote puede contener transacciones BRE-B (con key) y transacciones bancarias (con bankId + accountType + accountNumber).
• Validación de llave: El sistema resuelve la llave BRE-B al procesar la transacción. Si la llave no es válida o no está activa, la transacción individual será rechazada.
• Límites: Aplican los mismos límites transaccionales que para dispersiones bancarias. Consulta GET /limits.
• Cuenta origen: El accountId debe corresponder a una cuenta activa del payer. Consulta GET /accounts.