Contrato con el autorizador

Cómo el GatewayQR adjunta la respuesta de BeneficiosCenter a la intención de pago que viaja al Autorizador DINI/TECSO, y qué devuelve este último. Fuente: docs/Beneficios-contrato-autorizador.pdf del repositorio del sistema y ADR-004.

Convención de este documento

Negro (en el PDF fuente) = campo del estándar Prisma v27 ("Integradores Grandes cuentas, QR"). Naranja = extensión propuesta por Tipre, no es estándar Prisma: requiere acuerdo con el Autorizador DINI/TECSO. Se marca cada campo abajo.

BeneficiosCenter decide, antes de autorizar, qué descuento corresponde a cada tipo de cuenta DINI para ese ticket. El GatewayQR adjunta el resultado a la intención de pago en el bloque benefits_methods_data del estándar Prisma. El Autorizador DINI/TECSO aplica una sola entrada — la que coincide con la cuenta que efectivamente pagó — y devuelve lo aplicado en benefits_data. Los filtros de BeneficiosCenter (vigencia, día y horario, sucursal, monto mínimo, tipo de factura) ya vienen resueltos: lo que llega, aplica.

1. Lo que viaja en la intención de pago (GatewayQR → Autorizador)

{
  "original_amount": 100000.00,
  "benefits_methods_data": [
    {
      "establishment_id": "12345678",
      "benefits_card": { "code": "990", "description": "Jueves Dini Negocios 10%" },
      "discount": {
        "percentage": 10.00,
        "maximum_discount_amount": 15000.00,
        "amount": 10000.00,
        "type": "DISCOUNT"
      }
    },
    {
      "establishment_id": "12345678",
      "benefits_card": { "code": "991", "description": "Gift Card 5% Septiembre" },
      "discount": { "percentage": 5.00, "amount": 5000.00, "type": "DISCOUNT" }
    }
  ]
}

Campo	Origen	Estándar Prisma v27
benefits_methods_data	array opcional	sí (págs. 14, 21, 28, 29 del doc v27)
benefits_card.code	paymentMethodId de BeneficiosCenter	sí — alfanumérico, no se valida; por eso viajan los códigos DINI 990/991
benefits_card.description	description de BeneficiosCenter	sí
discount.percentage	percentage de BeneficiosCenter	sí
discount.maximum_discount_amount	maxDiscountAmount de BeneficiosCenter	sí — opcional: si el beneficio no tiene tope, no se envía
establishment_id	configuración del gateway, no de BeneficiosCenter	sí
discount.amount	discountAmount de BeneficiosCenter	NO — extensión Tipre
discount.type	type de BeneficiosCenter	NO — extensión Tipre

Siempre es descuento sobre el total del ticket.

Por qué existe la extensión Tipre

discount.amount es el monto ya calculado por BeneficiosCenter — amount × percentage / 100, redondeado a 2 decimales y recortado al tope. Evita que el autorizador compute y unifica el redondeo. discount.type anticipa beneficios que no sean descuento (por ejemplo puntos de un programa de lealtad); hoy siempre vale DISCOUNT. Si el Autorizador DINI/TECSO no acepta estos campos, el gateway los omite y el contrato queda en los cuatro campos estándar sin cambiar nada más — mismo criterio de degradación que aplica a maximum_discount_amount cuando es null (ADR-004, punto 2).

Ejemplo A — cómo se calcula amount: ticket original 100.000,00 × 10 % = 10.000,00; el tope es 15.000,00 y 10.000,00 no lo supera, así que amount = 10.000,00. Para la Gift Card no hay tope: 100.000,00 × 5 % = 5.000,00.

1b. Mismo bloque cuando el descuento supera el tope

{
  "original_amount": 250000.00,
  "benefits_methods_data": [
    {
      "establishment_id": "12345678",
      "benefits_card": { "code": "990", "description": "Jueves Dini Negocios 10%" },
      "discount": {
        "percentage": 10.00,
        "maximum_discount_amount": 15000.00,
        "amount": 15000.00,
        "type": "DISCOUNT"
      }
    }
  ]
}

Ejemplo B: ticket original 250.000,00 × 10 % = 25.000,00, que supera el tope de 15.000,00. Entonces amount = 15.000,00, el mismo valor que maximum_discount_amount: el porcentaje sigue informando 10 %, pero el monto ya viene recortado.

Regla: amount = mín(original_amount × percentage / 100, maximum_discount_amount), redondeado a 2 decimales. El Autorizador DINI/TECSO no computa nada: descuenta amount y devuelve discounted_amount = 15.000,00, y el pago queda en 235.000,00.

2. Lo que devuelve el Autorizador DINI/TECSO (webhook o consulta)

{
  "status": "approved",
  "payment_method_id": 990,
  "amount": 90000.00,
  "benefits_data": {
    "benefits_card": [ { "code": "990", "description": "Jueves Dini Negocios 10%" } ],
    "original_amount": 100000.00,
    "discounted_amount": 10000.00,
    "percentage": 10.00,
    "type": "DISCOUNT"
  }
}

Campo	Estándar Prisma v27
benefits_data (viene solo si intervino una tarjeta de beneficios)	sí (págs. 37, 46, 47)
benefits_data.benefits_card, .original_amount, .discounted_amount	sí
benefits_data.percentage, .type	NO — extensión Tipre, permiten conciliar sin recalcular y detectar si el tope recortó; no son imprescindibles: con code y discounted_amount alcanza

Con payment_method_id = benefits_card.code, el gateway sabe qué entrada se aplicó, calcula importe_recdesc e importe_final para el POS, y el trxid lo cruza con la auditoría de BeneficiosCenter (ver E2E con GatewayQR para una corrida real de punta a punta con estos mismos campos).

Diagrama de secuencia

sequenceDiagram
    participant POS
    participant GW as GatewayQR (Tipre)
    participant BC as BeneficiosCenter (Tipre)
    participant AUT as Autorizador (DINI/TECSO)

    POS->>GW: 1. Intención de pago
    rect rgba(224, 248, 72, 0.15)
    Note over GW,BC: RUTA CALIENTE — objetivo < 20 ms
    GW->>BC: 2. POST /resolver
    BC-->>GW: 3. benefits[] por cuenta
    end
    GW->>AUT: 4. Intención + benefits_methods_data
    AUT-->>GW: 5. Autorización + benefits_data
    GW-->>POS: 6. importe_final / importe_recdesc

Referencias

• [Integradores] Grandes cuentas - QR v27 (Prisma).
• BeneficiosCenter SPEC §4 y ADR-004.
• Cómo configurar el lado GatewayQR de esta integración (API key, timeouts, comportamiento fail-safe), en Configurar el lado GatewayQR.
• Confirmación formal de DINI de que el autorizador acepta el bloque con códigos 990/991: aún pendiente (ver RISKS.md, R-02).