Skip to main content

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.

ArccNova v2 es una plataforma SaaS donde cada tenant (empresa inmobiliaria) cobra a sus propios clientes finales (compradores de lotes). El diseño de pagos resuelve dos problemas a la vez: cómo el dinero llega directamente a la empresa sin que ArccNova actúe como intermediario financiero regulado, y cómo ArccNova retiene automáticamente su fee de plataforma sin redistribución manual.

​
ADR-004 — Pagos: Stripe Connect Express

Fecha: 2026-06-05 | Estado: Aceptado (actualizado 2026-06-10)

​
Contexto

ArccNova no debe actuar como intermediario que reciba y redistribuya dinero, por razones de compliance (CNBV en MX, FinCEN en US). Sin embargo, necesita orquestar los pagos en nombre de sus tenants y cobrar un porcentaje de plataforma.

​
Opciones evaluadas

OpciónDescripción
Stripe Connect Express ✅Cada tenant tiene su propia cuenta Stripe; ArccNova orquesta
Platform charges (cuenta única)ArccNova recibe todo el dinero y redistribuye — riesgo regulatorio
Conekta (MX)PSP local de México, sin soporte nativo para US ni Connect

​
Decisión

Stripe Connect Express. Cada tenant hace onboarding con su propia cuenta Stripe Express. ArccNova crea PaymentIntents en nombre del tenant y cobra un application fee. Los fondos van directamente a la cuenta Stripe del tenant.

​
Arquitectura de la cuenta

ArccNova (Platform Account)
│
├── Tenant A (Connected Account Express)
│   ├── PaymentIntent → cliente comprador de Lote 12
│   └── application_fee_amount = 1% del monto
│
├── Tenant B (Connected Account Express)
│   └── PaymentIntent → cliente comprador de Lote 7
│
└── SaaS subscriptions → Main Stripe Account (sin Connect)
Los pagos de suscripción SaaS (empresa → ArccNova por el plan mensual) usan la cuenta principal de Stripe de ArccNova, no Connect Express. Connect Express es solo para los cobros del tenant a sus clientes finales.

​
Métodos de pago soportados

MétodoMercadoLímiteNotas
Tarjeta de crédito/débitoMX + USSin límite específicoCargo inmediato
SPEI (transferencia bancaria)MXSin límite específicoAsíncrono; demora bancaria
OXXO (efectivo)MXHasta 10,000 MXNAsíncrono; hasta 24 h para confirmar
El pago OXXO es asíncrono por naturaleza: el cliente paga en tienda y la confirmación puede tardar hasta 24 horas. El sistema debe manejar este caso frente a la regla anti-doble-cobro. El comportamiento exacto está marcado como punto abierto D5 (ver /reference/open-points).

​
Reglas de negocio confirmadas (T03)

  • ArccNova retiene el 1% como application_fee_amount automáticamente, sin tocar el flujo del dinero.
  • El pago en línea coexiste con la cobranza en caja: el sistema valida antes de crear el cobro en línea que no haya conflicto (sin pagos parciales ni anticipados) para evitar doble cobro.
  • El cambio de estado del pago se notifica al navegador vía SSE (ADR-019) — el módulo Collections actualiza la UI en tiempo real.

​
Flujo de pago en línea

1

Validación anti-doble-cobro

El WebClient solicita al API iniciar un pago en línea para una cuota (MultipleInstallments). El backend verifica que no exista un OnlinePayment activo para la misma cuota y que no haya un cobro de caja en proceso.
2

Creación del PaymentIntent

El API crea el PaymentIntent en Stripe en nombre de la cuenta Connect del tenant, incluyendo el application_fee_amount (1%). Stripe devuelve un client_secret.
3

Pago en el navegador

El WebClient usa el client_secret con Stripe.js para renderizar el formulario de pago (tarjeta, SPEI u OXXO). El número de tarjeta nunca toca los servidores de ArccNova.
4

Webhook de confirmación

Stripe envía payment_intent.succeeded (o el equivalente para SPEI/OXXO) al endpoint de webhook del API. El backend procesa el evento y aplica el cobro usando el mismo motor de cuotas de Collections (Cobros-Flujos 10).
5

Notificación SSE

El backend transmite el cambio de estado por SSE al navegador del usuario conectado. La UI de Collections se actualiza sin recargar la página.

​
Tablas del módulo Payments

-- Cuenta Stripe Connect por tenant (una por empresa)
CREATE TABLE "StripeConnectAccounts" (
    "Id"                bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    "TenantId"          bigint NOT NULL UNIQUE REFERENCES "Tenants"("Id"),
    "StripeAccountId"   varchar(100) NOT NULL UNIQUE,
    "OnboardingStatus"  varchar(30) NOT NULL DEFAULT 'pending',
    "ChargesEnabled"    boolean NOT NULL DEFAULT false,
    "DetailsSubmitted"  boolean NOT NULL DEFAULT false,
    "CreatedAtUtc"      timestamptz NOT NULL DEFAULT timezone('utc', now()),
    "UpdatedAtUtc"      timestamptz NOT NULL DEFAULT timezone('utc', now())
);

-- Registro de cada intento de pago en línea
-- CollectionId enlaza el cobro generado por el webhook
CREATE TABLE "OnlinePayments" (
    "Id"                     bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    "PublicId"               uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
    "TenantId"               bigint NOT NULL REFERENCES "Tenants"("Id"),
    "BranchId"               bigint NOT NULL REFERENCES "Branches"("Id"),
    "SaleId"                 bigint NOT NULL REFERENCES "Sales"("Id"),
    "FinancingTypeId"        bigint NOT NULL REFERENCES "FinancingTypes"("Id"),
    "StripePaymentIntentId"  varchar(100) NOT NULL UNIQUE,
    "Amount"                 numeric(18,2) NOT NULL,
    "Currency"               varchar(3) NOT NULL,
    "ApplicationFeeAmount"   numeric(18,2) NOT NULL DEFAULT 0,
    "Method"                 varchar(20) NOT NULL,   -- card | spei | oxxo
    "Status"                 varchar(30) NOT NULL DEFAULT 'pending',
    "CollectionId"           bigint REFERENCES "Collections"("Id"),
    "CreatedAtUtc"           timestamptz NOT NULL DEFAULT timezone('utc', now()),
    "ConfirmedAtUtc"         timestamptz
);

​
ADR-005 y ADR-006 — Funcionalidades Fiscales Pospuestas

Dos ADR relacionados con pagos fueron evaluados y pospuestos para esta versión:
La emisión de Comprobantes Fiscales Digitales por Internet (CFDI 4.0) mediante un Proveedor Autorizado de Certificación (PAC) fue evaluada. Se pospone porque el cliente no la solicitó como requisito del MVP y su implementación requiere integración con el SAT que añade complejidad significativa. Estado: Pospuesto (2026-06-10).
Stripe Tax para el cálculo automático de impuestos en el mercado de EE.UU. fue considerado. Stripe Connect Express lo habilita sin costo adicional de integración. Se pospone junto con el módulo fiscal completo hasta que el negocio lo solicite. Estado: Pospuesto (2026-06-10).
Los módulos Tax/, Rentals/ y Materials/ tienen scaffolding físico en la solución pero ningún código de implementación. Se activarán como épicas futuras cuando el negocio defina sus requisitos. El CFDI de nómina (ISR, IMSS, INFONAVIT) también está fuera de alcance — el módulo Hr.Payroll calcula nómina sin cálculo fiscal en esta versión.

Build docs developers (and LLMs) love

Get started for freeTalk to us