Recarga

Una recarga le permite a un usuario final cargar dinero a su propio saldo de billetera desde cualquier banco colombiano: tu producto le muestra una llave Bre-B personal (o un QR), él transfiere desde la app de su banco, y segundos después el saldo de su subcuenta refleja la recarga. El patrón es una plantilla de recarga por subcuenta, creada una vez y reutilizada en cada recarga. La llave se vuelve la "dirección de depósito" permanente del usuario.

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.
Una subcuenta por usuario final. Ver Ledger.
Un endpoint de webhooks suscrito a los eventos de recaudos.

Vista de la secuencia

Pasos

Crea la plantilla cuando nace la subcuenta. Una llamada por usuario, idempotente sobre external_id (usa tu propio ID de usuario o cuenta):

{
  "external_id": "user-8421-topup",
  "type": "topup",
  "usage_mode": "multiple_use",
  "subaccount_id": "<la subcuenta del usuario>",
  "currency": "COP",
  "nickname": "Recarga de billetera del usuario 8421",
  "method_params": { "co_breb": { "create_qr": true } }
}

La plantilla se crea en estado created: la llave Bre-B todavía no existe.

Espera payin_template_ready. El webhook (o un GET a la plantilla) entrega payment_tokens.co_breb: la llave y, como create_qr fue true, la imagen del QR estático. Guarda ambos asociados al usuario.
Muestra la llave en tu producto. El usuario recarga cuando quiera, desde cualquier banco, sin más llamadas a la API: cada transferencia a la llave queda registrada como un pago contra esta plantilla.
Reacciona a los webhooks del pago. payin_subaccount_credited es la señal para actualizar el saldo visible del usuario; subaccount_amount es lo acreditado. Las condiciones de rechazo (una transferencia por encima del tope de Bre-B, un monto fuera de los límites de la plantilla) llegan como payin_rejected con su state_reason.
Concilia. Cada pago lleva template_id y subaccount_id, así que mapearlo a un usuario es un lookup que ya tienes. instrument.payer te dice quién envió realmente el dinero.

Variante: recarga de una sola vez

Para una única recarga esperada (un depósito de onboarding, el fondeo único de un saldo de campaña), crea la plantilla con "usage_mode": "single_use" y, si el monto es fijo, define minimum_payin_amount = maximum_payin_amount. El primer pago exitoso mueve la plantilla a paid y esta no acepta nunca otro pago. Usa expected_payers si solo una persona específica puede fondearla.

Barandas que vale la pena definir

minimum_payin_amount / maximum_payin_amount: acotan cada recarga.
expected_payers: amarra la llave al documento de su dueño, para que nadie recargue la billetera de otro por error.
payin_data.metadata: se estampa en cada pago, útil para etiquetar el producto de billetera o la campaña.

Siguientes pasos

Recaudar con una plantilla: la misma mecánica, apuntada a clientes.
Liquidación: cómo el dinero recargado llega a tu cuenta de fondeo.
Plantillas: cada campo que acepta la plantilla.