# Modelo de Mercado Pago para LavanderOS **Documento de análisis** **Fecha:** 6 de septiembre de 2026 **Estado:** decisión arquitectónica confirmada ## 1. Objetivo Integrar Mercado Pago en LavanderOS para que cada lavandería pueda cobrar a sus propios clientes mediante enlaces de pago, códigos QR y terminales Point, conservando la separación financiera entre negocios. Este documento no describe el cobro de la mensualidad de LavanderOS. Los pagos operativos de las lavanderías y las suscripciones del SaaS son flujos financieros distintos. ## 2. Principio principal El dinero de una operación se acredita en la cuenta de Mercado Pago asociada al `Access Token` utilizado para crear el cobro. Por lo tanto, LavanderOS no debe utilizar una sola cuenta recaudadora para procesar las ventas de todas las lavanderías. Cada tenant deberá vincular su propia cuenta de Mercado Pago y autorizar a LavanderOS mediante OAuth. Esta modalidad de cuentas conectadas fue confirmada como el modelo objetivo: el propietario controla su cuenta, recibe directamente sus ventas y puede revocar la autorización. LavanderOS registra y concilia la operación, pero no custodia ni transfiere fondos de las lavanderías. Las credenciales actualmente configuradas en el `.env` corresponden exclusivamente al desarrollo y a las pruebas de integración. Si se utilizaran para todos los cobros, el dinero se dirigiría a la cuenta propietaria de esas credenciales. En producción, el `CLIENT_ID` y el `CLIENT_SECRET` identificarán la aplicación LavanderOS; no sustituirán el token OAuth individual de cada lavandería. ## 3. Flujo recomendado 1. El propietario de la lavandería accede a la configuración de pagos. 2. Selecciona **Conectar Mercado Pago**. 3. LavanderOS genera un estado OAuth único, temporal y asociado al tenant. 4. El propietario es redirigido a Mercado Pago. 5. Mercado Pago solicita autenticación y consentimiento. 6. El propietario autoriza a LavanderOS para operar en nombre de su cuenta. 7. Mercado Pago devuelve un código temporal a la URL de retorno. 8. El servidor de LavanderOS intercambia ese código por un `Access Token` y un `Refresh Token`. 9. LavanderOS cifra los tokens y los vincula exclusivamente al `tenant_id`. 10. Los cobros posteriores de esa lavandería se crean usando su propio token. 11. El dinero se acredita en la cuenta Mercado Pago de la lavandería. 12. Mercado Pago envía un webhook y LavanderOS concilia el resultado con la orden local. ```text Cliente de la lavandería | | paga v Mercado Pago | | acredita el importe, menos sus comisiones v Cuenta Mercado Pago de la lavandería | | webhook firmado v LavanderOS actualiza pago, pagado y saldo ``` ## 4. Responsabilidad de cada cuenta ### Cuenta de LavanderOS - Es propietaria de la aplicación de integración. - Inicia y recibe el flujo OAuth. - Identifica a LavanderOS ante Mercado Pago. - No debe recibir automáticamente el dinero operativo de otras lavanderías. - Sus credenciales maestras permanecen sólo en el servidor. ### Cuenta de la lavandería - Es la cuenta recaudadora de sus ventas. - Recibe los pagos realizados por sus clientes. - Asume las comisiones y condiciones comerciales de Mercado Pago. - Vincula sus sucursales, cajas y terminales Point. - Puede revocar la autorización otorgada a LavanderOS. ## 5. Canales contemplados ### Enlace de pago LavanderOS genera un enlace asociado a una orden o saldo. El enlace puede enviarse por correo o mensajería. La orden sólo se considera pagada después de recibir y verificar la confirmación de Mercado Pago. ### Código QR LavanderOS genera o solicita un QR relacionado con la orden, sucursal y caja. El cliente lo escanea y paga desde un dispositivo compatible. El resultado se confirma mediante API y webhook. ### Terminal Point Cada terminal debe estar asociada a la cuenta recaudadora, sucursal y caja correctas. LavanderOS envía el importe y la referencia de la orden a la terminal; nunca captura ni almacena los datos de la tarjeta. ## 6. Modelo comercial recomendado Durante la primera versión productiva: - cada lavandería recibe el 100 % de sus ventas, menos las comisiones de Mercado Pago; - LavanderOS cobra su plan mensual en un proceso separado; - LavanderOS no retiene ni concentra dinero perteneciente a sus clientes; - no se aplica comisión de marketplace sobre cada lavado. Este modelo simplifica conciliación, devoluciones, obligaciones fiscales y separación de fondos. ## 7. Alternativa futura: Split de pagos Mercado Pago ofrece esquemas de marketplace que pueden dividir una operación entre el vendedor y la plataforma. Con esta alternativa, LavanderOS podría cobrar una comisión por transacción y la lavandería recibiría el resto. No se implementará inicialmente porque requiere analizar: - condiciones y aprobación comercial de Mercado Pago; - identificación y requisitos de los vendedores; - comisiones de Mercado Pago y de LavanderOS; - impuestos y facturación; - contracargos y devoluciones; - responsabilidad sobre saldos insuficientes; - compatibilidad real con Point y QR, pues Split no está disponible para todos los productos. La mensualidad del SaaS seguirá siendo el modelo comercial base mientras no exista una decisión distinta. ## 8. Información que almacenará LavanderOS Por cada conexión de una lavandería: - `tenant_id`; - identificador del usuario o collector de Mercado Pago; - ambiente de prueba o producción; - canales habilitados; - token de acceso cifrado; - refresh token cifrado, cuando corresponda; - fecha de expiración y última renovación; - estado de la conexión; - fechas de vinculación y revocación; - usuario de LavanderOS que realizó la vinculación. Por cada intento: - tenant, sucursal, caja y orden; - canal: enlace, QR o Point; - importe y moneda; - referencia externa sin datos personales; - clave de idempotencia; - identificadores de orden y pago de Mercado Pago; - estado local y estado del proveedor; - fechas de creación, aprobación, rechazo, expiración o reembolso; - respuesta técnica sanitizada, sin tokens ni datos de tarjeta. Por cada webhook: - identificador único del evento; - tipo de evento; - identificador del recurso; - fecha de recepción; - resultado de validación de firma; - estado de procesamiento; - número de intentos y último error sanitizado. ### Diseño extensible a otros proveedores La persistencia y los servicios de negocio no deberán depender de nombres exclusivos de Mercado Pago. La conexión de cada tenant se modelará como una cuenta de proveedor con, al menos: - `tenant_id`, `provider`, ambiente e identificador externo de la cuenta; - credenciales cifradas, permisos concedidos y expiración; - estado, fechas de conexión, renovación y revocación; - usuario que conectó o desconectó la cuenta. Los intentos ya utilizan `provider`, referencia externa, identificador del recurso e idempotencia. La implementación deberá exponer una interfaz común para conectar una cuenta, crear enlaces o QR, consultar pagos, procesar webhooks y solicitar reembolsos. Mercado Pago será el primer adaptador; cualquier proveedor futuro deberá evaluarse e implementarse sin alterar la lógica central de órdenes y pagos. ## 9. Reglas de seguridad - Nunca guardar contraseñas de Mercado Pago. - Nunca guardar números completos de tarjeta, CVV ni información sensible del medio de pago. - Cifrar tokens en reposo con una clave independiente del contenido de la base. - No escribir tokens en logs, excepciones o tickets. - Validar `state` y PKCE durante OAuth. - Validar la firma `x-signature` de cada webhook. - Usar HTTPS en las URLs OAuth y webhook. - Aplicar idempotencia para evitar cargos duplicados. - Consultar la API antes de acreditar un pago cuando exista alguna duda. - Aislar todas las conexiones, intentos y eventos por `tenant_id`. - Registrar vinculaciones, desconexiones, devoluciones y cambios sensibles. ## 10. Estados y conciliación Crear un intento no equivale a recibir dinero. LavanderOS actualizará `orders.paid_amount` y `orders.balance_due` únicamente después de confirmar que el pago fue aprobado. Los estados locales deberán contemplar, como mínimo: - pendiente; - requiere acción; - procesando; - aprobado; - rechazado; - cancelado; - expirado; - reembolsado parcialmente; - reembolsado totalmente. Los webhooks pueden llegar repetidos o fuera de orden. El procesamiento debe ser idempotente y comparar la versión o el estado consultado en la API antes de modificar los saldos. ## 11. Desarrollo local Actualmente LavanderOS opera en `localhost` sin dominio ni certificado HTTPS. En local se puede: - validar el token de prueba; - crear intentos y órdenes de prueba; - consultar estados; - simular respuestas; - probar idempotencia y conciliación. Para recibir webhooks reales se necesitará una URL HTTPS pública. Puede utilizarse temporalmente un túnel seguro durante el desarrollo; en producción deberá configurarse el dominio definitivo. Las variables esperadas son: ```dotenv MERCADOPAGO_ENV=sandbox MERCADOPAGO_PUBLIC_KEY= MERCADOPAGO_ACCESS_TOKEN= MERCADOPAGO_CLIENT_ID= MERCADOPAGO_CLIENT_SECRET= MERCADOPAGO_WEBHOOK_SECRET= PAYMENT_CREDENTIALS_KEY_BASE64= ``` Ningún valor secreto debe incluirse en Git, documentación, capturas o conversaciones. ## 11.1 Base técnica implementada Desde el 6 de septiembre de 2026 existe una capa de conexión neutral por proveedor: - `payment_providers` cataloga proveedores y capacidades sin acoplar órdenes a Mercado Pago; - `payment_provider_connections` mantiene una conexión independiente por lavandería, proveedor y ambiente; - los estados contemplan preparación, conexión, expiración, error y revocación; - los tokens se almacenarán cifrados con `PAYMENT_CREDENTIALS_KEY_BASE64`, una clave de 32 bytes separada de MySQL y Git; - la desconexión elimina localmente tokens, cuenta externa, permisos concedidos y expiración; - preparar y desconectar quedan registrados en auditoría; - el propietario cuenta con la pantalla **Mi lavandería → Pagos digitales**; - la pantalla sólo informa si existen los requisitos y nunca revela secretos. La conexión OAuth real permanece deshabilitada de forma intencional. Se habilitará cuando `APP_URL` sea pública con HTTPS, existan Client ID/Client Secret válidos y la clave de cifrado esté resguardada. El `Access Token` global de sandbox continúa sirviendo únicamente para pruebas técnicas y no representa una cuenta conectada del propietario. ## 12. Fases propuestas 1. Crear conexiones de proveedor por tenant, eventos y estados; los intentos neutrales ya existen. 2. Implementar enlace de pago en sandbox. 3. Implementar consulta y conciliación idempotente. 4. Implementar receptor y validación de webhooks. 5. Añadir QR. 6. Añadir terminales Point por sucursal y caja. 7. Implementar cancelaciones y reembolsos. 8. Activar OAuth por lavandería cuando exista URL HTTPS; no usar el token global de sandbox para cobros reales. 9. Ejecutar pruebas productivas controladas. 10. Evaluar Split sólo si cambia el modelo comercial. ## 13. Decisiones pendientes - Política de reembolsos y quién puede autorizarlos. - Tiempo de expiración de enlaces y códigos QR. - Tratamiento de comisiones en reportes y tickets. - Canales disponibles según el plan contratado. - Uso de un túnel HTTPS durante el desarrollo. - Proceso de soporte cuando una lavandería revoque OAuth. - Requisitos fiscales de las comisiones y mensualidades. - Evaluación futura de BBVA u otros proveedores. ## 14. Referencias oficiales - OAuth: - Obtener Access Token: - Split de pagos 1:1: - Configuración de Point: - Notificaciones de Orders: