Planes de cuotas QR

1. La respuesta corta

El cliente elige en la billetera; el POS no elige nada. El POS nunca ve la tarjeta: los BINs le llegan al gateway desde Prisma v27 p.19. El POS manda por QR el importe a cobrar, y se entera del medio, de las cuotas y del importe final cuando el pago ya está aprobado. Entonces imputa la diferencia, sea un descuento o un recargo, y cierra el ticket por lo efectivamente cobrado. Es un esquema postpago.

¿De dónde salen los planes? De una configuración por comercio, con dos modos que producen el mismo resultado y están activos desde el inicio:

• Modo A, el POS manda las promociones. El comercio ya mantiene sus rangos de tarjeta (dM_Banda) y sus planes (dM_TarPl) en el POS POS. El POS los serializa en cada trxpago.
• Modo B, el gateway guarda los planes. El comercio los administra en la consola del gateway, con vigencia, días de la semana, monto mínimo y diferencias por sucursal.

Un ejemplo de punta a punta, igual en los dos modos:

Con un descuento el camino es el mismo, con signo negativo: un plan de 1 pago al −10 % sobre $ 1.000 devuelve importe_final 900 y recdesc −100, y el POS imputa el descuento y cierra por 900.

2. Los dos modos

La fuente de los planes es un atributo del comercio (Merchant.planSource, AC-18): POS_SUPPLIED es el modo A y GATEWAY_CONFIGURED es el modo B. Los dos aplican recargos y descuentos, producen el mismo OfferedPlans por tarjeta y comparten las reglas de Prisma (1 cuota siempre, medio 112 siempre).

En los dos modos, el POS necesita la misma imputación postpago (§11), porque el resultado que vuelve es el mismo: importe, importe_final y importe_recdesc con signo.

3. En qué momento se decide

%%{init: {"sequence": {"wrap": true, "width": 180}}}%%
sequenceDiagram
    autonumber
    participant POS
    participant GW as GatewayPrismaQR
    participant PR as Prisma
    participant W as Billetera

    POS->>GW: trxpago con importe 100.000
    alt Modo A
        GW->>GW: guarda las promociones que mandó el POS junto con el pago
    else Modo B
        GW->>GW: usa la tabla de planes del comercio
    end
    GW->>PR: crear intención (original_amount 100.000)
    W->>PR: escanea el QR, el cliente tiene 3 tarjetas cargadas
    PR->>GW: BINs 450799 Visa Galicia, 520048 MC Macro, 491511 Visa Débito Santander
    GW->>GW: match del BIN con las promociones o los planes (milisegundos)
    GW->>PR: intención completa (por tarjeta: 1, 3, 6 y 12 cuotas con sus montos)
    PR->>W: muestra las opciones
    W->>PR: el cliente elige MC Macro, 6 cuotas
    PR->>GW: notificación con amount 112.000 e installments 6
    GW-->>POS: importe 100.000, importe_final 112.000, recdesc +12.000, cuotas 6
    POS->>POS: imputa el recargo postpago y cierra el ticket

En el modo A los planes llegan antes del escaneo, junto con el pago; en el modo B ya están en la base. En los dos casos, cuando Prisma manda los BINs, el gateway tiene todo lo necesario: el match tarda milisegundos y el presupuesto de 27 s v27 p.22 se va en la red, no en el cálculo.

4. Qué dice Prisma v27 (hechos)

Conclusión: que Prisma acepte un total_amount distinto del original_amount, mayor o menor, es una suposición hasta que conteste la pregunta 10 (§13). El sistema se construye con recargos y descuentos activos, pero habilitarlos en producción depende de esa respuesta.

5. Lo que ya existe en el POS

5.1 Rangos y planes

flowchart TB
    PAN["Número de tarjeta"] --> BANDA["dM_Banda<br/>ordenada por iOrden<br/>cDesde · cHasta · iDigmin · iDigmax"]
    BANDA -- "primer rango que matchea" --> RANGO["iIdRango"]
    RANGO --> TARPL["dM_TarPl<br/>cPlan · iCuotas · iPlan<br/>cComercio · fRecDescMPP · bHabilitado"]
    TARPL --> VENTA["Venta con recargo o descuento<br/>idRECARGO_DESCUENTO"]

Lo que no tienen las tablas del POS: vigencia por fechas y días de la semana. Hoy el comercio las maneja actualizando las tablas. En el modo B esas columnas existen en el gateway.

5.2 Redondeo del POS

El gateway calcula igual que el POS (mitad hacia arriba con el mismo doble redondeo, AC-14). Si no, la misma tarjeta daría un recargo distinto en el pinpad y en el QR.

6. Modo A: promociones del POS

6.1 Cómo viajan en trxpago

El POS manda filas planas, una por cantidad de cuotas, ordenadas. Se envían solo las que tienen planes habilitados para QR, para no mandar la tabla entera desde un POS DOS. Los nombres de los campos son provisionales: S3 los fija con el equipo del POS.

{
  "id": 1206901,
  "totalitem": 100000.00,
  "totalcashback": 0,
  "nropv": 1,
  "nroticketfiscal": "12346",
  "promos": [
    { "orden": 10, "mediopago": 1,   "desde": "450799", "hasta": "450799", "cuotas": 3,  "recdesc": 0 },
    { "orden": 11, "mediopago": 1,   "desde": "450799", "hasta": "450799", "cuotas": 6,  "recdesc": 0 },
    { "orden": 20, "mediopago": 31,  "desde": "491511", "hasta": "491511", "cuotas": 1,  "recdesc": -10 },
    { "orden": 25, "mediopago": 31,  "desde": "454545", "hasta": "454545", "cuotas": 1,  "recdesc": -20, "base": 30000 },
    { "orden": 31, "mediopago": 1,   "desde": "4",      "hasta": "4",      "cuotas": 6,  "recdesc": 12 },
    { "orden": 41, "mediopago": 104, "desde": "51",     "hasta": "55",     "cuotas": 6,  "recdesc": 12 },
    { "orden": 42, "mediopago": 104, "desde": "51",     "hasta": "55",     "cuotas": 12, "recdesc": 25 }
  ]
}

• El ejemplo es un extracto de las filas de §9. recdesc es el % con signo de fRecDescMPP: positivo es recargo y negativo es descuento.
• base es opcional: la parte del ticket a la que aplica la promoción. Sin base, aplica a todo el importe QR.
• El gateway guarda las promociones tal como llegaron junto con el pago (payment.pos_promotions) y arma desde ahí la oferta.
• Sin promos, el gateway ofrece 1 pago sin ajuste a todas las tarjetas aceptadas.
• TNA y CFT son obligatorios para Prisma cuando hay recargo, y dM_TarPl no los tiene. El gateway verifica que sean coherentes con el recargo (AC-15); de dónde salen en el modo A se define en S3. Sin interés, o con descuento, valen 0.

6.2 El match de BINs

La regla replica IdentifyDataCard, pero por cantidad de cuotas (AC-11):

flowchart TB
    START["BIN de Prisma (6 u 8 dígitos)<br/>más payment_method_id"] --> ACC{"¿Medio aceptado<br/>por el comercio?"}
    ACC -- "no" --> NOACC["No se ofrece<br/>(pregunta 13 a Prisma)"]
    ACC -- "sí" --> LOOP["Recorrer las filas de promos<br/>por orden ascendente"]
    LOOP --> PM{"¿La fila es del mismo medio<br/>que informa Prisma?"}
    PM -- "no" --> NEXT["Siguiente fila"]
    PM -- "sí" --> LEN{"¿desde o hasta tienen<br/>más dígitos que el BIN?"}
    LEN -- "sí" --> UNDEC["Indecidible:<br/>se saltea y se registra"]
    UNDEC --> NEXT
    LEN -- "no" --> PFX{"¿El prefijo del BIN cae<br/>entre desde y hasta?"}
    PFX -- "no" --> NEXT
    PFX -- "sí" --> Q{"¿Esa cantidad de cuotas<br/>ya tiene ganadora?"}
    Q -- "sí" --> NEXT
    Q -- "no" --> WIN["GANA esta fila<br/>para esa cantidad de cuotas"]
    WIN --> NEXT
    NEXT --> MORE{"¿Quedan filas?"}
    MORE -- "sí" --> PM
    MORE -- "no" --> DONE["Una ganadora por cantidad de cuotas<br/>más 1 pago sin ajuste si falta"]

Reglas:

1. Para cada cantidad de cuotas gana la primera fila por orden cuyo prefijo y medio coinciden. No gana «la más específica»: si el gateway usara otra regla, la misma tarjeta tendría planes distintos en el pinpad y en el QR.
2. Comparación por prefijo: BIN[0:len(desde)] ≥ desde y BIN[0:len(hasta)] ≤ hasta, igual que el strncmp del POS.
3. Chequeo de medio de pago: la fila tiene que coincidir con el payment_method_id de Prisma. Esto evita que una Visa débito caiga en un rango genérico «4» pensado para Visa crédito.
4. Dos límites conocidos: Prisma no informa el largo del PAN, así que iDigmin e iDigmax no se pueden evaluar; y un desde o hasta de más de 8 dígitos no se puede decidir con el BIN: se saltea y queda registrado (R-08).
5. Sin ganadora: la tarjeta va en 1 pago sin ajuste, siempre que el medio esté aceptado.
6. Se guarda qué fila ganó para cada cantidad de cuotas y por qué se descartaron las otras.

6.3 Con base

Cuando una fila trae base, el ajuste se calcula sobre esa base (acotada al importe QR) y se convierte en un porcentaje efectivo sobre el QR (AC-12). Ejemplo, QR de $ 100.000, fila −20 % con base $ 30.000:

7. Modo B: planes del gateway

7.1 Qué guarda cada plan

Tabla installment_plan, por comercio:

El plan de 1 cuota es implícito y nunca se guarda: siempre se ofrece.

7.2 Cómo se resuelve

flowchart TB
    START["BIN, medio y banco de Prisma<br/>más importe, fecha y sucursal"] --> ACC{"¿Medio aceptado<br/>por el comercio?"}
    ACC -- "no" --> NOACC["No se ofrece"]
    ACC -- "sí" --> CAND["Candidatos: planes habilitados<br/>del comercio para ese medio"]
    CAND --> F1{"¿Coinciden banco y rango de BIN<br/>cuando el plan los fija?"}
    F1 -- "no" --> OUT["Se descarta"]
    F1 -- "sí" --> F2{"¿Está vigente hoy, aplica este día<br/>y el importe llega al mínimo?"}
    F2 -- "no" --> OUT
    F2 -- "sí" --> G["Por cada cantidad de cuotas<br/>gana el plan más específico"]
    G --> S["Rango de BIN gana sobre banco<br/>y banco gana sobre medio<br/>la sucursal gana sobre el comercio"]
    S --> DONE["Una ganadora por cantidad de cuotas<br/>más 1 pago sin ajuste si falta"]

El ajuste se calcula siempre sobre todo el importe QR. Dos planes que empatan en especificidad para la misma tarjeta son un error de configuración: la consola se niega a guardarlos (AC-13).

8. Cómo se calculan los montos

Valen para los dos modos y son los del POS:

• TNA y CFT: los datos de cada plan vienen del adquirente o del banco; el gateway solo verifica la coherencia con el ajuste. Calcularlos nosotros mete una responsabilidad regulatoria que no corresponde. Ilustrativo, con sistema francés e IVA del 21 % sobre el interés: 6 cuotas +12 % da TNA 40,05 % y CFT 61,87 %; 12 cuotas +25 % da TNA 43,34 % y CFT 68,28 %.
• Cashback: solo con Visa Débito y en 1 pago v27 p.97. El ajuste se aplica sobre la compra, nunca sobre el efectivo (AC-17).
• Cuotas MiPyME: los planes 13 (3 cuotas) y 16 (6 cuotas) se ofrecen con su código de plan cuando están configurados (AC-16). El objeto installments[] de Prisma no tiene un campo de código de plan: cómo se indica es la pregunta 9.

9. Ejemplo y simulador

Almacor, ticket de $ 100.000 por QR. Los medios aceptados son 1, 31, 104, 105, 106 y 112; Amex (65) no está aceptado.

Modo A. Promociones que manda el POS:

El orden importa: la Visa de Galicia (450799) gana las filas 10 y 11 y obtiene 6 sin interés; cualquier otra Visa crédito cae en las filas 30 y 31 y obtiene 6 con +12 %.

Modo B. Planes del gateway, vigentes del 2026-10-01 al 2026-10-31:

Para 6 cuotas, la Visa de Galicia gana el plan 3 (banco, más específico) los martes y jueves y el plan 4 el resto de los días. La fecha por defecto es el martes 2026-10-06.

10. El ciclo de vida del ajuste

flowchart TB
    A["Modo A: promos en trxpago<br/>(desde dM_TarPl.fRecDescMPP)<br/>Modo B: installment_plan"] --> C["Match del BIN<br/>(gateway)"]
    C --> D["installments.total_amount<br/>(intención completa)"]
    D --> E["El cliente elige<br/>(billetera)"]
    E --> F["notificación.amount<br/>más installments"]
    F --> G["recdesc = amount − importe<br/>(gateway)"]
    G --> H["Imputación postpago<br/>(POS)"]

Lo que vuelve al POS:

La regla no cambia: importe + importe_recdesc == importe_final, al centavo (INV-04).

11. La imputación en el POS

11.1 Cómo cierra el POS (postpago)

Después de la aprobación, el POS recibe importe, importe_final e importe_recdesc y cierra por lo que cobró la billetera. La imputación que hoy existe para descuentos en un POS de la familia hace todo esto POS de referencia pos_mppo.cpp:3625-3719:

1. Controles: coherencia importe + recdesc == importe_final, descuento no mayor que el total, e idempotencia por autorizadortrxid.
2. Filas de detalle por alícuota de IVA (bAcumulado=1, importes negativos para el descuento) POS de referencia pos_tic2.cpp:987-1157.
3. El IVA se recalcula desde el neto con el ajuste, nunca se prorratea. El centavo de residuo va al bucket de mayor neto.
4. Recalcula las percepciones y prorratea los redondeos fiscales.
5. Registra idRECARGO_DESCUENTO con signo en dE_TMdeP y lo imprime como «Rec/Desc» entre SUBTOTAL y TOTAL POS de referencia pos_vnta.cpp:4279-4330.

11.2 Descuento y recargo

Los dos son de primera clase: el POS imputa el que corresponda al signo de importe_recdesc.

flowchart TB
    R["importe_recdesc del gateway"] --> S{"Signo"}
    S -- "negativo (descuento)" --> D1["Filas negativas por alícuota"]
    S -- "positivo (recargo)" --> R1["Filas positivas por alícuota"]
    D1 --> IVA1["IVA recalculado desde el neto"]
    R1 --> IVA2["IVA del recargo financiero<br/>(definición impositiva pendiente)"]
    IVA1 --> T["idRECARGO_DESCUENTO con signo<br/>en dE_TMdeP · cierra la Z"]
    IVA2 --> T
    T --> P{"¿Impresora fiscal?"}
    P -- "no" --> PNF["Línea Rec/Desc en el ticket<br/>(genérica)"]
    P -- "sí" --> PF["Comando fiscal: D para descuento, R para recargo<br/>(a validar)"]

11.3 El peligro de hoy

Hoy, si llega un recdesc positivo, la imputación del POS de referencia devuelve 0 y el llamador lo ignora. La venta queda registrada por el importe original, mientras la billetera cobró más. No hay reversa ni error visible: solo una línea de log (inferido de leer el código, no se ejecutó). Es el riesgo R-04.

Regla (INV-06): el POS nunca registra una venta QR por un importe distinto del que cobró la billetera. Si no puede imputar, falla en forma explícita y dispara la reversa del pago.

11.4 Almacor y Becerra

Sus fuentes solo parsean importe_recdesc POS pos_ctoq.cpp:3508; la imputación existe únicamente en el POS de referencia. Hay que portarla a Almacor y Becerra y sumarle el recargo. Es una dependencia del sistema, no una alternativa (R-07).

12. Riesgos

13. Preguntas que hay que cerrar con Prisma

La numeración es la de PRISMA-PREGUNTAS.md.

14. Decisiones