Webhooks y conciliación

Eventos

Cuentas Venti no introduce eventos nuevos: reutiliza los webhooks de checkout que ya conoces.

Evento	Cuándo	Cómo reconocer una cuenta
`checkout.paid`	Un cliente pagó un checkout con su cuenta	`successful_object: "account_entry"` y `account_entry_id` presente (`payment_id` es `null`)
`checkout.paid`	Un cliente pagó su estado de cuenta	`successful_object: "payment"` o `"loan"` (medio externo); el checkout es el `repayment_checkout_id` de un statement
`checkout.refunded`	Devolviste un checkout pagado con cuenta	`refunded: true`, `refunded_amount` acumulado

Para distinguir un checkout de cobro de una venta normal, guarda los repayment_checkout_id de tus statements (o consulta GET /statements?financial_account_id=... al recibir el evento). Los checkouts de cobro también llevan metadata.statement_id.

Identificar el medio de pago en un checkout

Un checkout pagado con cuenta:

{
  "id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
  "status": "paid",
  "successful_object": "account_entry",
  "account_entry_id": "ae_Qm2vX9pLkR4TnW8sHjD3fGa7",
  "payment_id": null,
  "payment_method_id": null
}

Con expand[]=account_entry.financial_account.program obtienes en la misma llamada la cuenta y el nombre del programa con que se pagó — útil para boletas, correos y tu backoffice.

Conciliación contable

La regla de oro: las ventas con cuenta no mueven dinero; la cobranza sí.

Evento de negocio	Libro mayor (`AccountEntry`)	Tu balance en Venti
Venta pagada con cuenta	`purchase` (débito)	Sin impacto
Devolución de esa venta	`refund` (crédito)	Sin impacto
Pago del estado de cuenta	`repayment` (crédito)	Abono menos comisiones estándar

En la práctica:

Tu cuenta por cobrar con los clientes = la suma de los posted_balance negativos de tus cuentas (o el closing_balance de los statements impagos).
Tu flujo de caja en Venti solo refleja cobranzas. Si concilias ventas contra abonos, excluye las ventas con cuenta y concíliala contra los repayment.
Cada AccountEntry trae balance_after y un sequence incremental por cuenta: puedes reconstruir el saldo de cualquier cuenta en cualquier punto del tiempo, y detectar huecos si tu réplica pierde eventos.

Idempotencia y consistencia

El libro mayor es append-only y cada movimiento se escribe con una clave de idempotencia interna: reintentos del mismo pago nunca duplican movimientos.
Los webhooks pueden llegar más de una vez (reintentos de 3 días): usa el id del evento o del checkout como clave de deduplicación, como con cualquier otro webhook de Venti.
available puede ser menor que credit_limit + posted_balance durante unos minutos si hay un pago en curso (held_amount > 0): las reservas expiran solas si el cliente no completa el pago.

Modo test

Todo el producto funciona en modo test con tu API key de test: programas, cuentas, pagos con cuenta en el checkout de test y statements. Úsalo para probar tu integración de webhooks y conciliación antes de emitir cuentas reales.