Saltar a contenido

ADR-003 — Plan source: the gateway holds the plans (Mode B only; Mode A rejected)

Status

Accepted (human, 2026-10-02). Amended 2026-10-28 (human decision): Mode A removed; see Decision.

Context

Prisma sends the wallet's BINs and we must answer, per card, the installment plans with signed surcharge/discount, TNA and CFT within 27 s (v27 p.22). Merchants already keep card ranges (dM_Banda) and plans with fRecDescMPP in the POS; some also run promotions that apply to part of the ticket. Others prefer to manage plans centrally. Details and worked examples: docs/PLANES-CUOTAS.md, docs/emulador-qr.html.

Decision

Mode B only; Mode A (POS-supplied promotions) rejected 2026-10-28 (human decision): less attack surface (untrusted promotion input), one plan path to maintain and test, no dependency on a POS release for promotions; recoverable from tag mode-a-reference.

  • The plans are the gateway's: configured per merchant and branch through the console (method, bank, BIN range, installments, signed %, TNA/CFT, validity, weekdays, minimum amount, branch override); the most specific wins; ties are rejected by the console. There is no per-merchant plan-source setting: merchant.plan_source does not exist.
  • A promos list or a base_amount that a POS may still send in trxpago is ignored (not read, not stored, never a 400; at most a DEBUG line), in the POS-native and in the RouterQR shape. AC-18 proves it.
  • The offer always has the 1-installment plan and method 112 (CompleteOffer); Cuotas MiPyME plans carry their plan code.
  • Rounding as the POS: 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 (corrected 2026-10-28 from the POS source; it said RoundExp100 double rounding).
  • Surcharges and discounts are active from the start (human, 2026-10-02); production use depends on Prisma confirming that total_amount may differ from original_amount (question P1).

The original decision (2026-10-02) was a per-merchant choice between Mode A (the POS sends promos in trxpago; the first row by order whose BIN prefix and payment method match wins; an optional base turns into an effective % over the QR amount) and Mode B. AC-11 and AC-12 belonged to Mode A and are withdrawn.

Consequences

  • The POS release no longer has to serialize promotions into trxpago; surcharges and discounts still need the POS imputation work (SPEC §3 item 10).
  • The merchant must have its plans configured in the console: a merchant with none offers only the single payment. The plans are checked by the gateway, never taken from a request (no untrusted promotion input).
  • Mode A cannot be switched back on by configuration: reviving it means restoring the code from the tag mode-a-reference.
  • importe_recdesc is signed toward the POS.

Implementation Plan

  • Domain: PlanSource with the single GatewayConfiguredPlanSource (looked up per checkout by MerchantPlanSource), PlanFigures and PosRounding for the amounts.
  • Persistence: installment_plan table. Nothing a POS sends about plans is stored.
  • Console: plan CRUD + simulator (amount + BIN → offered plans).
  • Tests: AC-13..AC-18 (AC-11 and AC-12 withdrawn); property tests on rounding.

Verification

  • [ ] AC-13..AC-18 green (AC-11 and AC-12 withdrawn with Mode A).
  • [ ] Same card, same plan: the gateway adjustment equals the pinpad adjustment computed by the POS formula.