Registrar e Acompanhar Portfólios de Empréstimos

A Loans API da Belvo permite que você registre instantâneos de portfólios de empréstimos para clientes de débito direto. Cada instantâneo é tanto um registro do estado atual do seu empréstimo quanto uma instrução de cobrança — assim que você faz um POST de um instantâneo, a Belvo automaticamente tenta uma cobrança por débito direto para aquele cliente no mesmo dia (ou no próximo dia útil), de acordo com o seu arranjo de Managed Collections.

O fluxo geral é:

1. POST de um instantâneo de empréstimo — forneça o estado atual do empréstimo, incluindo o defaultDate (a data em que o empréstimo se tornou inadimplente).
2. Belvo coleta imediatamente — nenhuma ação adicional é necessária de sua parte. A Belvo aciona o débito direto no mesmo dia do seu pedido (ou no próximo dia útil).
3. Receba um webhook — a Belvo notifica você sobre o resultado da cobrança.
4. POST de um novo instantâneo — cada vez que você quiser que a Belvo tente outra cobrança, envie um novo instantâneo.

Antes de começar, certifique-se de:

1. Gerar suas chaves de API.
2. Configurar um webhook para escutar eventos.
3. Ter um cliente existente e método de pagamento criado. Veja Pagamentos por Débito Direto via API para instruções de configuração.

Cada vez que você faz uma solicitação POST /loans, a Belvo cria um snapshot de empréstimo — um registro do estado atual do empréstimo em um determinado momento. A Belvo define automaticamente a data de coleta (targetCollectionDate) para o dia atual ou o próximo dia útil — você não pode especificá-la na solicitação.

• Primeiro POST para um par merchantCustomerId + paymentMethodId: a Belvo cria um registro de empréstimo pai em segundo plano e anexa o snapshot a ele. Você não interagirá diretamente com o empréstimo pai.
• POSTs subsequentes para o mesmo par: a Belvo anexa o novo snapshot ao empréstimo existente. Isso fornece um histórico de auditoria de cada solicitação de coleta que você fez.

Para agendar uma cobrança, faça uma solicitação POST Criar um instantâneo de empréstimo:

{
  "paymentMethodId": "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b",
  "merchantCustomerId": "CUST001234",
  "daysOverdue": 45,
  "totalBalance": 15000.50,
  "principalAmount": 12000.00,
  "defaultDate": "2026-03-01",
  "issueDate": "2026-01-15"
}

Para todos os parâmetros opcionais, consulte a referência da API POST Create a loan snapshot.

Uma solicitação bem-sucedida retorna uma resposta 201 Created com o ID do snapshot recém-criado:

{
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

Salve este id — você pode usá-lo para recuperar os detalhes do snapshot mais tarde.

Para recuperar todos os instantâneos, faça uma solicitação de Listar todos os instantâneos de empréstimos.

Recomendamos filtrar por merchant_customer_id para limitar os resultados a um único cliente:

GET /loans?merchant_customer_id=CUST001234

Isso retorna uma lista plana de todos os instantâneos postados para esse cliente, em todos os seus métodos de pagamento, em ordem cronológica inversa.

Para recuperar um instantâneo específico, faça uma solicitação de Obter detalhes de um instantâneo de empréstimo usando o id do instantâneo retornado quando você o criou:

GET /loans/{id}

Quando a Belvo tenta a cobrança por débito direto acionada por um snapshot de empréstimo, você recebe um webhook payment_request_update com o resultado.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_successful",
  "datetime": "2026-06-10T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "successful",
    "amount": 15000.50,
    "failedReason": null,
    "failedMessage": null
  }
}

O details.id no payload do webhook é o ID da solicitação de pagamento, não o ID do snapshot de empréstimo. Para a lista completa de códigos failedReason, veja Códigos de Erro Bancário.

Para informações gerais sobre configuração de webhooks, política de tentativas e campos de payload, veja Webhooks.