SPEC — GatewayQR-MunicVAllende
Go-live: not set (customer is in a hurry; no date committed yet)
1. Objective and value
Allow CYRE POS terminals at merchants adhered to the Villa Allende municipal program to accept Billetera Municipal as one more payment method, like a credit card:
- The POS shows a QR code, the municipal employee pays from the municipality's wallet app, and the POS receives the result.
- A payment can be cancelled from the POS. A sale is never cancelled.
- The gateway holds the merchant API key and does the polling against the municipal API. It records every operation so it can be reconciled, and it isolates the POS from changes in the municipal API (for example, real-time notifications in v2).
Why now: the municipality is replacing the paper voucher. Without POS integration, an adhered merchant would have to charge with a separate phone app and reconcile manually.
2. POS ↔ gateway contract (ADR-001)
The gateway exposes the existing PAGOQR contract already used by the CYRE POS
(pos_ctoq.cpp, struct PAGOQR) and implemented by GatewayPrismaQR:
| Operation | Gateway behavior |
|---|---|
POST /api/trxid {pos, sucursal, comercio} |
Allocates the local payment attempt id. |
POST /api/trxpago {id, totalitem, totalcashback, nropv, nroticketfiscal} |
Creates the municipal charge and returns immediately with estado=PAGO_ENVIADO and a new field qrdata (the municipal codigo). Idempotent per id (trxid): never a second charge for the same id (CONSTITUTION C4). nropv and nroticketfiscal are stored for reference only (DOMAIN-MODEL D1). |
GET /api/trxes/{id} |
Returns the current local status mapped to PAGOQR estado strings (PAGO_APROBADO when paid). |
POST /api/trxanulacion {id, trxidoriginal, nropv, nroticketfiscal} |
Cancels a PENDING municipal charge. Cancelling a PAID payment requires a municipal refund API that does not exist yet (RISKS R-02). |
Network: POS ↔ gateway traffic runs over CYRE's private VPN on MPLS lines; the POS API has no authentication by design, and the POS never holds or sends the municipal API key (CONSTITUTION C2). (human decision, 2026-11-16)
Required POS changes (minimal):
- When any response (
trxpagoorGET /api/trxes/{id}) carriesqrdataand the QR is not on screen yet, render it, porting the encoder and renderer from the Caracol tree (QRENC.C/.H,MostrarQRScrinpos_scre.cpp). The gateway sendsqrdataon the query too, only while the charge can still be paid, so the QR still reaches the POS after an E1 create timeout. (origin: agent, confirmed: 2026-11-16) - Make the
GET /api/trxes/{id}polling interval configurable (today fixed at 10 s; target 1–2 s). - When the cashier presses Esc while waiting (
pos_ctoq.cpp:3697-3701, today it just returnsSC_ERROR_CANCELO_USUARIOwithout telling the gateway), sendtrxanulacionfor the pending id so the municipal charge is cancelled immediately. If the cancel is not approved, run one final query on the pending id and acceptPAGO_APROBADOas an approved payment (race rule, §4). The existingtrxanulacionmenu (_PAGOQR_MenuAnulacion) cancels a past payment, which for this method is a PAID charge and is denied (O2). (origin: agent, confirmed: 2026-11-16) - When the
trxpagonever reached the gateway (connect or transmit failure), the attempt stays ISSUED and every query answersPAGO_ENVIADOwithoutqrdata, so the POS waits with no QR (today the loop inlocalPAGOQR_Op_v2only queries and never resends). While no QR has been shown yet, the POS resends the sametrxpago(sameid) from its query loop. The gateway treats a repeat of an id that is past ISSUED as a read (C4), so the resend is safe whether or not the first one arrived; the resend's answer is only used to renderqrdata, and the following query decides the outcome. (human decision, 2026-11-17) Resend after 2 queries with no QR on screen, at most 3 resends per payment. (origin: agent, confirmed: 2026-11-17) - Cap the POS's wait for the
trxpagoanswer (todaymax(TIMEOUT_RX/3, 30), 80 s withTIMEOUT_RX240) and send the first query right after it, without the poll pause of key 564. The cap is 10 s in the POS build (min(TIMEOUT_RX/3, 10), andTIMEOUT_RX/3is at least 70 at the 210 s floor of RUNBOOK section 6, so the 10 s always applies); it is not a profile key. The POS logs show the wait ends about 11 s after thetrxpagois sent (whole-second timer), and the first query follows at once. When only the answer is lost, that query reaches the gateway before its 20 s abandonment (ADR-003) cancels the charge; it carriesqrdata, the QR appears and the sale continues. The gateway normally answerstrxpagoin under 2 s (create timeout 1.5 s); a reused create plus one 5 s query takes about 6.5 s, and an answer the cap does cut is recovered by the query loop: the resend is a read (C4). The gateway is unchanged. Found in the POS E2E of 2026-11-18 (its first run, not kept indocs/evidence/): with the 80 s wait the first query comes after the gateway's 20 to 26 s cut, so a lost answer always ended in a denied sale. (human decision, 2026-11-18: cap the wait) The 10 s value and the immediate first query were the agent's proposal. (origin: agent, confirmed: 2026-11-18)
3. Failure behavior
- E1 — Timeout or connection loss while creating the charge. The attempt goes to
UNCERTAIN. The gateway retries the samePOST /cobrowith the samereferenciaExterna; municipal idempotency returns the charge if it was created, or creates it. The POS receivesPAGO_ENVIADOuntil it resolves. The gateway never opens a new attempt on its own. (origin: agent, confirmed: 2026-11-16) - E2 — Municipal rejection on create (400 such as
COMERCIO_INACTIVOor invalid amount, 401 invalid API key). The attempt ends at once and the POS's first query receivesREFUND_DENEGADOwith the municipalmensajeinmensajevarios(after any non-approvedtrxpago, the POS always enters its query loop,pos_ctoq.cpp:3676-3712). A 401 also raises a cockpit alert (broken configuration). (origin: agent, confirmed: 2026-11-16) - E3 — Cashback is not supported by the municipal API. A
trxpagowithtotalcashback > 0is rejected (same path as E2:REFUND_DENEGADOon the first query) with a clear message, and the POS disables cashback for this payment method. (origin: agent, confirmed: 2026-11-16) - E4 — Insufficient balance is invisible (RISKS R-04): the POS keeps showing "waiting" until the charge expires or the cashier cancels. The POS screen text reads "If the customer cannot pay, press Esc to cancel." (origin: agent, confirmed: 2026-11-16)
4. Status mapping to PAGOQR estado
Grounded in the CYRE POS query loop (pos_ctoq.cpp:3519-3559, :3684-3760): any trxpago
answer other than PAGO_APROBADO sends the POS into the query loop, and inside it only
REFUND_DENEGADO ends the wait as a denial. Every other string keeps the POS polling.
| Local status | estado returned by GET /api/trxes/{id} |
POS effect |
|---|---|---|
| CREATING / PENDING / UNCERTAIN | PAGO_ENVIADO |
Keeps waiting |
| PAID | PAGO_APROBADO, with idTransaccion as the authorization id |
Approved |
| PAID_UNCONFIRMED | PAGO_APROBADO |
Recovered when the cashier picks "Reintenta via Consulta" |
AMOUNT_MISMATCH (paid, but the credited amount differs from totalitem or is unreadable) |
REFUND_DENEGADO, mensajevarios "Monto acreditado distinto: NO cobrar de nuevo, verificar en cockpit" |
Denied; AMOUNT_MISMATCH alert in the cockpit (human decision, 2026-11-17) |
| CLOSED_BY_ADMIN (an attempt held or stuck past its expiry, closed by an admin) | REFUND_DENEGADO, mensajevarios "Cerrado por admin: NO cobrar de nuevo, verificar con la Muni" |
Denied (human decision, 2026-11-17) |
| EXPIRED / CANCELLED / E2 rejection | REFUND_DENEGADO, reason in mensajevarios ("QR expired", "Cancelled", municipal mensaje) |
Denied immediately |
POST /api/trxanulacion answers (the POS accepts only AUTORIZACION_DE_ANULACION_APROBADA or
REFUND_APROBADO as success, pos_ctoq.cpp:3551-3555):
| Case | estado returned |
|---|---|
| Pending charge cancelled at the municipal API | AUTORIZACION_DE_ANULACION_APROBADA |
| Charge already PAID (menu anulación, O2) | Denial, message "Pago ya acreditado: pedir devolución a la Muni" |
| Esc-vs-pay race: the municipal cancel returns 409 and the charge is PAID | Denial; the attempt stays PAID (not PAID_UNCONFIRMED) |
Race rule: POS change 3, when the cancel is not approved, runs one final GET /api/trxes/{id}
on the pending id; on PAGO_APROBADO it records the payment as approved and the sale closes
normally. (origin: agent, confirmed: 2026-11-16)
Inherited debt: REFUND_DENEGADO is used for a payment denial because it is the only denial
string the POS honors today. (origin: agent, confirmed: 2026-11-16)
5. Cockpit (v1)
Admin-only web console (login, CONSTITUTION C8):
- K1 — Merchant CRUD: POS
comerciocode, CUIT, API key (entered once, never shown again), environment. - K2′ — Branch CRUD per merchant (DOMAIN-MODEL D4). Terminals are not registered.
- K3 — Attempt list with filters (date, branch, POS, status) and a detail view with the event timeline.
- K4b — "Close held attempt": available only after
expira+ grace for an attempt that is held (merchant mismatch) or stuck (MUNI_STUCK); requires the admin's current password and a mandatory note; endsCLOSED_BY_ADMINand appends an audit and an attempt event. (human decision, 2026-11-17) - K4 — Alert panel: PAID_UNCONFIRMED and municipal 401; action "mark resolved with note", recorded as an event.
- K5 — "Reconcile day X" screen (O3, subject to the corpus).
- K6 — Read-only view of the timing configuration; edited in
config/application-prod.yml. - K7 — Admin user CRUD.
(origin: agent, confirmed: 2026-11-16)
5b. Operational defaults (agent-origin, confirmed by the operator 2026-11-17)
- Admin lockout after 5 wrong passwords, for 15 minutes; wrong current passwords on re-authentication count toward the same lock.
- MUNI_STUCK after 12 consecutive municipal refusals; a stuck attempt is queried every 300 s; unanswered calls after expiry count toward stuck; the gateway refuses to start when the stuck interval is not greater than charge TTL + final-query grace.
- CUIT is 11 digits with no check-digit validation; branch number 1–99999; API key 1–256 printable ASCII without spaces; passwords of 12+ characters (≤ 72 bytes).
- Attempt list paging ≤ 100; date filters use Buenos Aires days.
- Deactivating a merchant or branch only stops new
trxids; in-flight attempts keep polling. - Merchant create does not re-authenticate; edit, key rotation, activate/deactivate do.
- Every cockpit-created user is ADMIN (no partial operator role in v1).
wire_logretention 90 days, hourly purge in batches of 1000.- The cockpit shares the POS API port; in production the cockpit source allow-list is mandatory.
- Password change/reset/disable ends the user's other sessions; enabling a user needs no re-auth.
- Console static files under
/adminare public; the admin API requires login. - Held/stuck alerts are raised once per episode. (origin: agent, confirmed: 2026-11-17)
6. Out of scope (v1)
- O1 — Real-time notifications (SignalR / webhook): v2. v1 polls every 5 s (ADR-003). (origin: agent, confirmed: 2026-11-16)
- O2 — Cancelling a PAID payment: the municipal API states that a paid charge is reverted
"por devolución, fuera de este flujo" (§9,
COBRO_NO_ANULABLE), with no endpoint. Handled manually with the municipality until a refund API exists (RISKS R-02). (origin: agent, confirmed: 2026-11-16) - O3 — Automatic daily reconciliation with alerts: v2. v1 includes an on-demand cockpit
screen "Reconcile day X": it fetches
/comercio/{cuit}/movimientosfor that day and shows differences both ways (credited but not PAID locally; PAID locally with no movement). Condition: the sandbox corpus (RISKS R-01) must show a field that matches a movement to a charge (idCobrooridTransaccion). If none exists, the screen moves to v2. (origin: agent, confirmed: 2026-11-16) - O4 — Cashback (E3). (origin: agent, confirmed: 2026-11-16)
- O5 — Fixed QR per terminal (the "large merchant" model in the security PDF), until the municipality clarifies it (RISKS R-05). (origin: agent, confirmed: 2026-11-16)
- O6 — Two QR payment methods in parallel on the same POS (ADR-001). (origin: agent, confirmed: 2026-11-16)
7. Acceptance
The full criteria live in ACCEPTANCE.md; this index maps them to the sections above.
- AC-01 to AC-07 — payment flow (§2, §4)
- AC-08 to AC-11 — failure behavior (§3)
- AC-12 to AC-15 — timing (ADR-003)
- AC-16 to AC-18 — security and data (CONSTITUTION)
- AC-19 to AC-21 — cockpit (§5)
- AC-22 — dev bench (ADR-004)
- AC-23 — Esc-vs-pay race (§4)
- AC-24 to AC-29 — coverage of already-agreed scope (K5, C5, C7, C8, POS changes)
- AC-33 — POS resends a
trxpagothat never reached the gateway, and recovers a lost answer within the abandonment window (POS changes 4 and 5)
8. Source contract
- Municipal API:
Documntacion-API.html(API de Cobro v1, 2026-10-13). - Security model:
04-Arquitectura de Seguridad -para dpto, Sistemas-.pdf. - Known gaps and contradictions are tracked in
RISKS.md.