Dispersión (Bre-B)

POST /v1/co/breb/payout

Envía dinero a un destino Bre-B. Al crear la dispersión se retiene amount + feeCharged de tu balance disponible; al completarse se debita definitivamente, y si falla se libera.

Request body

El destino es siempre la llave (keyType + keyValue); el gateway la resuelve internamente.

{
  "amount": 100000,
  "keyType": "PHONE",
  "keyValue": "3123185778",
  "identificationNumber": "1020304050",
  "reference": "factura-123"
}

Campo	Tipo	Requerido	Descripción
`amount`	`number`	✅	Monto en pesos COP enteros, `> 0` y `≤ 11.500.000`
`keyType`	`string`	✅	`ID` \| `PHONE` \| `EMAIL` \| `ALPHA` \| `BCODE`. No distingue mayúsculas y normaliza `mobile` / `MOBILE` → `PHONE`. Ausente o inválido → `400` con la lista de valores permitidos
`keyValue`	`string`	✅	Llave Bre-B del destinatario. Se pre-valida contra el formato del tipo (ver tipos de llave)
`identificationNumber`	`string`	✅	Documento del titular de la llave: 5–18 alfanuméricos
`reference`	`string`	❌	Tu referencia interna (vuelve como `txIdSource` en Transacciones)

El formato de keyValue se valida antes de tocar la red o tu balance (p. ej. PHONE = 10 dígitos que empiezan con 3; ALPHA = @ + 5–20 alfanuméricos) → 400 si no cuadra. El keyType ya normalizado es el que se usa en la resolución interna de la llave.

Response `201 Created`

{
  "externalId": "b4f6d2f0-6a1e-4c9b-9d3a-2f8e7c6b5a41",
  "status": "PROCESSING",
  "providerTxId": "BREB-PAY-3321",
  "amount": 30000,
  "feeCharged": 800,
  "totalDebit": 30800,
  "currency": "COP"
}

Campo	Descripción
`externalId`	ID generado por Rivopay — guárdalo para consultar el estado
`status`	Estado inicial (`PROCESSING`)
`providerTxId`	ID del pago en Bre-B
`feeCharged`	Fee cobrado (en pesos COP)
`totalDebit`	Total retenido de tu balance (`amount + feeCharged`)

Consultar estado

GET /v1/co/breb/payout/{externalId}

{
  "externalId": "b4f6d2f0-6a1e-4c9b-9d3a-2f8e7c6b5a41",
  "status": "COMPLETED",
  "amount": 30000,
  "currency": "COP",
  "feeCharged": 800,
  "failureReason": null,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:02:00.000Z"
}

Estados posibles: PROCESSING, COMPLETED, FAILED. Si falló, failureReason explica el motivo.

Errores

Código	Causa
`400`	Falta `keyType`, `keyValue` o `identificationNumber`; `keyType` fuera del enum; `keyValue` con formato inválido para su tipo; `identificationNumber` fuera de 5–18 alfanuméricos; monto `≤ 0` o > 11.500.000; o falta `X-Idempotency-Key` (`IDEMPOTENCY_KEY_REQUIRED`)
`402`	Saldo insuficiente — la respuesta incluye `availableBalance` y `requiredAmount`
`403`	Servicio Bre-B no habilitado, o producción no habilitada para tu cuenta
`409`	Onboarding incompleto — contacta con soporte
`422`	Llave inexistente o inactiva (no se retiene saldo), monto fuera de los límites de tu cuenta, o Bre-B rechazó la operación
`502`	Bre-B no disponible — reintenta
`503`	Servicio temporalmente suspendido para tu cuenta