Validación de pagos en recaudos

Cómo un recaudo acepta o rechaza cada pago Bre-B entrante — reglas de montos, expiración, pagadores permitidos y todas las razones de rechazo

Cuando un cliente paga uno de tus recaudos, Mono valida el pago antes de aceptarlo. Las reglas son las que definiste al crear el recaudo: cuánto se puede pagar, hasta cuándo y quién puede pagar. Un pago que rompe una regla se rechaza automáticamente, y la razón de rechazo te dice exactamente qué regla rompió. Esta página explica cada regla y cada razón que puedes recibir.

Recaudos vs. intentos de pago

Un recaudo (collection) es tu punto de cobro Bre-B (un código QR o una llave de pago). Cada pago individual contra él es un intento de pago (attempt), con su propio estado — separado del ciclo de vida del recaudo. Un intento rechazado no cambia el estado del recaudo; solo incrementa su contador failed_attempts.

Cómo se valida un intento de pago

Cada pago entrante se convierte en un intento que termina en uno de tres desenlaces:

Estado del intento	Significado	Final
`created`	Intento recibido, validación en curso	No
`successful`	El pago fue exitoso	Sí
`rejected`	Mono rechazó el pago con base en las reglas del recaudo	Sí
`failed`	El pago falló por causas externas (banco, proveedor, timeouts)	Sí

Para intentos rejected y failed, el campo state_reason del intento nombra la causa exacta — la lista completa está en la tabla de referencia.

Las reglas que tú controlas

Quién puede pagar — `expected_payers`

Si envías expected_payers al crear el recaudo, solo esos pagadores quedan permitidos — cualquier otro se rechaza con payer_not_allowed. Cada pagador esperado se identifica por su documento de identidad colombiano:

document_type — uno de CC, CE, NIT, NUIP, PPT, PEP, PASS, TI
document_number — el número de documento del pagador esperado

Deja expected_payers vacío para aceptar pagos de cualquier persona. Mira UC6 — Factura a cliente para un ejemplo armado.

Cuánto se puede pagar — límites de monto

Todos los montos son enteros en centavos (p. ej. 10000000 = COP 100.000,00). Aplican dos niveles de límites:

Campo	Aplica a	Regla	Razón de rechazo
`minimum_attempt_amount`	cada intento	Monto mínimo permitido por intento de pago (solo recaudos `multiple_use`)	`amount_below_minimum`
`maximum_attempt_amount`	cada intento	Monto máximo permitido por intento de pago (solo recaudos `multiple_use`)	`amount_exceeds_maximum`
`total_maximum_amount`	el total acumulado	Máximo total que el recaudo puede recibir — al alcanzarlo, el recaudo pasa a `paid`	`amount_exceeds_total_maximum`
`total_minimum_amount`	el total acumulado	Mínimo total requerido para que el recaudo se considere cumplido	`amount_below_total_minimum`

usage_mode decide cómo se acumulan los intentos:

single_use — el recaudo acepta solo un pago exitoso.
multiple_use — el recaudo acepta múltiples pagos hasta alcanzar total_maximum_amount.

Hasta cuándo — `expires_at` / `expires_in`

Define el plazo del recaudo como fecha absoluta ISO-8601 (expires_at) o en segundos desde ahora (expires_in) — son mutuamente excluyentes en el request. Un pago después del plazo se rechaza con collection_expired. Mira UC7 — Venta flash para un ejemplo armado.

Encendido o apagado — `enabled`

enabled controla si el recaudo puede recibir pagos. Los pagos contra un recaudo deshabilitado se rechazan con collection_disabled — útil para pausar un recaudo sin eliminarlo.

Referencia de razones de rechazo

El state_reason del intento (presente solo en intentos rejected / failed) nombra la causa:

Ligadas a las reglas y el estado de tu recaudo:

`state_reason`	El pago se rechazó porque…
`payer_not_allowed`	el pagador no está en la lista `expected_payers` del recaudo
`amount_below_minimum`	el intento está por debajo de `minimum_attempt_amount`
`amount_exceeds_maximum`	el intento está por encima de `maximum_attempt_amount`
`amount_exceeds_total_maximum`	empujaría el total recibido más allá de `total_maximum_amount`
`amount_below_total_minimum`	está por debajo del requisito `total_minimum_amount` del recaudo
`collection_expired`	ya pasó el plazo `expires_at` / `expires_in` del recaudo
`collection_disabled`	el recaudo tiene `enabled: false`
`collection_paid`	el recaudo ya llegó a `paid` (su máximo total, o era de un solo uso)
`collection_discarded`	el recaudo fue descartado
`collection_invalid_state`	el recaudo no está en un estado que acepte pagos
`collection_not_found`	ninguna llave de recaudo coincide con el pago
`collection_pruning`	la llave del recaudo está en proceso de poda (pruning)

Causas externas / operativas (fuera de la configuración de tu recaudo): rejected_by_bank, provider_unavailable, lock_timeout, risk_control, internal_error, mono_timeout, breb_timeout, unknown.

Observar rechazos en tu integración

Webhooks — cada intento no exitoso dispara collection.attempt_unsuccessful con el intento y su state_reason; los exitosos disparan collection.attempt_successful.
Consulta directa — lista los intentos con List collection attempts.
Un intento rechazado nunca saca al recaudo de su estado actual — solo incrementa el contador failed_attempts del recaudo.

Siguientes pasos

Ciclo de vida del recaudo — cómo el recaudo mismo se mueve entre estados.
Casos de uso de recaudos — combinaciones de reglas listas para usar (precio fijo, pagador restringido, venta flash…).
Create collections — la referencia completa del request con todos los campos de esta página.

Validación de pagos en recaudos

En esta página