Casos de uso de Recaudo

Un recaudo es cómo tu negocio recibe dinero por Bre-B: lo creas, compartes su llave de pago o QR, y Mono te notifica a medida que los pagadores pagan. La misma entidad cubre una venta única, un plan mensual, una donación abierta o un pedido de marketplace — lo que cambia es la configuración. Esta página lista los escenarios comunes y los campos exactos a definir para cada uno.

Lee primero el concepto de recaudos si estos términos son nuevos. Los montos están en centavos (1 COP = 100 centavos), la unidad que espera la API.

Antes de empezar

Necesitarás:

• Una cuenta tenant registrada (tenant_account_id) para recibir los fondos.
• Un endpoint de webhook para recibir eventos de recaudo — ve Payloads de webhooks.
• Familiaridad con el ciclo de vida del recaudo (ready → minimum_paid → paid).

Referencia rápida

UC1 — Compra de producto (precio fijo)

Un cliente paga un monto fijo una vez. Pon el piso y el techo del total iguales para que el recaudo se cierre con el primer pago exitoso.

{
  "usage_mode": "single_use",
  "total_minimum_amount": 5000000,
  "total_maximum_amount": 5000000,
  "expires_in": 3600,
  "metadata": { "product_id": "SKU-128", "product_name": "Teclado inalámbrico" }
}

5000000 centavos = $50,000 COP. Compártelo como QR dinámico con ese monto y expiración. El recaudo llega a paid con el primer pago exitoso.

UC2 — Carrito de compra (monto dinámico)

El total es lo que sume el carrito, calculado en el checkout. Define solo total_maximum_amount; omite el mínimo.

{
  "usage_mode": "single_use",
  "total_maximum_amount": 12000000,
  "metadata": { "order_id": "ORD-9931", "item_count": "4" }
}

Como el cobro exacto se decide al pagar, comparte la llave de pago en lugar de un QR de monto fijo.

UC3 — Suscripción / plan de pagos (cuotas fijas)

Un plan pagado en cuotas iguales. Acota el total de por vida y fija cada pago al valor de la cuota.

{
  "usage_mode": "multiple_use",
  "total_maximum_amount": 60000000,
  "minimum_attempt_amount": 5000000,
  "maximum_attempt_amount": 5000000
}

Doce cuotas de $50,000 COP hacia un plan de $600,000. El recaudo progresa ready → minimum_paid → paid a medida que llegan las cuotas; sin QR, porque es recurrente.

UC4 — Donación libre (abierta)

Acepta cualquier monto, cualquier número de veces, sin fin. Omite ambos montos totales para que el recaudo nunca llegue a paid y permanezca en ready.

{
  "usage_mode": "multiple_use",
  "custom_key_value": "REFOREST",
  "custom_merchant_name": "Fundación VerdeVida"
}

custom_key_value hace la llave legible (p. ej. @MN{random}REFOREST) y es inmutable una vez creada. Compártela como QR estático en volantes o redes sociales.

UC5 — Cuotas flexibles (límites mín/máx)

El pagador elige cuánto pagar cada vez, dentro de límites, hacia una meta con un depósito mínimo.

{
  "usage_mode": "multiple_use",
  "total_maximum_amount": 300000000,
  "total_minimum_amount": 50000000,
  "minimum_attempt_amount": 10000000,
  "maximum_attempt_amount": 100000000
}

Una meta de $3,000,000 con un depósito mínimo de $500,000; cada pago entre $100,000 y $1,000,000. Los pagos por debajo de minimum_attempt_amount o por encima de maximum_attempt_amount se rechazan; el recaudo llega a minimum_paid cuando se cumple el piso, y a paid en el techo.

UC6 — Factura a cliente (pagador restringido)

Una factura pagable solo por el cliente nombrado. Usa expected_payers para restringir quién puede pagar y reference para llevar el número de factura.

{
  "usage_mode": "single_use",
  "total_minimum_amount": 18000000,
  "total_maximum_amount": 18000000,
  "expected_payers": [{ "document_type": "CC", "document_number": "1023711432" }],
  "custom_merchant_name": "Distribuciones Andinas S.A.S.",
  "reference": "FAC-2024-001",
  "expires_in": 86400
}

Compártela como QR dinámico adjunto a la factura (expiración de 24 horas arriba).

UC7 — Venta flash (ventana corta)

Una oferta por tiempo limitado. Usa un expires_in muy corto; si nadie paga a tiempo, el recaudo pasa a discarded.

{
  "usage_mode": "single_use",
  "total_minimum_amount": 2500000,
  "total_maximum_amount": 2500000,
  "expires_in": 30
}

Renderiza el QR dinámico con una cuenta regresiva que coincida.

UC8 — Gift card / recarga (con tope, reutilizable)

Un saldo cargado en varios pagos hasta un tope, pagable por cualquiera que tenga la tarjeta.

{
  "usage_mode": "multiple_use",
  "custom_key_value": "GIFT4MARIA",
  "total_maximum_amount": 50000000,
  "minimum_attempt_amount": 1000000,
  "maximum_attempt_amount": 20000000
}

Imprime el QR estático en la tarjeta. El recaudo llega a paid cuando se llena el tope.

UC9 — Deuda variable (tope dinámico)

Un saldo rotativo — p. ej. una línea de crédito — donde el techo por pago cambia con el tiempo. Mantenlo abierto (sin totales) y actualiza maximum_attempt_amount a medida que cambia el saldo.

{
  "usage_mode": "multiple_use",
  "custom_key_value": "CARD-7781",
  "maximum_attempt_amount": 80000000
}

Ajusta el techo después con Actualizar recaudo (PATCH); el cambio dispara un webhook collection.updated con los valores previos. La llave en sí es inmutable.

UC10 — Split de marketplace

Un solo cobro que tu backend luego reparte entre varios destinatarios. Codifica las reglas de split como metadata plana (los metadata de Bre-B no pueden anidarse), y ejecuta los pagos tras la liquidación.

{
  "usage_mode": "single_use",
  "total_minimum_amount": 10000000,
  "total_maximum_amount": 10000000,
  "metadata": {
    "split_1_recipient_key": "@MNVENDEDOR1",
    "split_1_type": "percentage",
    "split_1_value": "80",
    "split_2_recipient_key": "@MNPLATFORM",
    "split_2_type": "percentage",
    "split_2_value": "10",
    "split_3_recipient_key": "shipping@logistics.com",
    "split_3_type": "fixed",
    "split_3_value": "500000"
  }
}

Cuando llega el webhook collection.paid, lee las reglas de split desde metadata y ejecuta los pagos — ve la receta de split en Casos de uso de Dispersiones.

Próximos pasos

• Casos de uso de Dispersiones — paga a los destinatarios (y completa el split de marketplace).
• Sandbox: recaudos — simula pagos contra cualquier receta de arriba.
• Crear recaudo — el esquema completo de request y response.