# Smart Collections

Beta
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.

Regulatory Disclosure
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.


## How it works

Smart Collections combines two Belvo products across two phases. The diagram below shows the three main steps of a complete integration.


```mermaid
sequenceDiagram
    participant Client as Your application
    participant Aggregation as Belvo Aggregation API
    participant Payments as Belvo Payments API

    rect rgba(0, 100, 255, .05)
        Note over Client, Payments: 1. Collection Instruction setup

        Client->>Aggregation: POST /api/collection-instructions/
        Aggregation-->>Client: 201 Created

        loop Background balance monitoring
            Note right of Aggregation: Belvo checks the linked account balance. Once your criteria are met, you'll receive a webhook you can act on. See step 3.
        end
    end

    rect rgba(0, 200, 100, .05)
        Note over Client, Payments: 2. Payment Authorization setup

        Client->>Payments: POST /payments/br/payment-authorizations/
        Payments-->>Client: 201 Created (authorization_url)

        Note right of Payments: User approves the authorization at their bank

        Payments->>Client: Webhook: PAYMENT_AUTHORIZATION
        Client->>Payments: GET /payments/br/payment-authorizations/{id}/
        Payments-->>Client: 200 OK (status: AUTHORIZED)
    end

    rect rgba(255, 150, 0, .05)
        Note over Client, Payments: 3. Charge creation

        Aggregation->>Client: Webhook: item_ready_to_charge
        Note over Client, Payments: Also requires an AUTHORIZED Payment Authorization from step 2

        Client->>Payments: POST /payments/br/payment-authorizations/{id}/charges/
        Payments-->>Client: 201 Created

        Payments->>Client: Webhook: CHARGE
        Client->>Payments: GET /payments/br/payment-authorizations/{id}/charges/{charge_id}/
        Payments-->>Client: 200 OK
    end
```

**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.

The two phases are independent
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.

## Integration options

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.