Top-up

A top-up lets an end user load money into their own wallet balance from any Colombian bank: your product shows them a personal Bre-B key (or QR), they transfer to it from their bank's app, and seconds later their subaccount balance reflects the recharge. The pattern is one top-up template per subaccount, created once and reused for every recharge — the key becomes the user's permanent "deposit address".

Before you start

You will need:

• A Mono account with Core and the payins feature enabled for your program. See Methods — program configuration.
• One subaccount per end user. See Ledger.
• A webhook endpoint subscribed to the payin events.

Sequence overview

Steps

1. Create the template when the subaccount is born. One call per user, idempotent on external_id (use your own user or account ID):

   {
     "external_id": "user-8421-topup",
     "type": "topup",
     "usage_mode": "multiple_use",
     "subaccount_id": "<the user's subaccount>",
     "currency": "COP",
     "nickname": "Wallet top-up — user 8421",
     "method_params": { "co_breb": { "create_qr": true } }
   }

   The template is created in created state — the Bre-B key does not exist yet.

2. Wait for payin_template_ready. The webhook (or a GET on the template) delivers payment_tokens.co_breb: the key and, since create_qr was true, a static QR image. Store both against the user.

3. Show the key in your product. The user recharges whenever they want, from any bank, with no further API calls: every payment to the key becomes a payin against this template.

4. React to the payin webhooks. payin_subaccount_credited is the signal to update the user's visible balance — subaccount_amount is what was credited. Reject conditions (a transfer above the Bre-B cap, an amount outside the template's limits) arrive as payin_rejected with a state_reason.

5. Reconcile. Every payin carries template_id and subaccount_id, so mapping a payment to a user is a lookup you already have. instrument.payer tells you who actually sent the money.

Variant: one-off recharge

For a single expected recharge — an onboarding deposit, a one-time funding of a campaign balance — create the template with "usage_mode": "single_use" and, if the amount is fixed, set minimum_payin_amount = maximum_payin_amount. The first successful payin moves the template to paid and it never accepts another payment. Use expected_payers if only a specific person may fund it.

Guardrails worth setting

• minimum_payin_amount / maximum_payin_amount — bound each recharge.
• expected_payers — lock the key to its owner's document, so nobody tops up someone else's wallet by mistake.
• payin_data.metadata — stamped on every payin, useful to tag the wallet product or campaign.

Next steps

• Collect with a template — the same mechanics, pointed at customers.
• Settlement — how the recharged money reaches your funding account.
• Templates — every field the template accepts.