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.

Formas de indicar el destino

Debes enviar una de estas tres opciones (en este orden de precedencia):

Opción	Campo(s)	Cuándo usarla
Resolución	`resolutionId`	Pago único: obtuviste el ID con `resolve-key` y confirmaste el titular
Destinatario	`recipientId`	Beneficiario recurrente ya creado
Llave directa	`keyType` + `keyValue`	El gateway crea el destinatario por ti en el momento

Request body

Con destinatario existente:

{
  "recipientId": "rcpt_8a7b6c",
  "amount": 30000,
  "reference": "retiro-551",
  "displayName": "Mi Comercio SAS"
}

Con resolución (pago único):

{
  "resolutionId": "res_9d8c7b",
  "amount": 30000,
  "reference": "retiro-551"
}

Con llave directa:

{
  "keyType": "PHONE",
  "keyValue": "3009876543",
  "amount": 30000,
  "reference": "retiro-551"
}

Campo	Tipo	Requerido	Descripción
`resolutionId`	`string`	❌*	ID de una resolución vigente de `resolve-key`
`recipientId`	`string`	❌*	ID de un destinatario creado previamente
`keyType`	`string`	❌*	Tipo de llave: `ID`, `PHONE`, `EMAIL`, `ALPHA`, `BCODE`
`keyValue`	`string`	❌*	Valor de la llave del destinatario
`amount`	`number`	✅	Monto en pesos COP enteros. Máximo `11.500.000`
`reference`	`string`	❌	Tu referencia interna (vuelve como `txIdSource` en Transacciones)
`displayName`	`string`	❌	Nombre del remitente mostrado al receptor

* Envía resolutionId, o recipientId, o el par keyType + keyValue.

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.

Listar pagos en la red

GET /v1/co/breb/payments

Lista los pagos Bre-B de tu cuenta directamente desde la red Bre-B (entrantes y salientes) — útil para conciliación fina por endToEndId o qrCodeReference.

Query param	Descripción
`pageSize`	Resultados por página (1–100, default `20`)
`pageNumber`	Página (default `1`)
`direction`	Filtra por dirección del pago (entrante/saliente)
`status`	Filtra por estado en la red
`qrCodeReference`	Filtra por la referencia del QR de cobro
`endToEndId`	Filtra por el identificador end-to-end de la red

{
  "payments": [
    {
      "paymentId": "pay_1a2b3c",
      "status": "COMPLETED",
      "providerStatus": "settled",
      "direction": "OUTBOUND",
      "amount": { "value": "30000", "currency": "COP" },
      "qrCodeReference": null,
      "e2eId": "E2E-20260601-0001",
      "errorCode": null,
      "failureReason": null,
      "receiverName": "MARIA FERNANDA G.",
      "senderName": "MI COMERCIO SAS",
      "createdAt": "2026-06-01T10:00:00.000Z",
      "updatedAt": "2026-06-01T10:02:00.000Z"
    }
  ],
  "pagination": { "total_items": 1, "total_pages": 1 }
}

Errores

Código	Causa
`400`	Sin destino (`resolutionId` / `recipientId` / llave), `keyValue` con formato inválido, o monto > 11.500.000
`402`	Saldo insuficiente — la respuesta incluye `availableBalance` y `requiredAmount`
`403`	Servicio Bre-B no habilitado, o producción no habilitada para tu cuenta
`409`	Comercio sin onboarding Bre-B
`422`	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