ADR-002 — Automatic compensation: timeout means cancellation¶
Status¶
Accepted (human, 2026-10-02, Q4).
Context¶
The POS waits a bounded time, but the wallet can still charge the customer afterwards. GatewayQR answers SINRESPUESTA and rejects late approvals with 504, so a customer can stay charged with no sale. GatewayMP compensates, but from an in-memory queue that retries forever. RouterQR adds its own sweeper that sends trxanulacion every 5 s until it gets a 2xx (SPEC §3.0).
Alternatives¶
| Option | Pros | Cons |
|---|---|---|
| Timeout = cancellation + automatic annulment (chosen) | Simple for the cashier; no double charge | Annuls a payment the customer completed at the very edge |
SINRESPUESTA + POS follow-up |
Flexible | Depends on the cashier; source of double charges |
Decision¶
- On wait expiry the gateway cancels the intention at Prisma and answers the POS "denied"; the POS never receives
SINRESPUESTA. - A compensation intent is persisted before any "no sale" answer (INV-02). A leased job (multi-node safe) processes it: not paid →
DELETE /intentions/{id}; paid → forced annulment (returns cashback); forced refund only when annulment is no longer possible. - Before re-sending a forced operation, query
GET /annulments/GET /refunds(Prisma documents no idempotency). - Bounded retries with backoff, then
COMPENSATION_FAILED+ alert. - Late notifications are always accepted (INV-03); if the payment is marked for compensation, they trigger it.
trxanulacionis idempotent: POS, RouterQR sweeper and our job converge on one reversal per payment.- Unknown create outcome (amended 2026-10-02, SD-002, human-approved): a timeout, 5xx or IO error when creating the intention is treated like a wait expiry: in one transaction the payment moves to
COMPENSATION_PENDING, the intention becomes non-live (the checkout is free for the next sale) and the compensation task is persisted; the POS is answered "denied", never a 500. The create call is bounded as a whole (headers and body) by the read timeout and a body size cap; a timeout or oversize answer is unknown. Any 2xx other than 201 is unknown but carries its intention id into the hand-over; after a 201 the id is never dropped unless another intention already holds it. Only a definite refusal is a plain failure: 400, 401, 403, 404 and a 422 that is plainly v27's validation error; 408, 409, 429, any other 4xx, a 5xx, a 201 with an unusable id and a 422 that may be a duplicate are unknown (D-46). Without a Prisma intention id, compensation relies on Prisma question 4b (cancel by integrator id) or on "a new intention invalidates the previous one". - Late wallet results are always recorded on the payment (wallet payment id, amounts, installments, method, authorization code) without changing what the POS sees; a result that is not the expected approval of a
COMPLETE_SENTpayment routes the payment toCOMPENSATION_PENDING, and a paid one gets a forced annulment. A wallet rejection never approves, never claims a wallet payment id and never schedules a forced annulment for money not charged: inCOMPLETE_SENTit isREJECTEDwith its reason, elsewhere it is recorded only; a later approval with a new id is still compensated. A late result whose amounts do not add up (INV-04) is still recorded (payment id, method, installments, authorization code) without the amounts and goes to compensation. State-table edges added for this:INTENT_SENDING→SUPERSEDED,REJECTED→COMPENSATION_PENDING; on the hand-off the intention becomesCANCELLED(timeout, unknown outcome, cancel) orSUPERSEDED(supersede) in the same transaction (D-34). - Storage unreachable at the deadline (amended 2026-10-04, human-approved, INV-02 exception): the expiry keeps trying to persist the hand-over until shortly before the caller's read timeout; if the database still cannot be reached from that node, the POS is answered "no sale" without a persisted intent and an operator alert names the payment. A wallet approval applied at or after the payment's wait deadline never approves it: it is recorded and handed over to compensation. An approval committed before the deadline by another node, unseen by the answering node, is left to the S4 reconciliation.
- One reversal per wallet charge (amended 2026-10-04, human-approved, D-79): reversals and compensation tasks are keyed by the wallet charge (Prisma
payment_id), not by our payment. The charge that moved the payment toAPPROVED(the one the POS saw approved) is the sale's charge; every other charge on the same intention is always annulled. When the last answer the POS heard was "no sale" (INV-01 as amended 2026-10-04: a POS told "approved" ontrxpagoor on its consulta holds a sale, recorded durably aspos_told_approved_at), every charge on that intention is annulled, each with its own reversal. Each reversal intent is persisted in the same transaction that records its charge (INV-02). No wallet charge on an intention survives except the sale's own (INV-01). - Money goes back at most once per wallet charge: a reversal that Prisma completes after we marked it
FAILEDisCOMPLETED_LATEand still counts as that charge's money return; if a refund already returned the money, it isLATE_AFTER_REFUND(outside the one-money-return rule) and raises an alert for manual handling.
Consequences¶
- The gateway wait must end before RouterQR's read timeout (≈ 50 s with dev values; R-13).
- A
Reversalentity with a unique "one active reversal per wallet charge (Prismapayment_id)" constraint (amended 2026-10-04, D-79).
Implementation Plan¶
- Domain:
Paymentstate machine (COMPENSATION_PENDING,COMPENSATED,COMPENSATION_FAILED),Reversalaggregate,CompensationPolicy(pure). - Persistence:
compensation_tasktable withlease_until,attempts,next_attempt_at; claim withUPDATE ... OUTPUT ... WITH (READPAST). - Adapter:
AuthorizerPort.cancelIntention / forceAnnul / forceRefund / queryAnnulment / queryRefund. - Tests: AC-19..AC-25, one test per INV-01..03.
Verification¶
- [ ] AC-19, AC-20, AC-21, AC-22, AC-23 and AC-25 green against the emulator.
- [ ] Killing the node between "persist intent" and "answer POS" still ends with the payment compensated.
- [ ] Two nodes never process the same compensation task at the same time.