Saltar a contenido

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

  1. 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. At expira + 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)
  2. 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.
  3. 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_RX must 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.