Saltar a contenido

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):

  1. When any response (trxpago or GET /api/trxes/{id}) carries qrdata and the QR is not on screen yet, render it, porting the encoder and renderer from the Caracol tree (QRENC.C/.H, MostrarQRScr in pos_scre.cpp). The gateway sends qrdata on 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)
  2. Make the GET /api/trxes/{id} polling interval configurable (today fixed at 10 s; target 1–2 s).
  3. When the cashier presses Esc while waiting (pos_ctoq.cpp:3697-3701, today it just returns SC_ERROR_CANCELO_USUARIO without telling the gateway), send trxanulacion for 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 accept PAGO_APROBADO as an approved payment (race rule, §4). The existing trxanulacion menu (_PAGOQR_MenuAnulacion) cancels a past payment, which for this method is a PAID charge and is denied (O2). (origin: agent, confirmed: 2026-11-16)
  4. When the trxpago never reached the gateway (connect or transmit failure), the attempt stays ISSUED and every query answers PAGO_ENVIADO without qrdata, so the POS waits with no QR (today the loop in localPAGOQR_Op_v2 only queries and never resends). While no QR has been shown yet, the POS resends the same trxpago (same id) 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 render qrdata, 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)
  5. Cap the POS's wait for the trxpago answer (today max(TIMEOUT_RX/3, 30), 80 s with TIMEOUT_RX 240) 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), and TIMEOUT_RX/3 is 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 the trxpago is 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 carries qrdata, the QR appears and the sale continues. The gateway normally answers trxpago in 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 in docs/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 same POST /cobro with the same referenciaExterna; municipal idempotency returns the charge if it was created, or creates it. The POS receives PAGO_ENVIADO until 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_INACTIVO or invalid amount, 401 invalid API key). The attempt ends at once and the POS's first query receives REFUND_DENEGADO with the municipal mensaje in mensajevarios (after any non-approved trxpago, 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 trxpago with totalcashback > 0 is rejected (same path as E2: REFUND_DENEGADO on 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 comercio code, 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; ends CLOSED_BY_ADMIN and 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)

  1. Admin lockout after 5 wrong passwords, for 15 minutes; wrong current passwords on re-authentication count toward the same lock.
  2. 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.
  3. 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).
  4. Attempt list paging ≤ 100; date filters use Buenos Aires days.
  5. Deactivating a merchant or branch only stops new trxids; in-flight attempts keep polling.
  6. Merchant create does not re-authenticate; edit, key rotation, activate/deactivate do.
  7. Every cockpit-created user is ADMIN (no partial operator role in v1).
  8. wire_log retention 90 days, hourly purge in batches of 1000.
  9. The cockpit shares the POS API port; in production the cockpit source allow-list is mandatory.
  10. Password change/reset/disable ends the user's other sessions; enabling a user needs no re-auth.
  11. Console static files under /admin are public; the admin API requires login.
  12. 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}/movimientos for 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 (idCobro or idTransaccion). 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 trxpago that 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.