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_sourcedoes not exist. - A
promoslist or abase_amountthat a POS may still send intrxpagois 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), notRoundExp100(corrected 2026-10-28 from the POS source; it saidRoundExp100double rounding). - Surcharges and discounts are active from the start (human, 2026-10-02); production use depends on Prisma confirming that
total_amountmay differ fromoriginal_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_recdescis signed toward the POS.
Implementation Plan¶
- Domain:
PlanSourcewith the singleGatewayConfiguredPlanSource(looked up per checkout byMerchantPlanSource),PlanFiguresandPosRoundingfor the amounts. - Persistence:
installment_plantable. 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.