Saltar a contenido

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.
  • trxanulacion is 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_SENT payment routes the payment to COMPENSATION_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: in COMPLETE_SENT it is REJECTED with 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 becomes CANCELLED (timeout, unknown outcome, cancel) or SUPERSEDED (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 to APPROVED (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" on trxpago or on its consulta holds a sale, recorded durably as pos_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 FAILED is COMPLETED_LATE and still counts as that charge's money return; if a refund already returned the money, it is LATE_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 Reversal entity with a unique "one active reversal per wallet charge (Prisma payment_id)" constraint (amended 2026-10-04, D-79).

Implementation Plan

  • Domain: Payment state machine (COMPENSATION_PENDING, COMPENSATED, COMPENSATION_FAILED), Reversal aggregate, CompensationPolicy (pure).
  • Persistence: compensation_task table with lease_until, attempts, next_attempt_at; claim with UPDATE ... 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.