ADR-001 — Reuse the PAGOQR POS contract and the GatewayPrismaQR template
- Status: accepted (2026-11-16)
Context
The municipal API requires the POS to display a dynamic QR (codigo) before the payment
outcome is known. The CYRE POS already has a single REST-like client, PAGOQR
(C:/Work/PCPOS/20260728F_CYRE/srcs/pos_ctoq.cpp:3217-3790), that talks to the QR gateways via
/api/trxid, /api/trxpago, /api/trxanulacion and /api/trxes/{id}. Today it shows no QR, and
trxpago blocks for 30 s or more, then polls every 10 s. GatewayPrismaQR
(C:/Work/AI/GatewayPrismaQR) implements the same contract on the current stack, with a cockpit,
an external config file and a provider emulator. The customer is in a hurry.
Alternatives
- A — Same contract plus a
qrdatafield;trxpagoreturns immediately; two small POS changes (render the QR, configurable poll interval). Chosen. - B — New endpoints and a new POS flow. Cleaner, but more C++ work and more time.
- Base on legacy GatewayQR (Spring Boot 1.5 / Java 8 / AngularJS). Rejected: obsolete stack.
Decision
Option A. The new gateway is derived from GatewayPrismaQR. It keeps the hexagonal layout, the POS adapter, persistence of payments, reversals and the wire log, the admin cockpit with auth, and the external configuration and deployment pattern. The Prisma-specific parts (BINs, complete intention, installment plans, wallet charge, callbacks) are replaced by a municipal wallet outbound adapter and an emulator of the municipal API.
Consequences
- The POS keeps one payment client. A second QR method running in parallel on the same POS would
need new profile ids and a second
iAutMode(single instance today). - The POS API has no authentication (inherited); the gateway must stay network-restricted.
- Cancelling a PAID payment stays blocked until the Muni provides a refund API (RISKS R-02).
Implementation Plan
- Copy the GatewayPrismaQR structure:
gatewaymodule plus an emulator module for the municipal API. - New
adapter.out.municlient for create / query / cancel, using theX-Api-Keyheader. trxpagoreturnsPAGO_ENVIADOwithqrdata; a server-side poller drives the attempt status.- POS: port
QRENC.C/.HandMostrarQRScrfromC:/Work/PCPOS/20260914_CARACOL; add a profile key for the poll interval; on Esc during the wait, sendtrxanulacionfor the pending id.
Verification
- [ ] The CYRE POS completes a payment against the gateway with only the three documented
changes (SPEC §2; the third, Esc →
trxanulacion, was added on 2026-11-16). - [ ] The
trxpagoresponse containsqrdataand returns in under 2 s. - [ ] Existing GatewayPrismaQR flows are not affected (separate project, copied code only).