Registro y Seguimiento de Portafolios de Préstamos

La API de Préstamos de Belvo te permite registrar instantáneas de portafolios de préstamos para clientes con débito directo. Cada instantánea es tanto un registro del estado actual de tu préstamo como una instrucción de cobro — tan pronto como envíes un POST de una instantánea, Belvo intenta automáticamente un cobro por débito directo para ese cliente el mismo día (o el siguiente día hábil), de acuerdo con tu acuerdo de Cobros Gestionados.

El flujo general es:

1. POST de una instantánea de préstamo — proporciona el estado actual del préstamo, incluyendo el defaultDate (la fecha en que el préstamo se volvió moroso).
2. Belvo cobra inmediatamente — no se requiere ninguna acción adicional de tu parte. Belvo activa el débito directo el mismo día de tu solicitud (o el siguiente día hábil).
3. Recibe un webhook — Belvo te notifica el resultado del cobro.
4. POST de una nueva instantánea — cada vez que desees que Belvo intente otro cobro, envía una nueva instantánea.

Antes de comenzar, asegúrate de:

1. Generar tus claves API.
2. Configurar un webhook para escuchar eventos.
3. Tener un cliente y un método de pago existentes creados. Consulta Pagos por Débito Directo vía API para obtener instrucciones de configuración.

Cada vez que realizas una solicitud POST /loans, Belvo crea una instantánea de préstamo — un registro del estado actual del préstamo en un momento específico. Belvo establece automáticamente la fecha de recolección (targetCollectionDate) al día actual o al siguiente día hábil — no puedes especificarla en la solicitud.

• Primer POST para un par merchantCustomerId + paymentMethodId: Belvo crea un registro de préstamo principal en segundo plano y le adjunta la instantánea. No interactuarás directamente con el préstamo principal.
• POSTs subsecuentes para el mismo par: Belvo adjunta la nueva instantánea al préstamo existente. Esto te proporciona un historial de auditoría de cada solicitud de recolección que has realizado.

Para programar una cobranza, realiza una solicitud POST Crear una instantánea de préstamo:

{
  "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 los parámetros opcionales, consulta la referencia de la API POST Crear una instantánea de préstamo.

Una solicitud exitosa devuelve una respuesta 201 Created con el ID de la nueva instantánea creada:

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

Guarda este id — puedes usarlo para recuperar los detalles de la instantánea más tarde.

Para recuperar todas las instantáneas, realiza una solicitud de Listar todas las instantáneas de préstamos.

Recomendamos filtrar por merchant_customer_id para limitar los resultados a un solo cliente:

GET /loans?merchant_customer_id=CUST001234

Esto devuelve una lista plana de cada instantánea publicada para ese cliente, a través de todos sus métodos de pago, en orden cronológico inverso.

Para recuperar una instantánea específica, realiza una solicitud de Obtener los detalles de una instantánea de préstamo utilizando el id de la instantánea que se devolvió cuando la creaste:

GET /loans/{id}

Cuando Belvo intenta realizar el cobro por débito directo desencadenado por un snapshot de préstamo, recibes un webhook payment_request_update con el 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
  }
}

El details.id en el payload del webhook es el ID de la solicitud de pago, no el ID del snapshot de préstamo. Para la lista completa de códigos de failedReason, consulta Códigos de Error Bancario.

Para información general sobre la configuración de webhooks, política de reintentos y campos del payload, consulta Webhooks.