Recaudos

Este entorno sandbox te permite probar tu integración de recaudos de extremo a extremo sin procesar pagos reales. Puedes simular pagos entrantes a tus recaudos, incluyendo escenarios exitosos y fallidos.

Prerrequisitos

Al menos un recaudo con una llave Bre-B activa.
El recaudo asociado a la llave Bre-B debe estar en estado ready o minimum_paid.

Simulando un intento de recaudo

Envía un request POST para simular a un pagador haciendo un pago a una de tus llaves de recaudo. Este endpoint solo está disponible en el entorno sandbox.

Ejemplo mínimo

{
  "creditor_key_value": "@YOURBREBKEY",
  "amount": {
    "amount": 50000,
    "currency": "COP"
  }
}

El sandbox generará información aleatoria del pagador y un payment_id si no se proveen, y procesará el pago a través del flujo completo. Recibirás una respuesta 202 Accepted inmediatamente:

{
  "collection_id": "bbcol_5g8k2mNpQrStUvWx",
  "attempt_id": "bbcolat_7hJkLmNpQrStUvWx",
  "transfer_id": "bbit_1a2b3c4d5e6f7g8h9i0j",
  "attempt_state_reason": null
}

Unos segundos después, los eventos de webhook se entregarán a tu URL de webhook configurada con el resultado final del intento. Podrías recibir los siguientes webhooks de recaudo:

collection.attempt_successful: El intento de pago fue settlleado exitosamente por el workflow de simulación.
collection.attempt_unsuccessful: El intento de pago fue rechazado (ya sea por un error simulado o una falla de validación).
collection.paid: El recaudo alcanzó su monto total.
collection.minimum_paid: El recaudo alcanzó su monto mínimo requerido.

Simulación de errores

Por defecto, los pagos simulados se completan con éxito. Para probar cómo tu integración maneja las fallas, pasa un campo error:

{
  "creditor_key_value": "@MN1234567890",
  "amount": {
    "amount": 50000,
    "currency": "COP"
  },
  "error": "tx_risk_control"
}

El pago igual se crea y recibirás la respuesta 202 Accepted, pero el evento de webhook posterior llevará un estado de rechazo.

Códigos de error disponibles

Código de error	Descripción
`tx_unknown`	Ocurrió un error inesperado
`tx_provider_unavailable`	El sistema Bre-B no está disponible
`tx_breb_timeout`	Timeout del sistema Bre-B
`tx_risk_control`	Transacción bloqueada por reglas de risk control

Flujo esperado

Llamas al endpoint de sandbox para simular un pago.
La API responde con 202 Accepted.
Después de un breve delay (2–5 segundos), se envía un webhook a tu URL configurada.
1. Si no se especificó error, el pago se settlea exitosamente.
2. Si se especificó un error, el pago se rechaza con el motivo correspondiente.