# Smart Collections

Beta
Smart Collections está atualmente em Beta. Alguns contratos nesta página ainda estão sendo confirmados com nossa equipe de engenharia, portanto, trate-os como provisórios e espere refinamentos antes da disponibilidade geral, incluindo:

- Payloads de webhook e códigos de eventos
- Atualizações de referência da API para os endpoints de Collection Instructions, Payment Authorization e Charge
- Nomes de campos e melhorias na documentação (terminologia, diagramas)


Entre em contato com seu gerente de conta da Belvo para participar do programa Beta.

Com as Smart Collections da Belvo, você pode delegar o monitoramento de saldo para a Belvo e acionar uma Cobrança Pix quando a conta do seu usuário tiver fundos suficientes. Em vez de verificar o saldo do usuário por conta própria, você informa à Belvo os valores que deseja coletar, bem como as condições de saldo a serem aguardadas, e a Belvo monitora a conta em segundo plano, notificando você quando é hora de coletar.

Divulgação Regulatória
De acordo com a **Resolução Conjunta nº 17** do BACEN, a Belvo opera como um **Iniciador de Transação de Pagamento (ITP)** regulamentado. Para garantir conformidade com os requisitos de transparência e marca:

- **Responsabilidade da Belvo:** A Belvo garante que todos os elementos e divulgações dentro do **Belvo Widget** estejam totalmente em conformidade com as regulamentações do BACEN e comunica quaisquer alterações necessárias aos parceiros.
- **Responsabilidade do Parceiro:** Os parceiros devem declarar claramente em sua interface/serviço que sua empresa não é a entidade de pagamento regulamentada e identificar a **Belvo** como o provedor responsável pela iniciação do pagamento.


## Como funciona

Smart Collections combina dois produtos da Belvo em duas fases. O diagrama abaixo mostra os três passos principais de uma integração completa.


```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
```

**Passo 1: Configuração da Instrução de Cobrança.** Você cria uma Instrução de Cobrança descrevendo o valor que deseja cobrar e as condições de saldo para aguardar. A Belvo então monitora a conta vinculada em segundo plano, para que você não precise fazer polling. Assim que o saldo atende aos seus critérios, a Belvo envia um webhook `item_ready_to_charge`, que é o que aciona o passo 3. Fase 1: Verificação de Saldo cobre o Passo 1.

**Passo 2: Configuração da Autorização de Pagamento.** Independentemente do passo 1, e a qualquer momento antes de precisar cobrar, você cria uma Autorização de Pagamento Smart Transfers para o pagador. Smart Transfers move fundos entre contas mantidas pela mesma pessoa ou empresa, então a conta que recebe os fundos deve ser mantida pelo pagador. A Belvo notifica você quando o status muda com um webhook, mas como esses são webhooks Payments-BR.V2, a notificação em si não carrega o status. Você busca a autorização com uma solicitação `GET` para confirmar que está `AUTHORIZED` e pronta para uso.

**Passo 3: Criação da Cobrança.** Quando você coleta através de uma Instrução de Cobrança, espera até receber `item_ready_to_charge` e confirmar que a autorização está `AUTHORIZED`, e então aciona uma Cobrança. (Uma Cobrança única sem uma Instrução de Cobrança só precisa da autorização `AUTHORIZED`, veja abaixo.) A Belvo processa o pagamento Pix e envia outro webhook quando o status da Cobrança muda. Assim como na autorização, você busca a Cobrança com uma solicitação `GET` para ver se foi bem-sucedida ou falhou. Fase 2: Criação de Pagamento cobre os Passos 2 e 3.

As duas fases são independentes
A Fase 1 e a Fase 2 são fracamente acopladas. A Belvo não vincula as duas juntas, então armazene os IDs dos seus itens, autorizações e Cobranças juntos para correlacioná-los no seu próprio sistema.

Na verdade, a Fase 1 é opcional. Com uma Autorização de Pagamento `AUTHORIZED` você pode acionar uma Cobrança diretamente, uma coleta única, sem criar uma Instrução de Cobrança.

## Opções de integração

Configurar as Smart Collections combina dois caminhos de integração. Use o OFDA Widget para integrar usuários e criar um Link para monitoramento de saldo, e a Payments API (API Direta (Smart Transfers)) para criar Autorizações de Pagamento e Cobranças.

Para gerenciar Instruções de Cobrança, veja Fase 1: Verificação de Saldo e a referência da API de Instruções de Cobrança.