Spec técnico

Cómo funciona vueltito por dentro.

Arquitectura, flujo de checkout, ledger auditable, integraciones y roadmap. Una vista técnica de cómo procesamos microaportes visibles y conciliables sobre pagos cotidianos.

Versión preliminar · 2026 Microaportes · Argentina Mercado Pago · Ledger · ONGs verificadas

Resumen

vueltito habilita microaportes autorizados sobre pagos cotidianos. En el checkout de un comercio integrado, el comprador acepta un aporte —un monto fijo, un porcentaje chico de la compra o un redondeo— de forma visible. vueltito calcula el aporte, registra el consentimiento y lo asigna a una ONG verificada, con ledger auditable y conciliación.

La estrategia no depende de un acuerdo directo con Mercado Pago desde el día uno. El primer wedge es una suite de plugins para comercios que ya cobran con Mercado Pago; con esos pilotos se genera tracción y evidencia.

La tesis es simple: vueltito habilita microaportes solidarios, visibles y conciliables en el checkout —procesados con Mercado Pago cuando es posible y trazables hacia ONGs verificadas. vueltito no intercepta ni desvía pagos personales.

Arquitectura en tres capas

El diseño separa la lógica de negocio del procesamiento de pagos y de cada canal de venta. Los plugins no duplican cálculos ni reglas: solo adaptan el canal.

1 · Core vueltito

El servicio central concentra la lógica: donantes, reglas de aporte, ONGs, campañas, comercios, transacciones, ledger, conciliación, leaderboard y auditoría.

2 · Payment layer

Integra Mercado Pago (Checkout Pro / API): OAuth del vendedor, marketplace_fee / application_fee, webhooks, idempotencia, reembolsos y conciliación de reportes.

3 · Adapter layer

Cada canal resuelve instalación y autenticación del comercio, lectura del carrito, UI de consentimiento, envío del cálculo al Core y creación/redirección del pago.

Flujo de checkout con aporte

  1. El adapter lee subtotal, moneda, ítems y comercio.
  2. Le pide al Core las opciones de aporte: fijo, porcentaje, redondeo, límites mínimos/máximos y ONG/campaña elegida.
  3. La interfaz muestra el aporte como una línea visible antes de pagar.
  4. El comprador acepta y se registra el consentimiento con su snapshot.
  5. El Payment layer crea la preferencia/pago en Mercado Pago con marketplace_fee / application_fee, external_reference y metadata de vueltito.
  6. Mercado Pago procesa el pago y el webhook actualiza el estado.
  7. El ledger registra compra, aporte, split y asignación a la ONG.
  8. El leaderboard se actualiza solo si el donante optó por participar.

Ledger y principios de datos

  • Ledger append-only: nunca se editan entradas históricas; los cambios se registran como reversas.
  • Webhooks idempotentes: ningún evento puede crear un doble aporte ni una doble entrada de ledger.
  • Snapshots de la regla y del consentimiento por cada transacción.
  • Estados separados: pago, split, asignación a ONG y liquidación se modelan por separado.
  • Sin PII en el leaderboard: alias por defecto y visibilidad opt-in.

Tipos de entrada del ledger

purchase_observed donation_authorized split_received ngo_allocated payout_sent refund_reversed adjustment

Integraciones

Cada canal tiene un nivel de control técnico y requisitos distintos. El roadmap prioriza dónde podemos demostrar valor primero.

WooCommerce

Primer MVP

Mejor control técnico y demo en sandbox. Plugin propio que muestra el aporte y crea la preferencia.

Tiendanube

Piloto

App con OAuth y payment option. Alta relevancia en Argentina; validación en producción.

Shopify

Roadmap

App de configuración e intención; payments/checkout UI requieren Plus o ser partner aprobado.

QR / Point

Roadmap

Pagos presenciales con Orders, POS y conciliación. Requiere caja y partnership más cercano.

VTEX

Enterprise

Payment Provider Protocol con homologación y test suite. Expansión a comercios grandes.

Adobe Commerce

Enterprise

Módulo PHP y customización de checkout. Posterior a un core y una integración MP maduros.

Seguridad y privacidad

  • Tokens de Mercado Pago y de las plataformas cifrados.
  • Validación de firma de webhooks donde la plataforma la provea.
  • No se guardan tarjetas ni datos sensibles de pago.
  • Leaderboard opt-in y alias por defecto.
  • Límites de aporte por transacción y por período.
  • Audit log para cambios en ONGs, payouts y ajustes; permisos separados para admin, comercio y ONG.

Principios de UX

  • El aporte es visible antes de pagar.
  • El usuario entiende la ONG, el monto y la regla.
  • El aporte es opcional y reversible antes de pagar.
  • Nunca se le llama "fee" al aporte hacia el usuario final: es una donación.

Roadmap

  • Fase 0 — Base: spec aprobado, modelo legal/fiscal, sandbox de Mercado Pago, política de reembolsos y lista de ONGs demo.
  • Fase 1 — Core + WooCommerce: Core API, ledger, leaderboard opt-in y demo end-to-end con Checkout Pro sandbox.
  • Fase 2 — Tiendanube: app OAuth, payment option y piloto con pagos mínimos.
  • Fase 3 — Enterprise: conector VTEX (PPP) y módulo Adobe Commerce.
  • Fase 4 — Shopify: según acceso a Plus / partner aprobado.
  • Fase 5 — Presencial y partnership: QR/Point y propuesta de alianza con Mercado Pago con datos de conversión.
Recomendación: proceder con una arquitectura que no dependa de promesas no verificadas. Primero confianza y evidencia; después, escala.