La suite Merchant, componente por componente

0Mapa y flujos

Todo punto de cobro termina en el mismo motor: una intención de pago con intentos por riel (tarjeta, pago móvil C2P y P2C, transferencia, QR, cripto, efectivo presencial, débito y crédito inmediato) y un veredicto. Después de la venta, el mismo motor cierra el lote, compensa, liquida y concilia. Cuatro flujos cubren casi todo lo que se presenta:

Flujo	Quién empieza	Por dónde pasa	Diagrama
Compra con tarjeta	Caja (Windows o Android)	API ECR → AuroraPOS → Merchant (JSON → ISO 8583) → Switch Aurora → autorizador	secuencia
Cobro empujado	Software del comercio con `X-API-Key`	Merchant · DispatchService → AuroraPOS por long-poll → Switch	secuencia
Checkout web o app	Backend del comercio	Sesión con token → widget o página de pago → Merchant autoriza por riel → webhook firmado	secuencia
Caja satélite	ERP o caja de terceros en Windows	FINORA Pago (API local, URI o CLI) → sesión de Checkout → veredicto o callback firmado	secuencia

Mapa interactivo de componentes · Presentación completa

1FINORA Merchant producción

Qué es: El motor y la consola del operador adquirente: comercios (principal, agencias, sucursales), terminales y puntos de cobro, catálogo de medios, orquestación de intenciones e intentos, lotes, clearing, liquidación, conciliación y estados de cuenta. Sobre él viven como módulos el Checkout API, el TMS con su marketplace, el adaptador AMP y la Torre.
Para quién: El operador de la plataforma (adquirente o banco patrocinante). El comercio no entra aquí: usa el portal.
Cómo se accede: Consola web Jmix en https://pos.finoracore.com. API REST /api/v1/** con clave de API por comercio (X-API-Key), token de dispositivo (terminales) o token de usuario OAuth2 (portal).
Cómo se conecta: Recibe de AuroraPOS por HTTPS (/api/v1/pos), de la Caja, FINORA Pago y el SDK por el Checkout API, del portal por /api/v1/portal/**. Habla ISO 8583 con el Switch Aurora (compra 0200, reverso 0420, cierre 0500) y con los bancos por sus APIs (pago móvil, transferencias, QR). Publica eventos a la Torre.
Estado real: Imagen pos:prod-20260913d en producción (changelogs 078 checkout, 079 medios por comercio, 080 AMP, 081 Torre); 606 pruebas en verde. Proyecto merchant/finora-pos (Jmix 2.8.2, Java 21, PostgreSQL).

Enlaces

Guía operativaencendido, guion de demo, cierre y ciclo Aprende con ejemplossiete lecciones de cinco minutos pos.finoracore.comconsola (producción)

2Portal del comercio producción

Qué es: La cara del comercio: panel con ventas de hoy y ayer, terminales en línea y última liquidación; ventas, lotes, liquidaciones, flota y consola de comandos, claves de API, licencias, usuarios, medios de pago habilitados, marketplace, Centro de desarrolladores y cabina de la Torre.
Para quién: Dueños y administradores del comercio. Roles portal-comercio (marketplace y consulta) y portal-comercio-admin (flota, comandos, claves, usuarios, medios).
Cómo se accede: https://portal.finoracore.com. Inicio de sesión OAuth2 con PKCE contra el authserver que el propio Merchant trae; el portal es un BFF Next.js que nunca expone la API del Merchant al navegador.
Cómo se conecta: Con el Merchant por /api/v1/portal/** usando el token del usuario; las descargas del marketplace se sirven en streaming desde el Merchant con enlace firmado HMAC de 5 minutos; la Torre llega por SSE (/api/torre/stream con proxy_buffering off).
Estado real: Contenedor finora-merchant-portal en CT132, commit 4a13240; usuario de demo comercio.demo. Proyecto merchant/finora-merchant-portal.

Enlaces

portal.finoracore.comproducción Centro de desarrolladoresguías, OpenAPI, consola de pruebas

3Marketplace producción

Qué es: El App Store de la suite: catálogo de aplicativos certificados con portadas, destacado y ficha; versiones con tipo de artefacto, plataforma, arquitectura y visibilidad; licencias con HMAC. Un comercio ve solo lo que tiene derecho a instalar: versión certificada y (pública, o regla de política, o licencia).
Para quién: Comercios que instalan sus cajas y terminales; el operador publica versiones desde la consola.
Cómo se accede: En el portal (/marketplace) y en la consola del Merchant. Publicado hoy: AuroraPOS 1.2.0, FINORA Caja 1.2.1 (Windows), FINORA Caja Android 1.1.0, FINORA Pago 1.0.1 (Windows), ECR DLL.
Cómo se conecta: Las descargas van por enlace firmado de 5 minutos servido por el Merchant (no pasan por Node). La auto-actualización de los aplicativos está planificada tras el keystore de liberación (GET /api/v1/device/apps/actualizacion).

Enlaces

Marketplace en el portaldescargas con enlace firmado Guía operativapublicación de versiones

4TMS · Flota producción · fase 1

Qué es: La gestión de terminales dentro del Merchant: latido cada 60 s con telemetría (batería, red, versión, lote, último cobro), comandos genéricos por long-poll con reclamación atómica, estado operativo que el servidor hace cumplir (un terminal SUSPENDIDO recibe DE39 = 58), parámetros con versión, consola del terminal y vista de Flota.
Para quién: El operador (consola) y el administrador del comercio (portal, /flota).
Comandos: COBRAR y REEMBOLSAR (reutilizan el despacho del cobro empujado), CERRAR_LOTE, ESTADO, MENSAJE, PARAMETROS, SUSPENDER, ACTIVAR; ABRIR_APP solo abre la propia app (control total del equipo en fase 2). Para terminales AMP: ESTADO, CERRAR_LOTE, ACTIVAR, DESACTIVAR.
Cómo se conecta: AuroraPOS 1.2.0 trae el agente de dispositivo (comandos, latido, bloqueo operativo). El portal envía comandos por su BFF; la Torre abre alertas cuando falta el latido.

Enlaces

Flota en el portalterminales, comandos, badge AMP Terminal AuroraPOSagente TMS y API ECR

5Checkout: API, SDK y página de pago producción

Qué es: La forma de cobrar desde la web o la app del comercio, y el motor que usan por dentro la Caja y FINORA Pago. Una sesión de cobro la crea el backend del comercio con su clave de API; al navegador llega un token corto que solo sirve para esa sesión. El SDK @finora/checkout (Web Component <finora-checkout> y API imperativa) y la página alojada pago.finoracore.com/s/{id}?t=… muestran los medios habilitados, guían la captura y esperan el veredicto. Al terminar, el Merchant envía un webhook firmado.
Para quién: Desarrolladores del comercio: integración en web, app o solo por API.
Cómo se accede: POST /api/v1/checkout/sesiones con X-API-Key → {sesionId, token, urlPago, medios[]}. Cliente: GET /sesiones/{id}, POST /medio, GET /estado (cada 2 s), POST /cancelar con Authorization: Bearer token. Modo inmersivo con ?modo=inmersivo.
Cómo se conecta: Reutiliza la orquestación del Merchant (intención + intento por riel) y, para tarjeta, el despacho al terminal. Webhook X-Finora-Signature: t=,v1=,v0= con HMAC-SHA256, tolerancia 5 min, reintentos con backoff, tabla dat_webhook_delivery. El PAN nunca pasa por el SDK: tarjeta = terminal físico.
Estado real: Changelog 078 en producción; SDK y página desplegados en pago.finoracore.com. Proyectos merchant/finora-pos y merchant/finora-checkout-sdk.

Enlaces

Guía «Checkout» y consola de pruebassandbox contra el banco simulado Diagrama de secuenciasesión, pago, veredicto

6FINORA Pago para Windows 1.0.1

Qué es: El cobrador instalable para cajas satélite: un ERP, SAP, Odoo, una caja en VB6 o una web le piden «cobra 227,00 por el pedido 8841» y reciben «APROBADA, referencia …». Con ventana para el cajero y el cliente (modo formal o inmersivo) o sin ella. No guarda tarjetas, no habla ISO 8583 y no decide rieles: crea una sesión de Checkout con la clave del comercio y devuelve el veredicto.
Para quién: Sistemas de caja de terceros en el mismo equipo Windows del mostrador.
Cómo se accede: Tres puertas: API local http://127.0.0.1:9810 con X-Pago-Token (POST /v1/cobros con esperar, mostrar, callbackUrl), URI finora-pago://cobrar?… y CLI finora-pago.exe cobrar --monto 227.00 --referencia 8841 --json con códigos de salida 0 aprobada · 1 rechazada · 2 en duda · 3 error. Puerto 9810 porque el 9800 lo usa el agente de hardware.
Cómo se conecta: Con el Checkout API por la clave del comercio cifrada con DPAPI; callback a la caja firmado sha256=HMAC(tokenLocal, cuerpo); sandbox por petición contra el banco simulado.
Instalación: Instalador Windows publicado en el marketplace. Configuración: clave del comercio, modo de la ventana, monitor del cliente, sonidos, color del comercio.

Enlaces

Guía de integraciónAPI local, URI, CLI, ejemplos en C#, Java, Node, Python, PowerShell y VB6 Diagrama de secuenciaorden, cobro, veredicto

7Caja Windows FINORA Caja 1.2.1

Qué es: La caja de mostrador para Windows (Electron): flujo guiado de cobro (cédula → medios → terminal → recibo), modo kiosco forzado con reintentos, autoservicio, inventario local con carga masiva, reinicio de base y origen externo de inventario. Semi-integrada por diseño: nunca ve una tarjeta.
Para quién: Cajeros y puntos de autoservicio del comercio.
Cómo se instala: Desde el marketplace; requiere la clave de API del comercio. Diagnóstico de la ventana en Configuración → Ventana; F11 alterna pantalla completa.
Cómo se conecta: Ordena el cobro al terminal por la API ECR (:8080) o a través del agente finora-merchant-agent (:9800) para hardware por USB; abre intenciones en el Merchant; la versión 1.3.0 pasará a montar @finora/checkout.

Enlaces

FINORA Cajaflujo guiado, terminal semi-integrado, modo desatendido Compra con tarjetadiagrama de secuencia

8Caja Android FINORA Caja 1.1.0

Qué es: La caja para tablet Android (com.dcgeeks.finora.caja): modo atendido o autoservicio, inventario local, kiosco, lector de códigos embebido. La tarjeta se cobra en el mismo equipo (Intent a AuroraPOS instalado en la tablet), en la nube (cobro empujado a otro terminal) o con lector.
Para quién: Comercios que prefieren una tablet en el mostrador o en el kiosco.
Cómo se instala: APK desde el marketplace, con la misma firma que AuroraPOS (requisito del permiso de firma para COBRAR). Requiere API 24 o superior.
Cómo se conecta: Con AuroraPOS por Intent en el mismo equipo; con el Merchant por la API de intenciones; comparte el módulo :sdkpos con el terminal.

Enlaces

Descargar del marketplaceFINORA Caja Android 1.1.0 FINORA Cajaguía

9AuroraPOS 1.2.0

Qué es: La aplicación del terminal de pago Android: lee el chip, captura el PIN en el pinpad, expone la API ECR (:8080) para la caja, recibe cobros empujados y comandos del TMS, late cada 60 s y envía la transacción al Merchant con su deviceToken.
Para quién: El terminal físico (Wiseasy T2, RX y P5L dados de alta para certificación).
Cómo se instala: APK desde el marketplace; alta del dispositivo en el Merchant (DatPosDevice) para obtener el token.
Cómo se conecta: HTTPS /api/v1/pos/transacciones y /reversos; long-poll de despachos y comandos; parámetros con versión (/pos/parametros incluye medios[]). Ante timeout genera un 0420 automático para que la venta no entre al lote.
Estado real: Lector EMV simulado: falta el .aar del fabricante para EMV real. Capa Bluetooth implementada.

Enlaces

Terminal AuroraPOSEMV, API ECR, ISO 8583 Cobro empujadodiagrama de secuencia

10Switch Aurora producción

Qué es: El switch transaccional ISO 8583 (Netty, motor de pasos @AuroraStep): autoriza, reversa y cierra lotes con criptografía EMV; enruta on-us / off-us por BIN a los autorizadores (core, banco simulado, redes).
Para quién: La red de pagos; el Merchant es su cliente ISO.
Cómo se accede: TCP ISO 8583 (:9503 en producción) y https://switch.finoracore.com/actuator/health.
Cómo se conecta: Recibe 0200 / 0420 / 0500 del Merchant, consulta al autorizador y responde 0210 / 0430 / 0510. En modo core convierte la moneda numérica a alfa-3 antes de autorizar contra el core.

Enlaces

Switch Aurorapipeline de pasos, enrutamiento por BIN, modo core Simulador ISO 8583certificación

11Bancos y banco simulado demo y certificación

Qué es: Los autorizadores y las APIs bancarias con las que habla la suite: host ISO 8583 para tarjeta y APIs de pago móvil (C2P, P2C), transferencias, QR y cripto. El banco simulado imita al banco desde afuera con reglas públicas por céntimos y por PAN (BIN 400000) para demostrar y certificar sin dinero real.
Para quién: Certificación, sandbox de desarrolladores y demostraciones.
Cómo se conecta: El Switch lo alcanza por ISO (:9600); el Merchant, por HTTP a través del nodo BANCO_SIM. El sandbox del Checkout apunta aquí.

Enlaces

Banco simuladoreglas por céntimos y por PAN Tienda de demostracióncompra real por el switch

12Terminal AMP (terminal externo) pendiente del terminal real

Qué es: El adaptador del Merchant para datáfonos AMP 6500/6700/8000/8200 por AMP Smart Connect. El terminal lógico gana terminalKind = AMP; el despacho de un cobro lo toma el adaptador en vez de AuroraPOS, manda purchase o refund y reporta con los mismos eventos, así checkout, TMS y webhooks no saben quién cobró. Bitácora propia (DatAmpTransaction) para conciliar.
Para quién: Comercios que ya tienen equipos AMP y quieren usar Checkout, Caja y TMS sin cambiar de terminal.
Cómo se configura: En la ficha del terminal: serial, código de autorización (solo escritura, cifrado con AES-256-GCM), modo de comunicación (relay en la nube, LAN :55555 o terminal virtual), clave del comercio. Botones «Probar conexión», «Cerrar lote» y «Destrabar cola».
Trampas conocidas: Código 1001 = ocupado, nunca cancelado; la cola FIFO del relay no se vacía por software: un timeout queda EN_DUDA y no se reintenta; solo tarjeta presente (sin captura manual).

Enlaces

Guía operativasección de terminales externos Flotabadge AMP y estado cada 60 s

13FINORA Torre producción · fase 1

Qué es: El centro de monitoreo en tiempo real: los hechos del sistema (ventas, latidos, lotes, comandos, sesiones) se publican como eventos, alimentan KPIs en vivo (1 min, 15 min, hoy) por comercio, sucursal y terminal, una bitácora append-only y un evaluador de reglas que abre alertas. La Torre observa: un fallo suyo se registra y no toca una venta.
Para quién: Supervisores del comercio (cabina en el portal) y pantallas de sucursal (modo TV).
Cómo se accede: Portal: /monitoreo (corporativa), /monitoreo/sucursal/…, /monitoreo/terminal/…, /monitoreo/alertas. TV: un administrador vincula la pantalla y obtiene un código de 6 dígitos que dura 10 minutos y se usa una vez; la TV abre /tv/{código} y queda acotada a su sucursal.
Cómo se conecta: API /api/v1/portal/torre/** (/resumen, /sucursales/{code}, /terminales/{tid}, alertas, reglas, /eventos) y SSE GET /stream con Last-Event-ID; usuario con ?t=, TV con ?tv=.
Reglas por comercio: Terminal sin latido > 3 min · caja sin ventas > 20 min · rechazos > 15 % · EN_DUDA ≥ 3 · batería < 15 % · lote abierto tras la hora de cierre. Semáforo VERDE · AMARILLO · ROJO · GRIS.
Estado real: Changelog 081 en producción; fase 1 en memoria (anillo de 5.000 eventos por comercio); E2 pasa a Kafka sin tocar la cabina. La cabina del portal se alinea al contrato del backend.

Enlaces

Cabina en el portalrequiere sesión Flujo de datosfuentes → bus → agregados y alertas → SSE → cabina y TV

14Centro de desarrolladores producción

Qué es: La sección /desarrolladores del portal: once guías con código real (empezar, checkout, FINORA Pago, cobro empujado, TMS, inventario externo, marketplace y licencias, webhooks, sandbox, errores, autenticación) con pestañas curl, Node, Java, C#, Python, PHP, PowerShell y VB6; referencia OpenAPI 3.1 con 36 rutas y 31 esquemas y «Probar con mi clave»; consola de pruebas que crea sesiones sandbox y muestra los webhooks recibidos con su firma; página de webhooks (secreto con regeneración única e historial).
Para quién: Desarrolladores del comercio o de su proveedor de software.
Detalle que importa: La clave de API no se puede recuperar del Merchant (solo se guarda el hash): el portal la sella en la sesión del desarrollador al crearla y el BFF la usa por él; solo sale al navegador en el curl que el desarrollador pide.

Enlaces

portal.finoracore.com/desarrolladoresguías, OpenAPI, consola, webhooks Guía pública de FINORA Pagosin sesión

15Diagramas

Interactivos (tema claro y oscuro, vistas guiadas, exportación) y validados con el perfil showcase de archify. Los cuatro últimos vienen de la guía de arquitectura a escala.