Cobro por llave (Bre-B)

POST /v1/co/breb/payin/key

Crea una llave Bre-B ALPHA efímera y exclusiva de ese cobro (@ + 16 alfanuméricos) y te la devuelve. El pagador transfiere a esa llave desde su app bancaria — no se genera QR.

Autenticación: firma ECDSA, igual que el resto de /v1/co/breb/*. País CO, moneda COP.

Request body

{
  "amount": 100000,
  "reference": "FACT-123"
}

Campo	Tipo	Requerido	Descripción
`amount`	`number`	✅	Monto en pesos COP enteros, `> 0` y `≤ 11.500.000`. El pago debe llegar por ese monto exacto o se rechaza en la autorización. Si falta → `400` `"amount requerido (pesos COP > 0)"`
`reference`	`string`	❌	Tu referencia de conciliación (queda en la tx como `txIdSource`)

Response `201 Created`

{
  "txId": "a1b2c3d4e5f6...",
  "status": "PENDING",
  "keyId": "7aa184b7-c549-467b-917f-460b4224b459",
  "keyValue": "@Xk9dPq2mLr7TzB4n",
  "keyType": "ALPHA",
  "expiresAt": "2026-07-23T15:15:00.000Z",
  "amount": 100000,
  "currency": "COP",
  "estimatedFees": {
    "feeClient": 500,
    "feeBase": 420,
    "iva": 80,
    "netAmount": 99500,
    "currency": "COP"
  }
}

Campo	Descripción
`txId`	ID único de la transacción en Rivopay
`keyValue`	Lo que compartes con el pagador
`keyId` / `keyType`	ID de la llave en la red y su tipo (siempre `ALPHA`)
`expiresAt`	Expiración de la llave (15 minutos después de crearla)
`amount`	Monto esperado del cobro
`estimatedFees`	Desglose de comisiones, calculado al crear el cobro

Consultar estado

GET /v1/co/breb/payin/key/{txId}

{
  "txId": "a1b2c3...",
  "status": "COMPLETED",
  "amount": 100000,
  "currency": "COP",
  "feeClient": 500,
  "netAmount": 99500,
  "createdAt": "2026-07-23T15:00:00.000Z",
  "updatedAt": "2026-07-23T15:03:00.000Z"
}

Estados: PENDING → PROCESSING (pago autorizado, en manos del banco) → COMPLETED | FAILED | EXPIRED.

La consulta verifica contra Bre-B: si el pago ya llegó y el webhook no, aquí mismo se acredita el balance y se dispara el webhook al comercio. Si el cobro nunca pasó por la autorización síncrona, se busca en la red el pago dirigido a la llave y se enlaza antes de resolver. Responde 404 si el txId no es tuyo o no existe.

También disponible en el panel: GET /v1/co/front/breb/payin/key/{txId} (Cognito, solo lectura).

Cancelar

DELETE /v1/co/breb/payin/key/{txId}

{ "txId": "a1b2c3...", "status": "CANCELLED" }

Marca la transacción como EXPIRED y borra la llave en la red. Responde 409 si la tx no es un cobro por llave o si ya está COMPLETED.

Ciclo de vida

Al liquidarse recibes el webhook payin.completed (o payin.failed) con firma HMAC-SHA256 en x-signature, igual que el QR — ver Webhooks.

Errores

Código	Causa
`400`	`amount` ausente (`"amount requerido (pesos COP > 0)"`), no numérico, `≤ 0`, mayor a `11.500.000`, o falta `X-Idempotency-Key` (`IDEMPOTENCY_KEY_REQUIRED`)
`403`	Bre-B no habilitado, o producción no habilitada para la cuenta
`409`	Onboarding incompleto — contacta con soporte
`422`	Monto fuera de los límites min/max de tu tarifa (validados al crear), o Bre-B rechazó la creación de la llave
`502`	Bre-B no disponible — reintenta
`503`	Cuenta suspendida temporalmente