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.
With Belvo's Smart Collections you can delegate balance monitoring to Belvo and trigger a Pix Charge when your user's account has sufficient funds. Instead of polling your user's balance yourself, you tell Belvo the amounts you want to collect as well as the balance conditions to wait for and Belvo watches the account in the background, notifying you when it's time to collect.
In accordance with BACEN Resolução Conjunta nº 17, Belvo operates as a regulated Iniciador de Transação de Pagamento (ITP). To ensure compliance with transparency and branding requirements:
- Belvo Responsibility: Belvo ensures that all elements and disclosures within the Belvo Widget are fully compliant with BACEN regulations and communicates any required changes to partners.
- Partner Responsibility: Partners must clearly state in their UI/service that their company is not the regulated payment entity and identify Belvo as the provider responsible for the payment initiation.
Smart Collections combines two Belvo products across two phases. The diagram below shows the three main steps of a complete integration.
Step 1: Collection Instruction setup. You create a Collection Instruction describing the amount you want to collect and the balance conditions to wait for. Belvo then monitors the linked account in the background, so you don't have to poll anything yourself. Once the balance meets your criteria, Belvo sends an item_ready_to_charge webhook, which is what triggers step 3. Phase 1: Balance Checking covers Step 1.
Step 2: Payment Authorization setup. Independently of step 1, and at any point before you need to charge, you create a Smart Transfers Payment Authorization for the payer. Smart Transfers moves funds between accounts held by the same person or company, so the account that receives the funds must be held by the payer. Belvo notifies you when its status changes with a webhook, but because these are Payments-BR.V2 webhooks, the notification itself doesn't carry the status. You fetch the authorization with a GET request to confirm it's AUTHORIZED and ready to use.
Step 3: Charge creation. When you collect through a Collection Instruction, you wait until you've received item_ready_to_charge and confirmed the authorization is AUTHORIZED, and then you trigger a Charge. (A one-off Charge without a Collection Instruction only needs the AUTHORIZED authorization, see below.) Belvo processes the Pix payment and sends another webhook when the Charge's status changes. As with the authorization, you fetch the Charge with a GET request to see whether it succeeded or failed. Phase 2: Payment Creation covers Steps 2 and 3.
Phase 1 and Phase 2 are loosely coupled. Belvo does not link the two together, so store the IDs of your items, authorizations, and Charges together to correlate them in your own system.
In fact, Phase 1 is optional. With an AUTHORIZED Payment Authorization you can trigger a Charge directly, a one-off collection, without creating a Collection Instruction at all.
Setting up Smart Collections combines two integration paths. Use the OFDA Widget to onboard users and create a Link for balance monitoring, and the Payments API (Direct API (Smart Transfers)) to create Payment Authorizations and Charges.
To manage Collection Instructions, see Phase 1: Balance Checking and the Collection Instructions API reference.