Saltar a contenido

SPEC — GatewayPrismaQR

Go-live: not set. The 2026-10-16 pilot date was dropped (human, 2026-10-02: "olvidar fecha 16/10, hacemos el sistema full desde ahora"). Prisma homologation timing is outside our control (see RISKS.md R-01).

1. Objective and value

Let the supermarket POS of merchants that already work with Prisma charge with interoperable QR through Prisma's Gateway QR, acting as Sistema Propio / Integrador Grande Cuenta per Integradores Grandes Cuentas QR v0.27.

2. First deployment

Item Value Source
First merchants Almacor and Becerra (existing Prisma clients) human, 2026-10-01
POS software Tipre DOS POS (same family as the GatewayQR client pos_mppo.cpp) memory of prior POS work; to be confirmed with the POS contract golden
Volume per merchant 5,000 to 10,000 QR payments per day human, 2026-10-01
Derived peak ~1,000 payments/hour in the busiest hour (assumes 10 % of the day in one hour) ≈ 0.3 payments/s; design target 5 payments/s for headroom derived, see below
BeneficiosCenter Out of scope. The gateway does not call BeneficiosCenter. human, 2026-10-01

Derived peak (origin: agent, confirmed: 2026-10-02)

3. Scope (full system)

The MVP cut of 2026-10-01 is superseded: the human asked on 2026-10-02 for the full system from the start, with modes A and B and surcharges/discounts active.

  1. POS API v1, compatible with the GatewayQR contract: POST /api/trxid, POST /api/trxpago, POST /api/trxanulacion, GET /api/trxes/{id}.
  2. Prisma payment flow: create intention, BINs callback, complete intention within 27 s.
  3. Installment plans per payment method; the 1-installment plan and method 112 (Transferencias 3.0) always present. The gateway holds the plans per merchant and branch (Mode B, the only operating mode: human decision 2026-10-28, which removed Mode A, the POS-supplied promotions; see ADR-003): method, bank, BIN range, installments, signed %, validity, weekdays, minimum amount, configured through the console. A promos list or a base_amount that a POS may still send in trxpago is ignored. See docs/PLANES-CUOTAS.md and docs/emulador-qr.html. Surcharges and discounts are in scope from the start (human, 2026-10-02): the resulting importe_recdesc is signed and the POS imputes it post-payment.
  4. Payment notification, status query and a reconciliation job.
  5. Forced annulment, forced refund and intention cancellation (DELETE /intentions/{id}).
  6. Cashback (Visa Débito only, per v27 p.97).
  7. Prisma Gateway QR emulator for end-to-end tests.
  8. React admin console (merchants, branches, checkouts, terminals, establishments, installment plans, payment search).
  9. Active multi-node deployment (human, 2026-10-02, Q13): two or more gateway nodes against the same database; no in-memory state as source of truth; leases for jobs.
  10. POS-side work (outside this repository, required by item 3): port the QR post-payment imputation from DINO to Almacor/Becerra, add surcharge support (positive rows, fiscal command, percepciones), and turn the silent rejection into an explicit failure. The POS no longer needs to serialize promotions into trxpago. See docs/PLANES-CUOTAS.md §10.
  11. Cuotas MiPyME (plans 13 = 3 installments, 16 = 6 installments; human, 2026-10-02, Q13), as a plan code in the installment-plan model.

3.0 Integration behind RouterQR (facts, 2026-10-02)

The POS does not call the gateways directly: it calls RouterQR (C:\Work\AI\RouterQR, tipre/RouterQR main, JHipster 4 / Boot 1.5, stateful, MSSQL). Source: real POS E2E log DINI\E2E_QR\paranoia\evidence\E2E_V1_log.txt and RouterQR code.

Fact Consequence for GatewayPrismaQR
RouterQR has two hardcoded slots, MERCADOPAGO and DINI (property server.routerqr.prisma.url, today pointing to GatewayQR). trxid fans out to both; the gateway that knows the merchant answers, the other must fail cleanly. GatewayPrismaQR plugs into a slot. Topology (one RouterQR per merchant or shared) decides whether that is a config change or a RouterQR code change (Q6).
Router → gateway trxpago: id = gateway trx id, adds tipoautorizador:"TECSO" and importe = totalitem; passes totalcashback, nropv, nroticketfiscal, and any base_amount/promos the POS sent. Accept TECSO (ignore it); amount comes in importe; ignore base_amount and promos.
Router approves only if estado == "AUTORIZACION_DE_PAGO_APROBADA" and importe, autorizadortrxid, autorizadorintencionid are numeric (getLong). The POS also decides only by estado. Keep GatewayQR estado names exactly; expose numeric ids (Prisma intention_id ≤ 12 digits and payment id ≤ 7 digits are numeric).
Router → gateway trxanulacion: id and trxidoriginal both = the gateway trx id. RouterQR's own sweeper sends trxanulacion for any payment left unanswered, denied or lost to the other gateway, every 5 s until 2xx. trxanulacion must be idempotent and answer 2xx (AUTORIZACION_DE_ANULACION_APROBADA) also for payments never approved or already compensated; one reversal per payment even if both RouterQR and our compensation job ask.
Timeouts: POS waits 10 s for trxid/consulta and 80 s for the first trxpago (profile 496 = 240 s / 3), then polls GET /api/trxes/{id} every 10 s up to 160 s. RouterQR dev: timeout-pago 60 s (read 59 s), trxid 5 s; prod config is external and not verified. The gateway's own payment wait must end before RouterQR's read timeout (≈ 50 s with dev values); only a consulta answered REFUND_DENEGADO (or an approved/annulled estado) stops the POS polling; AUTORIZACION_DE_PAGO_DENEGADA does not (Almacor pos_ctoq.cpp 3681-3733, real E2E 2026-10-04), so the consulta of a no-sale payment answers REFUND_DENEGADO (amended 2026-10-04, human-approved). The direct-VPN Almacor POS reads trxpago for max(profile 496 / 3, 30) s, 50 s with its profiles: configure the wait for that caller.
GET /api/trxes/{id} must return the same shape as trxpago with the current estado and importe (used by the POS manual annulment). Same response builder for pay and status.

Topology (human, 2026-10-02, Q6). There is one RouterQR per merchant chain: for example a single RouterQR for all Almacor branches, even though the branches belong to different partners (socios). Plugging GatewayPrismaQR in is a RouterQR configuration change (server.routerqr.prisma.url), with no RouterQR or POS code change.

Deployment (human, 2026-10-02, Q8). GatewayPrismaQR runs as one central multi-merchant instance on the same server as GatewayQR. Almacor has no QR today at all (neither GatewayQR nor GatewayMP), so nothing has to coexist with it on their router slots. The Prisma callbacks (4 public endpoints) are exposed once, from that server.

POS connection (human, 2026-10-02, Q9/Q10). Almacor has no RouterQR: the POS calls GatewayPrismaQR directly, through a VPN between the branches and the central server (Q10). The VPN is a risk to verify (RISKS R-14). Facts from the POS source (pos_prof.h:576-583, pos_ctoq.cpp): the QR transport is plain TCP to PAGOQR_SERVER_IP:PAGOQR_SERVER_PORT (profiles 494/495), without TLS and without any auth header. Corrected 2026-10-02 (SD-002, human-approved) from the real E2E log and pos_ctoq.cpp:3312-3325: the POS sends HTTP/1.1 with a Host header, two spaces after the method and bare LF line ends; it cannot parse a chunked body and reads until its socket times out unless the server closes, so every /api answer carries Content-Length and Connection: close, errors included in the {status, message} shape. The POS reads installments from paymentinstallments (sent together with cuotas) and copies mensajevarios into an 80-byte buffer, so it is cut to at most 79 UTF-8 bytes. Consequences:

  1. GatewayPrismaQR must accept both request shapes: POS-native (trxpago with totalitem, no tipoautorizador; trxanulacion with the QR trx id in id and trxidoriginal possibly 0) and RouterQR-forwarded (importe, tipoautorizador, id = trxidoriginal), so a RouterQR can be inserted later without changes.
  2. It must return the fields RouterQR adds today (id = our trx id, mediodepago), since nothing else adds them.
  3. The POS API listens only on the VPN side; the Prisma callbacks are the only public HTTPS surface. Two separate listeners, so trxanulacion is never reachable from the internet. (origin: agent, confirmed: 2026-10-02)

3.1 Automatic compensation (asynchronous cancellation/refund)

Status: accepted (human, 2026-10-02, Q4). (origin: agent, confirmed: 2026-10-02)

POS timeout policy (human, 2026-10-02). When the POS wait expires without a final result, the payment is treated as cancelled: the POS receives a denied answer and the gateway compensates automatically if the wallet approves later (GatewayMP style). The POS never receives an "unknown" (SINRESPUESTA) answer for a payment.

Problem. The POS waits a bounded time. The wallet can still charge the customer after the POS gave up, after the POS cancelled, or after the gateway told the POS "denied". Neither reference gateway handles all of this:

Gateway What it does Gap
GatewayMP Sets accion=CANCELAR before the outbound call; on timeout re-checks the provider three times (a last-second payment is returned as approved); a @Scheduled sweeper deletes the pending order or refunds the payment; startup reload. Queue is an in-memory map (single node), retries forever, no terminal state or alert.
GatewayQR Returns SINRESPUESTA to the POS; the POS may later send trxanulacion, which becomes motivo=ANNULMENT. No background job; a late approval webhook after SINRESPUESTA is rejected with 504, so the customer can stay charged with no sale.

Invariant (CONSTITUTION.md INV-01). If the gateway told the POS the payment did not go through, or the POS cancelled it, the customer must not end up charged. Every such payment is compensated automatically. (origin: agent, confirmed: 2026-10-02)

Design. 1. A compensation intent is persisted in the database before any answer that implies "no sale" reaches the POS (the GatewayMP safety-flag idea, but durable). 2. A compensation job takes pending intents with a lease, so it is safe with more than one node and survives restarts. 3. Action by state: not paid yet → DELETE /intentions/{id}; paid → forced annulment (preferred: it also returns the cashback, v27 v0.14); forced refund only when annulment is no longer possible (refund does not return cashback). 4. Before re-sending a forced operation, query GET /annulments or GET /refunds first: Prisma documents no idempotency. 5. Bounded retries with backoff, then a terminal COMPENSATION_FAILED state with an alert for manual handling. Never retry forever. 6. Late notifications are always accepted and applied, never rejected; if the payment is marked for compensation, the approval triggers it instead of reaching the POS. 7. Every step is audited (wire log + reversal entity) and visible in the console.

3.2 Quality bar (human, 2026-10-02, Q14)

Dimension Threshold
Line coverage ≥ 90 % domain (states, plans, amounts, compensation); ≥ 80 % elsewhere
Mutation score (PIT) ≥ 80 % domain
Architecture ArchUnit green: the domain does not depend on Spring, JPA or Jackson
Review findings Zero open BLOCKER, CRITICAL or HIGH to merge
Invariants Every CONSTITUTION invariant has at least one test that names it
End to end One scenario per flow (payment, timeout, cancel, annulment, refund, compensation, plans with surcharge and discount) against the Prisma emulator
Performance Complete intention sent in < 3 s p99 against the emulator

Integration tests run against a separate database GatewayPrismaQR_IT (local SQL Server and CI), never against GatewayPrismaQR; the test setup refuses to clean any database whose name does not end in _IT (human, 2026-10-02, SCR-001). No Docker on the development machine. Declared in uscha.config.json.

4. Out of scope

  • BeneficiosCenter integration (human, 2026-10-01).
  • USD intentions and benefit cards (Clarín 365, etc.): out of scope (human, 2026-10-02, Q13).
  • Partial refunds and annulment of a refund (Prisma excludes them, v27 p.5).
  • QR registration by API (Prisma only offers the Excel mass upload).

5. Acceptance

Mirror of ACCEPTANCE.md (source of truth). AC-01..AC-32 confirmed by the human on 2026-10-02. Each criterion closes only with a green test that carries its ID.

  • [x] AC-01 — When the POS sends POST /api/trxid with a known enabled merchant, branch and checkout, then the gateway answers 201 with a numeric id within 2 s; with an unknown or disabled one it answers a non-2xx error.
  • [x] AC-02 — When trxpago arrives in POS-native shape (totalitem) or RouterQR shape (importe, tipoautorizador), then both are processed identically.
  • [x] AC-03 — When a payment is approved, then the response carries estado = AUTORIZACION_DE_PAGO_APROBADA, numeric importe, autorizadortrxid, autorizadorintencionid, plus importe_final, importe_recdesc, cuotas, payment_method_id, payment_method_type, mediodepago, and importe + importe_recdesc == importe_final to the cent.
  • [x] AC-04 — When the POS retries trxpago with the same id, then the intention is never sent twice: the gateway resumes the wait or returns the stored result.
  • [x] AC-05 — GET /api/trxes/{id} returns the same shape as trxpago with the current estado and importe; for a payment the gateway has irreversibly decided as no sale (rejected, cancelled, superseded, expired, intention/complete failed, compensation pending/done/failed) the estado is REFUND_DENEGADO, the only denial that ends the Almacor POS polling. (amended by the human 2026-10-04 after the real POS E2E)
  • [x] AC-06 — The create-intention request carries cuit, branch, checkout, mcc, currency, original_amount and bins_max_quantity = 99, and cbu when the merchant operates Transferencias 3.0.
  • [x] AC-07 — The BINs callback answers 204 in under 200 ms p95 and the complete intention reaches Prisma in under 3 s p99 (emulator), always within 27 s.
  • [x] AC-08 — Every payment method in the complete intention includes the 1-installment plan, and method 112 is always present.
  • [x] AC-09 — Callbacks without the apikey we issued, or with a wrong one, are rejected (fail-closed, constant-time comparison).
  • [x] AC-10 — The same callback received twice produces the same result and no double effect.
  • [ ] ~~AC-11 — Mode A: for each BIN, per installment count, the first POS promotion row by order whose prefix and payment method match wins; ranges longer than the BIN are skipped and logged; no match gives 1 payment without adjustment.~~ (withdrawn: Mode A removed by human decision 2026-10-28)
  • [ ] ~~AC-12 — Mode A with a base: the adjustment is computed on the base (capped at the QR amount) and converted to an effective percentage over the QR amount.~~ (withdrawn: Mode A removed by human decision 2026-10-28)
  • [x] AC-13 — Mode B: plans are filtered by validity, weekday and minimum amount, and the most specific wins (BIN range > bank > payment method; branch > merchant); the console refuses two plans that tie.
  • [ ] AC-14 — Amounts use the POS rounding (half away from zero, the single rounding of the POS payment-method promotion engine, ROUND_DOUBLE((ROUND_DOUBLE(base) × ROUND_DOUBLE(pct)) / 100), not RoundExp100) and produce the same adjustment as the pinpad for the same card and plan.
  • [ ] AC-15 — For a plan with a surcharge, TNA and CFT are sent and are consistent with the adjustment; for an interest-free plan or a discount they are 0.
  • [ ] AC-16 — Cuotas MiPyME plans (13 and 16) are offered with their plan code when configured.
  • [x] AC-17 — The adjustment never applies to cashback; cashback is only offered with Visa Débito in 1 payment. (Read as "a cashback is never approved on any other method or installment count: it is compensated", because v27's complete intention has no field to offer cashback; accepted by the human 2026-10-04, pending Prisma questions 21-22.)
  • [x] AC-18 — Plans come only from the gateway's configuration per merchant and branch (Mode B); a POS-sent promotion list is ignored.
  • [ ] AC-19 — When the payment wait expires, the POS receives a denied answer before RouterQR's read timeout, the intention is cancelled at Prisma, and the POS never receives SINRESPUESTA.
  • [ ] AC-20 — When the wallet approves after the POS was told "denied" or after a cancellation, the gateway annuls the payment automatically (INV-01), and the compensation intent was persisted before the POS answer (INV-02; see the INV-02 exception).
  • [x] AC-21 — A late notification is always accepted and applied (INV-03).
  • [ ] AC-22 — Compensation prefers forced annulment over forced refund; before re-sending a forced operation the gateway queries its status; after the retry limit the payment ends in COMPENSATION_FAILED with an alert.
  • [ ] AC-23 — trxanulacion is idempotent: requested by the POS, by RouterQR's sweeper and by our job for the same payment, it produces one reversal at Prisma and answers 2xx (AUTORIZACION_DE_ANULACION_APROBADA) also for payments never approved.
  • [x] AC-24 — A cashier-initiated annulment of an approved payment issues a forced annulment (same batch) or forced refund (earlier batch) and answers the POS AUTORIZACION_DE_ANULACION_APROBADA in both cases: the gateway always tries the annulment and schedules the refund only when Prisma says the annulment is no longer possible, which is not known when the cashier asks (D-S4-9). (amended and accepted by the human 2026-10-28)
  • [ ] AC-31 — When the cashier cancels while trxpago is still waiting (POS sends trxanulacion for the in-flight payment), then the payment takes the compensation path: the intention is cancelled, any later approval is annulled, and both calls answer consistently.
  • [ ] AC-32 — When a new payment starts on the same checkout while a previous one is pending, then the previous payment is marked superseded and, if the wallet had already paid it, it is annulled automatically.
  • [ ] AC-25 — Killing a node in the middle of a payment loses nothing: another node finishes the payment or its compensation.
  • [x] AC-26 — Terminal trace and ticket numbers are unique and gap-free per terminal under concurrent payments.
  • [x] AC-27 — Every call to Prisma and every callback is persisted (wire log) with the payment id; secrets and full benefit card numbers never appear in logs.
  • [x] AC-28 — The POS API listens only on the configured VPN-side address; Prisma callbacks listen on a separate HTTPS port.
  • [x] AC-29 — The console manages merchants, branches, checkouts, terminals, establishments and plans, has a plan simulator (amount + BIN → offered plans), and searches payments with their full trail.
  • [x] AC-30 — The Prisma emulator reproduces approval, rejection, missing BINs, missing notification, duplicate notification, late notification, forced annulment and forced refund.