Cuotas y cobranza

Cuándo llega el dinero a tu balance

Tu abono no depende de que el cliente pague sus cuotas. Cuando el préstamo se autoriza (se cobró la primera cuota), Venti registra en tu balance:

Transacción	Monto	Qué es
`loan`	`+ amount`	El monto completo de la venta.
`fee`	`− fee`	La comisión de Venti por la transacción.
`payout_fee`	`− payout_schedule_fee`	Solo si tu calendario de pagos tiene costo.
`tax_fee`	`− IVA`	El IVA sobre las comisiones.

La fecha contable se cuenta desde la autorización del préstamo (authorized_at) y el abono sigue tu calendario de pagos habitual (1 o 3 días hábiles). En tus transacciones de balance y en tus payouts, una venta en cuotas se ve igual que cualquier otra venta: un abono por el total menos comisiones.

El sobrecargo (surcharge_amount), si tu configuración lo define, lo paga el cliente sumado a sus cuotas y no afecta tu abono.
Los intereses y cargos por atraso los paga el cliente a Venti; tampoco pasan por tu balance.

El calendario de cuotas

Cada préstamo sigue un programa de cuotas (ej: cl_1n2l_bw = 1 cuota hoy + 2 quincenales). El programa define la cantidad de cuotas, el intervalo, el interés (si aplica) y los cargos por atraso. El total a repartir entre las cuotas del cliente es amount + sobrecargo (con IVA) + interés.

La cuota 1 se cobra al autorizar el préstamo, con la tarjeta que el cliente eligió. Es lo que concreta el crédito. Un préstamo aprobado cuya primera cuota no se logra cobrar se reintenta y, si no se autoriza, se cancela automáticamente a los 20 minutos; un préstamo open sin actividad se cancela después de 1 hora.
Las cuotas restantes nacen open, cada una con su due_at.
Los programas disponibles y su detalle exacto para un préstamo se pueden previsualizar con GET /loans/{id}/installments_preview (endpoint público — es lo que la página de pago le muestra al cliente).

Cobranza automática

En el vencimiento de cada cuota, Venti la cobra automáticamente a la tarjeta guardada del préstamo:

Cobro exitoso → la cuota pasa a paid (webhook installment.paid).
Cobro fallido con la cuota vencida → pasa a past_due (webhook installment.past_due) y Venti sigue reintentando el cobro automáticamente durante los días siguientes.

Cargos por atraso

Una cuota past_due puede acumular cargos por atraso según las condiciones del crédito. En la API los ves en dos campos de la cuota:

total_late_fee_amount — el cargo vigente ahora (campo calculado; 0 si la cuota no está atrasada).
applied_late_fee_amount — el cargo que efectivamente se cobró cuando la cuota se pagó.

Cuando una cuota atrasada se paga (automática o manualmente), el cobro incluye sus cargos por atraso vigentes. Los cargos los paga el cliente a Venti; no pasan por tu balance.

Recordatorios al cliente

Venti acompaña al cliente durante todo el ciclo de cobro: le recuerda sus vencimientos por sus canales de contacto y gestiona la cobranza de las deudas atrasadas — nada de esto te involucra ni afecta tu abono.

Pago manual de cuotas

El cliente, desde su billetera Venti (pay.ventipay.com/wallet), puede pagar cualquier cuota pendiente cuando quiera: con una de sus tarjetas, varias cuotas de una vez, o con medios asíncronos como Webpay o transferencia.
Tú también puedes cobrar una cuota con POST /installments/{id}/authorize (scope installments:write), por ejemplo para regularizar un caso puntual con el cliente en línea. Con update_due_at: true puedes además cobrar anticipadamente una cuota cuyo vencimiento aún no llega.

Devoluciones

POST /loans/{id}/refund devuelve una venta en cuotas, total o parcialmente (amount en unidades menores; omítelo para devolver todo lo disponible). Se admiten devoluciones parciales sucesivas hasta el monto original (available_for_refund).

Qué hace Venti, empezando por las últimas cuotas:

Las cuotas pendientes (open/past_due) alcanzadas por la devolución se cancelan (o reducen su monto, si la devolución es parcial).
Lo que el cliente ya pagó se le devuelve como saldo a favor en su cuenta Venti. Los cargos por atraso no se devuelven.
El monto devuelto se descuenta de tu balance — tú recibiste el total por adelantado, así que la devolución corre por tu cuenta, independiente de cuánto haya alcanzado a pagar el cliente.

Condiciones: el préstamo debe estar autorizado y sin disputa, y tu balance debe cubrir la devolución (error insufficient_balance si no alcanza). El préstamo queda con refunded: true y refunded_amount acumulado; si venía de un checkout, el checkout también se marca refunded.

Siguiente paso

Sigue con webhooks y conciliación para integrar estos eventos en tu backoffice.