Saltar a contenido

DOMAIN MODEL — GatewayPrismaQR

Status: configuration aggregates confirmed (human, 2026-10-02, Q7); transactional aggregates confirmed (human, 2026-10-02). (origin: agent, confirmed: 2026-10-02)

Configuration aggregates

Decision 2026-10-02 (Q7, human): one Merchant per legal owner (CUIT), as in GatewayQR. A chain with several partners is modeled as several merchants, e.g. ALMACOR-ESCANUELA (4 branches) and ALMACOR-PALPASELLI (5 branches). The POS of each branch sends its partner's merchant name in comercio (POS profile PAGOQR_COMERCIO). Several merchants can sit behind the same chain RouterQR.

Entity Key fields Rules
Merchant name (the POS comercio, e.g. ALMACOR-ESCANUELA), cuit, cbu, mcc, enabled One per CUIT. cuit and cbu go in every intention and must match the QR registration at Prisma; mcc is mandatory (v0.20). Owns the accepted payment methods and the gateway-side plans. It has no plan-source setting: the plans are always the gateway's (ADR-003).
Establishment merchant, paymentMethodId, establishmentId (≤ 67 chars, Prisma limit) Acquirer establishment number per merchant (CUIT) and payment method.
Branch merchant, number (POS-side), branchCode (Prisma branch, ≤ 25), enabled number unique per merchant.
Checkout branch, number (POS-side), checkoutCode (Prisma checkout, ≤ 25), enabled number unique per branch. One fixed QR per checkout, registered at Prisma out of band.
Terminal checkout, terminalNumber (8 chars), traceSeq, ticketSeq One per checkout. Sequences advance atomically, never reused.
InstallmentPlan merchant, branch?, paymentMethodId, bankId?, binFrom?/binTo? (digit prefixes), quantity (1 to 99), adjustmentPct (signed, above -100), tna, cft, planCode? (Cuotas MiPyME: 13 = 3 installments, 16 = 6), validFrom, validTo (inclusive), weekdays? (mask, Monday 1 to Sunday 64), minAmount? (inclusive), enabled, offerable (false for a row kept only for its priority) The domain record is domain.InstallmentPlan; the plan engine is GatewayConfiguredPlanSource (docs/CONVENTIONS.md section 9a). Per number of installments the most specific plan that applies that day wins: a plan of the branch before a plan of the merchant, then BIN range, bank, payment method; a tie is a configuration error and the offer is not made. Surcharge plans (above zero) carry TNA and CFT above zero (cost not below the nominal rate); the rest carry zero. The 1-installment plan is implicit and always offered, unless a plan of 1 installment (a discount) replaces it; method 112 takes only plans of 1 installment without bank or BIN. Days are the shops' (gateway.plans.zone). A 1-installment plan may only be a discount: a 1-installment surcharge is refused (PLANES-CUOTAS D3). A row the domain refuses is kept, not dropped: if its payment method, bank, BIN bounds and quantity can be read it is built with offerable = false (wrong rates, a plan code that is not for its installments, a negative minimum, a surcharge of 1 installment, a percentage that the POS rounding takes to -100...), WARN once per row per window, and it still wins its installment count for the cards it applies to without being offered, so a more general plan cannot price those cards (D-S3-19); only a row whose card scope or quantity cannot be read is skipped.
OfferedPlan (value) quantity, totalAmount (amount + adjustment), amountPerInstallment (round2(total / quantity), not reconciled with the total), tna, cft (percentages, two decimals), planCode? What one plan of the complete intention says; stored in the complete snapshot and the base of OfferCheck. Amounts are PlanFigures with the rounding of the POS (PosRounding: half away from zero, the single rounding of its promotion engine, D-S3-9).

Transactional aggregates

Entity Key fields Rules
Payment id (the POS trxid), checkout, state, amount (null while ID_ISSUED: trxid carries no amount), posPointOfSale, posFiscalTicket, cashbackAmount (what the POS asked for), cashbackPaid (what the customer withdrew, as the wallet reported it; null until it reports; AC-17, docs/CONVENTIONS.md section 9c), baseAmount, currency=ARS, finalAmount, adjustmentAmount (signed: positive surcharge, negative discount), installments, planCode (MiPyME), paymentMethodId, paymentMethodType, prismaPaymentId, authorizationCode, tid, walletCode, denialReason, waitDeadlineAt (when the POS wait for the wallet ends: set once, counted from the arrival of the trxpago request (not from the moment its begin transaction gets a connection), so a retry or another node resumes against the same instant, R-13), posToldApprovedAt (column pos_told_approved_at, DATETIME2(3) UTC: the first instant the gateway finished writing an AUTORIZACION_DE_PAGO_APROBADA answer to the POS, on trxpago or on the consulta; NULL while the POS was never told approved; not part of the aggregate or its snapshot, see below), posApprovalIntentAt (column pos_approval_intent_at, DATETIME2(3) UTC: the first instant the gateway durably recorded, before answering, that it was about to tell the POS AUTORIZACION_DE_PAGO_APROBADA; NULL while it never was; not part of the aggregate or its snapshot, see below), version One explicit state machine (states: ID_ISSUED, INTENT_SENDING, INTENT_CREATED, BINS_RECEIVED, COMPLETE_SENT, APPROVED, REJECTED, INTENT_FAILED, COMPLETE_FAILED, SUPERSEDED, CANCELLED, EXPIRED, COMPENSATION_PENDING, COMPENSATED, COMPENSATION_FAILED, ANNULLED, REFUNDED; no UNKNOWN: a timeout or unknown outcome goes to compensation, ADR-002). amount + adjustmentAmount == finalAmount to the cent. Late wallet results are recorded (recordWalletResult(WalletFacts, PaymentAmounts?) returns a WalletResultEffect: APPROVED, COMPENSATE, DUPLICATE, SECOND_WALLET_PAYMENT, WRONG_STATE; never refused for content; the first wallet payment id is kept). The deadline rule of recordWalletResult: a result is APPROVED only for a payment in COMPLETE_SENT whose persisted waitDeadlineAt has not come (now < waitDeadlineAt); at or after the deadline, or with no persisted deadline (fail closed: nobody can prove the result is inside the wait), it is recorded and compensated (COMPENSATE), whoever applies it, because the POS was, or is being, told "no sale" (the exception to INV-02); a wallet refusal at or after the deadline keeps UNCONFIRMED_MESSAGE as the denial reason, so the status query says what the POS heard; waitHasEnded(now) is the question the BINs worker asks, commands supersede, reopenCompensation and recordWalletRejection (effects REJECTED, REJECTION_RECORDED, WRONG_STATE: a rejection never approves and claims no wallet id); WalletResults is the only applier of wallet results (compensation always through CompensationHandOff; a result that names an intention that is not the payment's is FOREIGN_INTENTION: nothing is written); WalletFacts carries tid, wallet code, plan code and terminal data (trace, ticket, terminal number, establishment) for S4 reversals without changing what the POS sees; settled states (APPROVED, ANNULLED, REFUNDED) require the final amount, method and installments. The marker pos_told_approved_at (INV-01: what counts is the last answer the POS heard): it is not a state of the payment but a fact about what left the gateway, so it lives outside the aggregate: PosApprovals.recordToldApproved(paymentId) sets it with UPDATE payment SET pos_told_approved_at = SYSUTCDATETIME() WHERE id = ? AND pos_told_approved_at IS NULL (database time, first instant kept), changes neither version nor updated_at, is never written inside a money transaction, and PaymentEntity does not map the column, so saving the payment cannot overwrite it. PosApprovalMarkerFilter calls it after an approved answer was written out and flushed (docs/CONVENTIONS.md §4); a record that fails is the POS_APPROVAL_UNRECORDED alert (RUNBOOK §3). S4 reads the column with SQL (D-105). The intent pos_approval_intent_at is the record written before the answer, by PosApprovals.recordApprovalIntent(paymentId) (same SQL shape, same rules: database time, first instant kept, no version or updated_at change, never inside a money transaction, not mapped by PaymentEntity): PosApprovalGuard calls it before PosApiController returns an approved answer, and when it cannot be stored the POS is answered the waiting estado instead (POS_APPROVAL_DEFERRED, RUNBOOK §3). Reading the two columns together: either one set means "the POS may have heard approved" (a person decides, never an automatic annulment); both NULL means the POS never heard approved, because the gateway never answers approved without the intent.
Intention payment, checkout, intentionId (Prisma), integratorIntentionId (deployment prefix + payment + attempt), state, binsDeadlineAt, version, updatedAt Own transition table. Live states (INTENT_SENDING, INTENT_CREATED, BINS_RECEIVED, COMPLETE_SENT): at most one per checkout; a payment handed to compensation makes its intention non-live while keeping the Prisma id for the cancel. A payment that starts on the checkout supersedes the payment of its live intention (AC-32): Payment.supersede and CompensationHandOff.handOverSuperseded in the transaction that opens the new payment (intention SUPERSEDED, cancel task). A payment the POS was told approved has no live intention and is a sale: it is never superseded (INV-01).
BinsSnapshot intention, wallet, receivedAt (the arrival of the BINs, from the gateway clock), BINs (JSON, masked before the insert) What the wallet offered. Stored by the BINs worker in the transaction that decides the complete intention. The BINs rule of the deadline: that transaction never sends the complete intention for a payment whose waitDeadlineAt has passed (the POS was told "no sale", possibly without it being persisted): the payment is handed over in the same transaction and the row ends WAIT_EXPIRED.
CompleteSnapshot intention, round, sentAt, one entry per payment method and BIN (bin, bankId; NULL for 112), per-entry establishmentId, terminalNumber, traceNumber, ticketNumber, plans (JSON in the field names of the v27 complete intention: quantity, total_amount, amount_per_installment, tna, cft) What we offered and with which numbers; needed later for forced annulment/refund and for the check of the notified method, BIN, installments and total against the offered plan (D-57, CompleteSnapshots.offeredMethods and OfferCheck). Persisted before the call; the numbers are one block taken from the terminal with one UPDATE ... OUTPUT (INV-05).
WalletCharge (S4) id, payment, intention, prismaPaymentId, sale (the charge that moved the payment to APPROVED), and what names it to Prisma for a forced reversal: paymentMethodId, establishmentId, terminalNumber, traceNumber, ticketNumber One row per wallet charge of an intention, unique by (intention, Prisma payment id) because Prisma's payment id repeats between intentions (D-56). At most one sale per payment. Every charge that is not the sale is annulled (ADR-002 amended, D-79); a "no sale" payment annuls all of them. Written only by WalletResults through ChargeLedger.
Reversal id (internal), payment, charge (S4: the wallet charge it gives back; trxanulacion arrives with id = trxidoriginal = payment id from RouterQR, or id + trxidoriginal 0 from the POS; the payment is trxidoriginal when positive, otherwise id, and trigger ROUTER/POS only labels who asked first), type (ANNULMENT / REFUND; a cancel of an unpaid intention is a task, not a reversal), trigger (POS / ROUTER / COMPENSATION), state (REQUESTED, IN_PROGRESS, COMPLETED, FAILED, COMPLETED_LATE, LATE_AFTER_REFUND), acceptedAt (when Prisma accepted the forced request), prismaRef, failureReason Its own entity, never a copy of the payment row. At most one active reversal per charge and at most one that returns money per charge (filtered unique indexes): a refund exists only after Prisma refused the annulment of that charge; the money of a charge goes back at most once. POS, RouterQR sweeper and the compensation job converge on the charge's reversal (ADR-002). SaleReversal (NO_SALE_CHARGE, NONE, IN_FLIGHT, DONE, FAILED) is where the reversal of a payment's sale charge stands, read through ChargeLedger.saleReversal: trxanulacion answers by it (AnnulPaymentService, idempotent per payment; accepted only once the reversal and its task are stored, INV-02) and the consulta shows a sale whose reversal is IN_FLIGHT or DONE as ANNULLED without changing the stored payment (D-118).
InboundNotification type (classified, unconstrained), rawType (as received), prismaIntentionId, prismaPaymentId, bodyHash (HMAC-SHA256 under a server secret), receivedAt (gateway clock, the one the 27 s of the BINs are counted from), raw body (masked), claimedBy, claimedUntil (database time), processedAt, outcome Persisted before processing and never refused (INV-03); processed under a claim by the BINs worker; outcome vocabulary includes DUPLICATE, COMPLETE_SENT, PAST_DEADLINE, WAIT_EXPIRED, ALREADY_PROCESSED, NOT_LIVE, UNCORRELATED and, for the purchase notification, the effects of a wallet result plus CHECKOUT_MISMATCH, AMOUNT_MISMATCH, UNOFFERED_PLAN, STATUS_NOT_FINAL, REVERSAL_RESULT (docs/CONVENTIONS.md §9, rules 6, 11, 12 and 13); ANNULMENT and REFUND rows are worked by ReversalNotificationWorker (S4) with the outcomes REVERSAL_COMPLETED, REVERSAL_REFUSED, REVERSAL_COMPLETED_LATE, LATE_AFTER_REFUND, REVERSAL_REFUSED_LATE, REVERSAL_DUPLICATE, REVERSAL_UNKNOWN, STATUS_NOT_FINAL, UNCORRELATED, UNUSABLE_NOTIFICATION (CONVENTIONS §11).
CompensationTask payment, kind (CANCEL_INTENTION: not paid, DELETE /intentions/{id}; REVERSE_CHARGE: the forced annulment or refund of one reversal), reversal (set for REVERSE_CHARGE), state (PENDING, IN_PROGRESS, DONE, COMPENSATION_FAILED), leaseOwner, leaseUntil (database time), attempts, nextAttemptAt, lastError Persisted before the POS hears "no sale" (INV-02); at most one active cancel per payment and one active task per reversal; claimed under a lease with READPAST, so two nodes never work the same task; bounded retries with backoff, then COMPENSATION_FAILED and an alert (ADR-002, CONVENTIONS §11).
payment.pos_told_approved_at and payment.pos_approval_intent_at (not entity fields) DATETIME2(3) NULL each: the intent is set once by PosApprovalGuard before an approved answer (trxpago or consulta) leaves, the told marker once by PosApprovalMarkerFilter after it was written out completely INV-01: the last answer the POS heard counts. The S4 reconciliation only reads them (PosApprovals, one port for the writers and the reader): a payment with either marker is a sale the POS may have heard and is never annulled as a no-sale (D-105). The intent is also refused while the sale charge has a reversal (D-S4-10): the POS is then answered the annulment view, never approved. Plain column, not mapped by PaymentEntity.
WireLog paymentId, operation, request, response, status, duration Every call to Prisma.