Collection use cases (Recaudo)

A collection is how your business receives money over Bre-B: you create it, share its payment key or QR, and Mono notifies you as payers pay. The same entity covers a one-off sale, a monthly plan, an open donation, or a marketplace order — what changes is the configuration. This page lists the common scenarios and the exact fields to set for each.

Read the Collections concept first if these terms are new. Amounts below are in centavos (1 COP = 100 centavos), the unit the API expects.

Before you start

You will need:

• A registered tenant account (tenant_account_id) to receive the funds.
• A webhook endpoint to receive collection events — see Webhook payloads.
• Familiarity with the collection lifecycle (ready → minimum_paid → paid).

Quick reference

UC1 — Product purchase (fixed price)

One customer pays one fixed amount once. Set the total floor and ceiling equal so the collection closes on the first successful payment.

{
  "usage_mode": "single_use",
  "total_minimum_amount": 5000000,
  "total_maximum_amount": 5000000,
  "expires_in": 3600,
  "metadata": { "product_id": "SKU-128", "product_name": "Wireless keyboard" }
}

5000000 centavos = $50,000 COP. Share as a dynamic QR carrying this amount and expiry. The collection reaches paid on the first successful payment.

UC2 — Shopping cart (dynamic amount)

The total is whatever the cart sums to, computed at checkout. Set only total_maximum_amount; omit the minimum.

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

Because the exact charge is decided at pay time, share the payment key rather than a fixed-amount QR.

UC3 — Subscription / payment plan (fixed installments)

A plan paid in equal installments. Cap the lifetime total and pin each payment to the installment amount.

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

Twelve installments of $50,000 COP toward a $600,000 plan. The collection progresses ready → minimum_paid → paid as installments arrive; no QR, since it recurs.

UC4 — Free donation (open-ended)

Accept any amount, any number of times, with no end. Omit both total amounts so the collection never reaches paid and stays ready.

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

custom_key_value makes the key readable (e.g. @MN{random}REFOREST) and is immutable once created. Share as a static QR on flyers or social media.

UC5 — Flexible installments (min/max bounds)

The payer chooses how much to pay each time, within bounds, toward a goal with a minimum deposit.

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

A $3,000,000 goal with a $500,000 minimum deposit; each payment between $100,000 and $1,000,000. Payments below minimum_attempt_amount or above maximum_attempt_amount are rejected; the collection reaches minimum_paid once the floor is met, then paid at the ceiling.

UC6 — Client invoice (restricted payer)

An invoice payable only by the named client. Use expected_payers to restrict who can pay and reference to carry the invoice number.

{
  "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
}

Share as a dynamic QR attached to the invoice (24-hour expiry above).

UC7 — Flash sale (short window)

A time-boxed offer. Use a very short expires_in; if no one pays in time, the collection moves to discarded.

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

Render the dynamic QR with a matching countdown.

UC8 — Gift card / top-up (capped, reusable)

A balance loaded over several payments up to a cap, payable by anyone holding the card.

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

Print the static QR on the card. The collection reaches paid when the cap is filled.

UC9 — Variable debt (dynamic cap)

A revolving balance — e.g. a credit line — where the per-payment ceiling changes over time. Keep it open (no totals) and update maximum_attempt_amount as the balance changes.

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

Adjust the ceiling later with Update collection (PATCH); the change fires a collection.updated webhook with the previous values. The key itself is immutable.

UC10 — Marketplace split

One charge that your backend later splits across several recipients. Encode the split rules as flat metadata (Bre-B metadata cannot nest), then run the payouts after settlement.

{
  "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"
  }
}

When the collection.paid webhook arrives, read the split rules from metadata and execute the payouts — see the post-sale split recipe in Outgoing transfer use cases.

Next steps

• Outgoing transfer use cases — pay recipients (and complete the marketplace split).
• Sandbox: collections — simulate payments against any recipe above.
• Create collection — the full request and response schema.