Saltar a contenido

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 qrdata field; trxpago returns 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: gateway module plus an emulator module for the municipal API.
  • New adapter.out.muni client for create / query / cancel, using the X-Api-Key header.
  • trxpago returns PAGO_ENVIADO with qrdata; a server-side poller drives the attempt status.
  • POS: port QRENC.C/.H and MostrarQRScr from C:/Work/PCPOS/20260914_CARACOL; add a profile key for the poll interval; on Esc during the wait, send trxanulacion for 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 trxpago response contains qrdata and returns in under 2 s.
  • [ ] Existing GatewayPrismaQR flows are not affected (separate project, copied code only).