# Fase 2: Criação de Pagamento (API Direta) 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. Na Fase 2 das Smart Collections, você coleta os fundos com **Smart Transfers**, o produto de Pagamentos da Belvo para movimentar dinheiro entre contas mantidas pelo mesmo usuário. Você cria uma **Autorização de Pagamento** de Smart Transfers uma vez e, em seguida, aciona uma **Cobrança** cada vez que a Fase 1 informa que há fundos suficientes. A integração completa passo a passo, com todos os campos, respostas e status, está no guia API Direta (Smart Transfers). Esta página cobre apenas o que é específico para usar Smart Transfers junto com a Fase 1: Verificação de Saldo. ```mermaid sequenceDiagram participant Client as Your application participant Aggregation as Belvo Aggregation API participant Payments as Belvo Payments API Client->>Payments: POST /payments/br/payment-authorizations/ Note over Client, Payments: Your user approves it at their bank Payments->>Client: Webhook: PAYMENT_AUTHORIZATION Client->>Payments: GET /payments/br/payment-authorizations/{id}/ Payments-->>Client: 200 OK (status: AUTHORIZED) Aggregation->>Client: Webhook: item_ready_to_charge (data.amount) 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 (status: SETTLED or FAILED) ``` ## 1. Crie a Autorização de Pagamento antecipadamente Crie a Autorização de Pagamento de Transferências Inteligentes **em paralelo** com sua Instrução de Coleta da Fase 1, para que já esteja `AUTHORIZED` quando `item_ready_to_charge` chegar. Siga Criar uma Autorização de Pagamento, e tenha em mente os seguintes pontos: - **Uma autorização, várias Cobranças.** Crie uma autorização por usuário e reutilize-a para cada Cobrança. Dimensione `total_allowed_amount`, `payment_transaction_limit` e `periodic_limits` para cobrir os itens que você espera coletar. - **O beneficiário deve ser mantido pelo usuário.** Transferências Inteligentes apenas movem fundos entre contas mantidas pela mesma pessoa (mesmo CPF) ou empresa (mesma raiz do CNPJ). - **Use o mesmo banco do Link.** Defina `payer.institution` para a instituição de pagamentos que corresponde ao banco do Link que você monitora na Fase 1. A Belvo não pode verificar isso para você, pois a autorização não faz referência ao Link. ### Debitar a conta que você monitora Na Fase 1, a Belvo verifica o saldo de **todas** as contas que o usuário compartilhou em seu consentimento de dados e envia `item_ready_to_charge` assim que **qualquer uma** delas tiver fundos suficientes. O webhook não informa qual conta foi. Para garantir que os Débitos sejam feitos na conta que você monitora, crie a autorização com os detalhes dessa conta em `payer.account_details` (`account_type`, `ispb`, `issuer`, `number`). Você pode obter `issuer` e `number` da `agency` e `number` da conta na Agregação Bancária. Veja Debitar uma conta específica. Caso contrário, o seu usuário escolhe a conta no banco, e pode não ser aquela cujo saldo foi verificado. ## 2. Cobrar quando `item_ready_to_charge` chegar Quando você receber `item_ready_to_charge`, verifique se a autorização está `AUTHORIZED`, e então crie uma Cobrança contra ela: - Defina `amount` para o `data.amount` do webhook. - Defina `date` para hoje, para que os fundos sejam coletados enquanto estão disponíveis. - Defina `external_id` para um UUID que você armazena junto com o item. A Belvo não vincula Instruções de Cobrança, autorizações e Cobranças entre si, e o `external_id` de uma Cobrança deve ser um UUID, então o próprio `external_id` do item só pode ser reutilizado se também for um UUID. Fase 1 é opcional Você não precisa de uma Instrução de Cobrança para cobrar. Com uma Autorização de Pagamento `AUTHORIZED`, você pode criar uma Cobrança a qualquer momento. A Fase 1 só é necessária quando você quer que a Belvo informe quando a conta tem fundos suficientes. ## 3. Acompanhe a Cobrança A Belvo envia um webhook `CHARGE` cada vez que o status da Cobrança muda. Busque a Cobrança para lê-la: `SETTLED` significa que os fundos saíram da conta do usuário; `FAILED` significa que não saíram, e `status_reason_code` informa o motivo (por exemplo, `INSUFFICIENT_FUNDS` se o saldo caiu após a Fase 1 verificá-lo). Uma Cobrança falhada não reinicia a Fase 1 Uma vez que um item atinge `item_ready_to_charge`, a Belvo para de monitorá-lo, mesmo que a Cobrança que você criar posteriormente falhe. Para tentar novamente, crie uma **nova** Instrução de Cobrança para esse valor. Reutilizar o mesmo `external_id` do item é permitido. ## Melhores práticas **Correlacione tudo com seus próprios IDs.** Armazene o `id` do item, o `id` da autorização e o `id` da Charge (e seus `external_id`s) juntos, para que você possa reconstruir a qual item cada Charge foi liquidada. **Retorne `2XX` rapidamente dos seus endpoints de webhook.** Processe a lógica de negócios de forma assíncrona para não exceder o tempo limite e acionar novas tentativas. **Reconcile itens que nunca produzem uma Charge.** A Fase 1 não envia webhook quando as janelas de um item terminam sem fundos suficientes. Acompanhe seus itens e faça o acompanhamento de qualquer um que fique obsoleto. Você pode verificar o status de cada item para ver como ele terminou. **Evite Charges duplicadas.** Smart Transfers ainda não suporta chaves de idempotência. Se uma solicitação de Charge exceder o tempo limite, liste as Charges da autorização e procure seu `external_id` antes de tentar novamente.