Saltar a contenido

CONSTITUTION — GatewayPrismaQR

Invariants no ADR, SPEC or implementation may violate. A breach is a BLOCKER finding, never a trade-off.

Money

  • INV-01 — If the gateway told the POS a payment did not go through (denied, cancelled or timed out), or the POS cancelled it, the customer must not end up charged: the gateway compensates it automatically (intention cancel or forced annulment). (human, 2026-10-02)
  • What counts is the last answer the POS heard (amended by the human, 2026-10-04, after the real Almacor POS E2E): a POS can hear "denied" on trxpago and then "approved" on its consulta. If the gateway ever told the POS a payment was approved (on trxpago or on the consulta), it is a sale and is never compensated as a no-sale; INV-01 applies when the last answer the POS heard was no sale. The gateway records durably that it told the POS "approved" (pos_told_approved_at), written as soon as the approved answer has been written out completely; a failure to record it raises an operator alert. Before any approved answer leaves, the gateway durably records its intent to answer approved (pos_approval_intent_at); if it cannot record it, it does not answer approved but "not settled yet" (INTENCION_DE_PAGO_RECIBIDA_APROBADA), so the POS asks again. Either record set means the POS may have heard "approved": code never annuls that payment as a no-sale, a person decides; both records still empty after the POS polling window means the POS never heard it. (amended by the human, 2026-10-28)
  • INV-02 — The compensation intent is persisted before the "no sale" answer reaches the POS; compensation survives restarts and never depends on in-memory state. (human, 2026-10-02)
  • Exception — storage unreachable at the deadline (amended by the human, 2026-10-04): when the database cannot be reached from the node answering the POS for the whole time left before the caller's read timeout, that node may answer "no sale" without a persisted intent. In return, two guarantees replace the persisted intent: (1) once a payment's wait deadline has passed, a wallet approval never approves it — it is recorded and compensated, because the POS was already answered; (2) an approval committed before the deadline by another node while the answering node could not read it is found by the S4 reconciliation, which compensates it only when neither record of an approved answer is set (INV-01), and every such answer raises an operator alert naming the payment.
  • INV-03 — A late Prisma notification is always accepted and applied; it is never rejected or dropped. (human, 2026-10-02)
  • INV-04 — importe + importe_recdesc == importe_final to the cent in every answer to the POS. (origin: agent, confirmed: 2026-10-02)
  • INV-05 — Terminal trace_number and ticket_number are unique and gap-free per terminal, also under concurrency and with several nodes. (origin: agent, confirmed: 2026-10-02)
  • INV-06 — The POS never records a QR sale at an amount different from what the wallet charged; if it cannot impute the adjustment it fails explicitly and the payment is reversed (system-level; the code lives in the POS repositories). (origin: agent, confirmed: 2026-10-02)

Security

  • INV-07 — Secrets (Prisma apikeys, the apikey we issue, database credentials) and full benefit card numbers are never logged or committed. (CWE-532, CWE-798) (origin: agent, confirmed: 2026-10-02)
  • INV-08 — Prisma callbacks fail closed: missing or wrong apikey is rejected, compared in constant time. (CWE-287, CWE-208) (origin: agent, confirmed: 2026-10-02)
  • INV-09 — No JPA entity is ever serialized on any endpoint; only explicit response DTOs. (CWE-200) (origin: agent, confirmed: 2026-10-02)
  • INV-10 — Outbound TLS is always validated; no trust-all certificate handling. (CWE-295) (origin: agent, confirmed: 2026-10-02)
  • INV-11 — The POS API is bound only to the VPN-side address; it is never reachable from the internet. (CWE-306) (origin: agent, confirmed: 2026-10-02)