ADR-003 — Timing ownership and POS abandonment
- Status: accepted (2026-11-16)
Context
The municipal doc suggests a 90 s POS timeout while a charge expires after 180 s by default, and
it cancels only when the cashier cancels. A charge can therefore be paid after the POS gave up
(RISKS R-03). The CYRE POS gives up at 2/3 of TIMEOUT_RX and then offers
"Reintenta via Consulta?". The municipal API has no refund (RISKS R-02), so a paid charge the POS
did not register cannot be reversed automatically.
Alternatives
- The POS owns the deadline (doc's suggestion). Rejected: paid-after-abandon risk.
- The gateway owns the deadline; POS timeout longer than the charge; auto-cancel on abandonment. Chosen.
Decision
- The gateway owns the clock. It creates the charge with
expiraEnSegundos= 120 (configurable, max 600 per the API). It queries the municipal API every 5 s (configurable) while the attempt is pending. Atexpira+ 10 s grace it runs a final query and settles the status. If the final query still answers PENDIENTE, the gateway cancels the charge at the municipal API before reporting any denial: cancel OK → EXPIRED; 409 → query and follow PAID handling; timeout → UNCERTAIN (CONSTITUTION C5). (confirmed: 2026-11-16) - The POS timeout exceeds the charge lifetime. CYRE profile
TIMEOUT_RX ≥ 210 s, so the POS always receives the municipal outcome (including VENCIDO) instead of abandoning a payable charge. - Abandonment detection. The primary cancel path is the cashier's Esc, which sends
trxanulacion(SPEC §2, POS change 3, added 2026-11-16). The rule below is the safety net for a POS that cannot notify. If a pending attempt receives no POS query for 20 s (configurable), the gateway cancels the municipal charge. If the cancel returns 409, the gateway queries the charge; if it is PAID, the attempt is flagged PAID_UNCONFIRMED and raised as an alert in the cockpit. Recovery is the POS "Reintenta via Consulta" option on the same id, or manual handling.
Consequences
- With a 5 s poll, the POS may learn about a payment up to about 5 s after the payer confirmed.
TIMEOUT_RXmust be set on every CYRE POS that enables this payment method (rollout checklist).- PAID_UNCONFIRMED adds one status to the D2 state model (DOMAIN-MODEL.md).
Implementation Plan
- Configuration keys:
muni.charge-ttl-seconds(120),muni.poll-interval-seconds(5),muni.final-query-grace-seconds(10),pos.abandon-after-seconds(20). - A scheduled poller over pending attempts (virtual threads), restart-safe: on startup it resumes every non-final attempt from the database.
- Tests with a controllable clock: payment just before expiry, payment between abandonment and cancel (409 → PAID_UNCONFIRMED), gateway restart while pending.
Verification
- [ ] A charge paid at second 115 is reported to the POS as
PAGO_APROBADO. - [ ] A POS that stops querying for 20 s triggers a municipal cancel.
- [ ] A cancel answered with 409 on a paid charge ends in PAID_UNCONFIRMED and a cockpit alert.
- [ ] After a gateway restart, pending attempts keep being polled.