Domain model — GatewayQR-MunicVAllende
Entities
| Entity | Meaning | Key fields |
|---|---|---|
| Merchant (Comercio) | Merchant adhered to the municipal program. One CUIT per merchant. | POS comercio code (unique), CUIT (unique), API key (encrypted at rest, never logged), environment (SANDBOX / PRODUCTION), active |
| Branch (Sucursal) | A merchant location; identified by the POS comercio + sucursal pair. |
merchant, branch number, active |
| Payment attempt (Intento de pago) | One QR charge attempt requested by a POS. Core aggregate of the gateway. | branch, POS number (pos, not registered), trxid (gateway id, unique), nropv and nroticketfiscal (reference only), amount, referenciaExterna; municipal data: idCobro, codigo, expira, idTransaccion, fechaPago, pagadoPorLegajo; local status |
| Alert (Alerta) | Something a human must look at: PAID_UNCONFIRMED, municipal 401 (MUNI_UNAUTHORIZED), AMOUNT_MISMATCH (paid amount differs, C1), MUNI_STUCK (12 consecutive municipal refusals; a final query still answering PENDIENTE does not reset the count), ENVIRONMENT_MISMATCH (merchant environment changed mid-flight, C6). At most one open alert per attempt and type. Shown in the cockpit alert panel (K4). |
attempt (trxid), type, raised at, resolved at, resolved by (admin user, V3), resolution note; resolving appends an attempt event ALERT_RESOLVED:<type> (source COCKPIT). (origin: agent, confirmed: 2026-11-16) |
| Admin audit (Auditoría) | Insert-only record of every cockpit write (V4). No secrets: a key rotation is recorded as apiKeyRotated=true. |
admin user, action, target, timestamp, details |
| Event (Evento) | Append-only record of each status change of an attempt. | attempt, from status, to status, source (POS / POLLER / COCKPIT), timestamp, municipal error code |
Relationships
- Merchant 1 — N Branch
- Branch 1 — N Payment attempt
- Payment attempt 1 — N Event
Model decisions
- D1 — The idempotency key is the gateway
trxid(replaces "N attempts per ticket", 2026-11-16). The POS requests a newtrxidfor every payment attempt (pos_ctoq.cpp:3636), soreferenciaExterna = {branch}-{pos}-{trxid}: retries oftrxpagowith the same id are idempotent, a new attempt gets a new charge, and the municipal idempotency never returns an expired charge.nroticketfiscalis NOT a key: it is a predicted number (pos_mppo.cpp:3599-3602) and repeats across CAE and CAEA invoicing (operator, 2026-11-16). The POS's uniquenroticketis not sent in the PAGOQR contract. (origin: agent, confirmed: 2026-11-16) - D2 — Local status is a superset of the municipal one:
CREATING → PENDING → PAID | EXPIRED | CANCELLED, plusUNCERTAINwhen the outcome is unknown (timeout on create or cancel). The gateway keeps querying until it is resolved and never reports "rejected" to the POS while uncertain. ADR-003 addsPAID_UNCONFIRMED(paid in the municipal API after the POS abandoned the attempt). (origin: agent, confirmed: 2026-11-16) Added during slice 1:ISSUED(atrxidwas handed out, notrxpagoyet) andREJECTED(municipal rejection on create, E2, or cashback, E3). POS mapping: ISSUED →PAGO_ENVIADO, REJECTED →REFUND_DENEGADO(PosEstadoMapper). The PAGOQR contract is unchanged. (origin: agent, confirmed: 2026-11-16) - D3 — The payer's employee number (
pagadoPorLegajo) IS stored on the payment attempt (human decision). It is personal data (Ley 25.326): persisted in the database only, never written to application logs. - D4 — Branches are configured, terminals are not (K2′). The gateway resolves the merchant
(CUIT, API key) from the POS
comercio+sucursal; atrxidfrom an unconfigured branch is rejected with "Sucursal no configurada". The POS number is stored on each attempt and used inreferenciaExterna(D1). (origin: agent, confirmed: 2026-11-16) - D5 — The environment is pinned on the attempt at claim (V3). Query and cancel refuse,
with no municipal call, when the merchant's current environment differs, and raise
ENVIRONMENT_MISMATCH(CONSTITUTION C6). Added in slice 2a from the improve review. (origin: agent, confirmed: 2026-11-17) - D6 — Amount mismatch is a final status, denied to the POS. A PAGADO whose amount differs
from the attempt amount (or cannot be read) ends
AMOUNT_MISMATCHwith an alert; the POS receivesREFUND_DENEGADOwith a "do not charge again" message. The money has moved, so the admin settles it from the alert. (human decision, 2026-11-17) - D7 — A held or stuck attempt is closed by an admin, never automatically. After
expira+ grace an admin may close it (current password + note) to the final statusCLOSED_BY_ADMIN; the POS receivesREFUND_DENEGADO"NO cobrar de nuevo, verificar con la Muni". While it stays held or stuck, its alert is raised once and is not raised again after a resolve. (human decision, 2026-11-17)