Smart Collections is currently in Beta. Some contracts on this page are still being confirmed with our engineering team, so treat them as provisional and expect refinements before general availability, including:
- Webhook payloads and event codes
- API reference updates for the Collection Instructions, Payment Authorization, and Charge endpoints
- Field names and documentation improvements (terminology, diagrams)
Contact your Belvo account manager to join the Beta program.
To use Belvo's Smart Collections, you must have already integrated both of the Brazil products it builds on: Banking Aggregation (to monitor balances) and Smart Transfers, from Payments Brazil (to collect funds). Smart Collections runs in production only.
Smart Collections uses two Belvo products, one to monitor bank account balances and one to move the funds:
| Task | What you need | Belvo product |
|---|---|---|
| Monitor the balance: know when the user has enough money to collect | A Link (link_id) that lets Belvo read the user's account balance in the background | Banking Aggregation (Open Finance Data Aggregation, OFDA) |
| Collect the funds: move funds via Pix once the balance is sufficient | A Smart Transfers Payment Authorization you can charge against | Payments Brazil: Smart Transfers |
Banking Aggregation and Payments are separate Belvo products. Each has its own API keys and its own webhook configuration, so you must set both up independently. Smart Collections will not work if you reuse one product's API keys or webhook endpoint for the other.
To monitor balances, you need to:
- Complete the Banking Aggregation getting started guide.
- Set up the OFDA Widget to create Links.
- Enable a webhook to receive
COLLECTIONSwebhook events (see Aggregation Webhooks).
Belvo needs a Link to read the user's account balance:
- If you already aggregate this user's data, reuse their existing Link. You don't need to create a new one for Smart Collections.
- Otherwise, create one by following the OFDA Widget integration guide.
To collect funds, you need to:
- Complete the Payments Brazil prerequisites.
- Ask your Belvo account manager to enable Smart Transfers for your organization.
- Set up webhooks to receive
Payments-BR.V2webhook events (see Payments Webhooks (Brazil)).
Smart Transfers only moves funds between accounts held by the same person (same CPF) or company (same CNPJ root). The beneficiary account on the Payment Authorization must therefore be held by the user you collect from. See the Smart Transfers overview.
When you create a Payment Authorization, payer.institution is a payments institution ID from the List all payment institutions endpoint. It is not the same as the OFDA institution from the user's Link, so you must look it up separately.
Once these are in place, head to Phase 1: Balance Checking to create your first Collection Instruction.