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