El módulo Payments permite que el cliente final —el comprador de lotes— pague sus cuotas en línea a través de la plataforma. Utiliza Stripe Connect Express para que el dinero caiga directamente en la cuenta Stripe de la empresa inmobiliaria (tenant), mientras ArccNova retiene automáticamente su comisión del 1%. Los pagos en línea coexisten con la cobranza tradicional en caja; ambos canales comparten el mismo motor de cuotas y vencimientos del módulo Collections.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/DevCarlosRodriguez/Documentacion-Arccnova-2.0/llms.txt
Use this file to discover all available pages before exploring further.
Arquitectura: Stripe Connect Express
La elección de Stripe Connect Express (ADR-004) responde a un requisito de compliance: ArccNova no debe actuar como intermediario que reciba y redistribuya dinero (CNBV en México, FinCEN en EE.UU.). Con Connect Express cada tenant tiene su propia cuenta Stripe y el flujo del dinero nunca pasa por ArccNova.ArccNova
Cuenta de plataforma. Orquesta los PaymentIntents en nombre del tenant y cobra el 1% de application fee automáticamente, sin tocar el flujo del dinero (T03).
Empresa (tenant)
Cuenta Connect Express. El dinero cae directo aquí. La empresa debe completar el onboarding de Stripe antes de poder recibir pagos en línea.
Cliente final
Comprador de lotes. Paga con tarjeta, SPEI o OXXO desde el portal o enlace que le facilite su asesor.
La suscripción SaaS de la empresa a ArccNova (BillingSaas) usa la cuenta principal de Stripe, no Connect Express. Son flujos completamente independientes.
Métodos de pago soportados
| Método | Descripción | Límite |
|---|---|---|
| Tarjeta | Débito o crédito vía Stripe Checkout | Sin límite definido |
| SPEI | Transferencia bancaria electrónica (México) | Sin límite definido |
| OXXO | Pago en efectivo en tiendas de conveniencia (México) | Hasta $10,000 MXN por transacción |
Flujos
Onboarding Connect de la empresa
La empresa completa el flujo estándar de onboarding de Stripe Express desde su panel de configuración en ArccNova. Hasta que no tenga cuenta conectada activa, no puede recibir pagos en línea.
Calcular la cuota vigente
Antes de crear el cobro, el sistema llama a Collections (
ValidateNextCollection) para determinar la cuota vigente, que puede incluir la cuota base más mora si aplica.Validación anti doble cobro
El sistema verifica que la cuota no tenga pagos parciales y que no se intente un pago anticipado. Si alguna condición falla, el pago en línea se rechaza. Estas variantes (parcial, anticipado) solo están disponibles en caja (T03).
Creación del PaymentIntent
Se crea el
PaymentIntent en la cuenta Connect de la empresa con:- El monto de la cuota vigente.
- El 1% de application fee para ArccNova.
- Metadata de la venta (
SaleId, tipo de financiamiento) para la reconciliación en el webhook.
El cliente paga
El cliente completa el pago en Stripe Checkout usando tarjeta, SPEI u OXXO. El flujo es íntegramente gestionado por Stripe; las llaves y webhooks son exclusivos del backend —el front solo dispara la sesión (decisión 11).
Recepción y procesamiento del webhook
Stripe envía el evento
PaymentIntent al backend de ArccNova:- Se valida la firma del webhook de Stripe.
- Se extrae la metadata (
SaleId, tipo de financiamiento). - Se inserta el cobro con origen
Stripeusando el mismo motor y las mismas reglas de vencimiento que el cobro manual en caja (CalculateLastPaymentDate). - Si el saldo de la venta llega a cero se ejecuta la liquidación (
SettleSale), igual que en caja.
Reglas de negocio
| Regla | Descripción |
|---|---|
| RN-01 | ArccNova retiene el 1% de cada cobro en línea vía application fee automática (T03). |
| RN-02 | Métodos habilitados: tarjeta, SPEI y OXXO con tope de $10,000 MXN (T03). |
| RN-03 | Sin pagos parciales ni anticipados en línea; esas variantes solo en caja (T03). |
| RN-04 | El motor de cuotas y vencimientos es el mismo que en el cobro manual (CalculateLastPaymentDate). |
| RN-05 | Caja y línea coexisten; el mismo cliente puede pagar una cuota en caja y la siguiente en línea. |
| RN-06 | Notificación de pago recibido: SSE al navegador + notificación de sistema + correo al cliente (decisión 19, T05). |
| RN-07 | Llaves Stripe y webhook solo en el backend; el frontend solo dispara la sesión de Checkout (decisión 11). |
Puntos abiertos
Canal de acceso del cliente final
Canal de acceso del cliente final
El mecanismo por el que el cliente final accede al pago en línea (portal público, enlace enviado por el asesor, QR en el estado de cuenta) no está especificado en las fuentes. Definir con el equipo antes de implementar la UX del cliente.
Pagos OXXO pendientes de confirmación
Pagos OXXO pendientes de confirmación
OXXO es un método asíncrono por naturaleza: el cliente recibe un voucher y paga en tienda horas o días después. Esto genera una ventana donde la cuota tiene un cobro “pendiente” pero no confirmado. El manejo de este estado intermedio frente a la regla anti doble cobro debe detallarse al diseñar el flujo de OXXO.