Recaudar con una plantilla

Este flujo recauda pagos de muchos pagadores a través de una sola dirección compartida: una plantilla multiuso emite una llave Bre-B y un QR estáticos, tú los exhibes (en una pantalla, un afiche, el pie de una factura) y cada transferencia que reciben aterriza en tu subcuenta como un pago. No hay llamada a la API por pago: la plantilla es la campaña, y los webhooks son tu registro de quién pagó qué.

Úsalo para donaciones, pagos con QR en punto físico, cuotas recurrentes o cualquier recaudo donde no necesites saber de antemano qué pago específico viene en camino.

Antes de empezar

Vas a necesitar:

• Una cuenta de Mono con Core y la feature de recaudos habilitada para tu programa. Ver Métodos: configuración del programa.
• La subcuenta que recibirá los recaudos.
• Un endpoint de webhooks suscrito a los eventos de recaudos.
• El concepto de Plantillas fresco en la cabeza.

Vista de la secuencia

Pasos

1. Crea la plantilla de recaudo. type: "collection" es el valor por defecto; hazla multiple_use y pide el QR:

   {
     "external_id": "campana-2026-regreso-a-clases",
     "usage_mode": "multiple_use",
     "subaccount_id": "<subcuenta receptora>",
     "currency": "COP",
     "reference": "Regreso a clases 2026",
     "minimum_payin_amount": { "amount": 1000000, "currency": "COP" },
     "total_maximum_amount": { "amount": 5000000000, "currency": "COP" },
     "expires_at": "2026-12-31T23:59:59Z",
     "method_params": { "co_breb": { "create_qr": true } }
   }

2. Espera payin_template_ready y publica la llave y el QR donde los pagadores los vayan a ver.

3. Deja fluir los pagos. Cada transferencia se convierte en un pago: payin_created → payin_approved_in_provider → payin_subaccount_credited. La identidad del pagador llega en instrument.payer. Así sabes quién pagó, ya que en este flujo nada identifica los pagos de antemano.

4. Vigila los hitos de la campaña. Si definiste total_minimum_amount, payin_template_minimum_paid anuncia que se alcanzó la meta; payin_template_paid anuncia el tope (total_maximum_amount) y la plantilla deja de aceptar pagos. Reabre una campaña pagada subiendo el tope con un update.

5. Ciérrala. Deja que expires_at pode la plantilla, o elimínala cuando paid_amount esté liquidado y nada quede en vuelo. En ambos casos la llave y el QR se dan de baja y payin_template_discarded lo confirma.

Conciliación en este flujo

Los pagos son anónimos hasta que llegan, así que concilia listando pagos por template_id y cruzando instrument.payer (documento) y amount. Si necesitas un cruce exacto pago-a-orden, esa es la señal para usar intenciones de pago en su lugar.

Siguientes pasos

• Recaudar con intenciones de pago: cuando cada pago debe identificarse de antemano.
• Liquidación: cómo el dinero recaudado llega a tu cuenta de fondeo.
• Webhooks: el catálogo completo de eventos sobre el que corre este flujo.