Saltar a contenido

Preguntas para Prisma — Integrador Grande Cuenta QR v0.27

Lista consolidada para enviar a Prisma. Fuente: Integradores Grandes Cuentas QR v0.27 (07-10-2025). Reemplaza las listas Q1–Q11 de la propuesta de discovery original (retirada; el estado actual está en SISTEMA.md) y P1–P5 de versiones anteriores de PLANES-CUOTAS.md. El detalle de las 27 ambigüedades detectadas está en research/prisma-gc-v27.md §10. Responsable del envío: el equipo de Tipre.

A. Arquitectura del flujo

  1. La tabla de "crear intención" marca payment_methods_data como opcional y el ejemplo trae cuotas. ¿Un integrador puede precargar los planes al crear la intención y evitar el paso BINs → intención completa?
  2. ¿Puede llegar más de un callback de BINs para la misma intención? ¿Se puede reenviar la intención completa?
  3. ¿Qué pasa si la intención completa llega después de los 27 segundos? ¿Desde qué momento corre el reloj? ¿Qué código devuelven?
  4. ¿Cuál es el TTL de una intención en estado created? ¿Qué hace DELETE /intentions/{id} si ya hubo BINs o si ya hubo pago? 4b. Si al crear la intención se nos corta la conexión (timeout o error 5xx) y no recibimos el intention_id, ¿podemos consultar o cancelar la intención por nuestro integrator_intention_id? ¿O alcanza con crear una intención nueva en la misma caja para invalidar la anterior?

4d. ¿El alta de intención responde siempre 201 Created, o puede responder 200, 202 o 204? (Hoy tratamos cualquier otro 2xx como desconocido y compensamos.) 4c. ¿Una intención puede terminar en más de un pago (por ejemplo, el cliente escanea dos veces o reintenta en la billetera)? ¿O una intención = como máximo un pago aprobado? 23. QR de la caja: alta y forma de mostrarlo. v27 dice que la billetera recibe "la última intención creada para esa caja" (p. 6) y menciona un alta masiva de QR con un Excel que no viene en el PDF (p. 4, v0.19). Entendemos que hay un QR fijo por caja (CUIT + sucursal + caja), impreso, y que el importe viaja solo en la intención. ¿Es así? ¿Cuál es el formato del Excel de alta, qué datos lleva por caja (CUIT, sucursal, caja, CBU, otros) y quién lo carga? ¿El QR impreso por caja es el único camino, o podemos mostrar en pantalla (por ejemplo, en el pinpad) el qr_raw que devuelve la intención (p. 15-16)? En ese caso, ¿ese string es siempre el mismo para la caja o cambia en cada intención?

B. Contrato

  1. Notificación de pago: ¿cuál es la ruta, qué header de autenticación usan, qué respuesta esperan y cuál es la política de reintentos? (v27 no la define.) 5b. Estados de la notificación de compra: v27 lista approved, rejected, annulled y refunded. ¿Puede llegar algún estado intermedio (pendiente, en proceso)? ¿Una notificación approved puede cambiar después? ¿annulled y refunded llegan por esta ruta o solo por /annulment y /refund? Hoy solo approved aprueba y solo rejected rechaza; cualquier otro valor se guarda y no cambia el pago. 5c. Transferencia (medio 112): ¿la notificación de compra de una transferencia trae installments? Hoy, si falta, no podemos asociar el cobro con ningún plan que ofrecimos y el pago se compensa en lugar de aprobarse. 5d. ¿La notificación de compra trae siempre payment_method_type (también en una transferencia)? Hoy, si falta, los datos no alcanzan para dar el pago por aprobado y se compensa. 5e. Una notificación rejected: ¿es definitiva para la intención, o la billetera deja reintentar con otra tarjeta y después puede llegar un approved para la misma intención? Hoy un rejected rechaza el pago y un approved posterior se compensa (anulación automática).
  2. terminal_number: ¿va uno por pedido o uno por medio de pago? (Provisoriamente numeramos trace/ticket por entrada de la intención completa: medio + BIN.) ¿Quién define los rangos de trace_number y ticket_number, y cuándo se reinician?
  3. ¿Cuál es el campo del código postal que exige BCRA (CIMPRA 530)? Está mencionado pero no aparece en el contrato.
  4. Formato de cft y tna: ¿porcentaje con 2 decimales (40.05) o tasa (0.4005)?
  5. Cuotas MiPyME: ¿cómo se indica el plan (13 / 16) en la intención completa? El objeto installments[] no tiene un campo de código de plan, y el anexo dice "hacer la tabla bien".

9b. ¿El cuit va solo con dígitos (30123456789) o con guiones (30-12345678-9)? ¿Tiene que coincidir carácter por carácter con el que se cargó en el alta del QR? 9c. ¿Qué código HTTP esperan que devolvamos a la notificación de pago (200, 201, 202 o 204)? 9d. En el callback de BINs, el campo wallet figura como obligatorio en la tabla pero no aparece en el ejemplo: ¿llega siempre?

C. Montos, recargos y descuentos

  1. ¿Aceptan un total_amount distinto del original_amount, tanto mayor (recargo por cuotas) como menor (descuento por medio de pago)? Es la pregunta más importante: de esto depende habilitar recargos y descuentos en producción.
  2. Si amount_per_installment × quantity no da exactamente total_amount por redondeo, ¿cuál de los dos cobran?
  3. En la notificación, ¿amount es el total_amount del plan elegido? 12b. En la notificación, ¿card_data.bin tiene el mismo largo (6 u 8 dígitos) que el BIN que la billetera listó en el callback de BINs? Hoy aceptamos cualquiera de los dos largos (uno es el comienzo del otro) y comparamos medio, cuotas e importe contra el plan que ofrecimos.
  4. Si nos llega un BIN de un medio que el comercio no acepta, ¿podemos omitirlo en la intención completa?

  5. Cashback, importe de la notificación. En una compra con cashback (solo Visa Débito), ¿el amount de la notificación (y el del GET /payments/qr) incluye el efectivo retirado o es solo el importe de la compra? ¿Y original_amount de la intención es la compra sola, sin el cashback? Hoy suponemos que amount es el total del plan sin el efectivo y, si no es así, el pago se compensa en lugar de aprobarse. (Corresponde a la ambigüedad 19 de research/prisma-gc-v27.md §10, que esta lista no recogía; el ejemplo de v27 trae amount 500.99 con cashback_amount 1000.00.)

  6. Cashback, retiro y método. Con absolute_cashback = true, ¿el cliente puede no retirar (la notificación llega sin cashback_amount o con 0)? ¿La billetera puede informar cashback_amount con un medio que no sea Visa Débito, o con más de un pago? Hoy leemos «sin cashback» o 0 como «no retiró» y aprobamos; cualquier otro retiro que no sea exactamente el pedido, o con otro medio, se compensa (anulación forzada, que devuelve el cashback). ¿Cómo debe informarnos Prisma el retiro en la anulación forzada, que no lleva el monto en el contrato?

D. Reversas

  1. ¿Son idempotentes crear intención, anulación forzada y devolución forzada? ¿Cómo detectan duplicados? En particular, ¿qué código HTTP devuelven si repetimos un integrator_intention_id (409, 422, otro) y significa que la intención ya existe?
  2. ¿Cuándo corresponde anulación forzada y cuándo devolución forzada (mismo día, mismo lote de cierre)? ¿Cuál es el plazo máximo para devolver?
  3. En una anulación forzada de un pago con recargo por cuotas, ¿se anula el total_amount cobrado (incluido el recargo)? ¿Y en la devolución?
  4. ¿El indicador QR del campo 59 del cierre de lote ISO nos aplica a nosotros o al adquirente?
  5. Pago tardío de una intención que nunca recibió la intención completa. Si el cliente paga una intención que cancelamos (o que reemplazamos) antes de enviar la intención completa, nunca le asignamos terminal_number, trace_number ni ticket_number. ¿La notificación de ese pago trae esos tres campos (asignados por Prisma o por la billetera) y también establishment_id y el medio de pago? La anulación forzada nos exige terminal, traza y ticket: si la notificación no los trae, no podemos armarla y el pago queda en COMPENSATION_FAILED (cliente cobrado sin venta, a resolver a mano). ¿Cómo debemos anular o devolver ese pago? ¿O Prisma garantiza que una intención sin intención completa no puede terminar en un pago? 17b. Si la anulación forzada ya no es posible (el lote se cerró), ¿cómo lo informan? Hoy suponemos que POST /forcedannulments responde 201 (la reversa queda en curso) y que el rechazo llega después, como el estado de la reversa en GET /annulments o en la notificación POST /annulment; solo entonces pedimos la devolución forzada. Cualquier otra respuesta del POST (400, 403, 5xx, timeout) la tratamos como un intento fallido y reintentamos, sin pasar nunca a devolución. ¿Es así, o el POST puede rechazar directamente con un código HTTP y un cuerpo que lo diga? Necesitamos la lista exacta de estados y códigos. 17c. La anulación y la devolución forzadas se identifican por intention_id, payment_method_id, establishment_id, trace_number y ticket_number, y no por el payment_id de Prisma. Si una intención recibe dos cobros (la billetera cobra dos veces), ¿el segundo cobro lleva los mismos trace_number/ticket_number de la intención completa o Prisma le asigna otros? ¿Cómo hacemos para anular solo el segundo? 17d. GET /annulments y GET /refunds solo aceptan intention_id. Con varios cobros o varios intentos de reversa sobre la misma intención, ¿qué devuelven (el último, el primero, una lista)? ¿Un 404 significa "no existe" o "todavía no se procesó"? ¿Qué status tiene una reversa en curso, y vuelve a notificarse por POST /annulment y /refund cuando termina? 17e. DELETE /intentions/{id} sobre una intención que ya fue pagada (o vencida), ¿qué responde: 404, 409, 422? Necesitamos distinguir "ya no existe" de "ya se pagó" para saber si hay que anular. 17f. GET /payments/qr y el 404 mientras un pago está en curso. ¿Puede GET /payments/qr?intention_id= responder 404 para una intención que existe y cuyo pago todavía se está procesando (la billetera ya confirmó, pero la compra aún no se registró)? Hoy, cuando DELETE /intentions/{id} responde 404, consultamos GET /payments/qr y, si también responde 404, damos la intención por inexistente y cerramos el pago como compensado, sin anular nada. Si el 404 de la consulta puede significar «todavía no se procesó», el cliente quedaría cobrado sin que lo sepamos. Necesitamos que nos confirmen que un 404 en ambos pedidos implica que no hay ningún cobro, o qué otra señal usar para distinguirlo. 17g. Pago de una intención ya cancelada. Después de DELETE /intentions/{id}, ¿la billetera puede todavía cobrar esa intención (por ejemplo, si el cliente escaneó antes de la cancelación y confirma después)? En nuestras pruebas con el emulador, un cobro así no tiene plan ofrecido y no podemos identificarlo para una anulación forzada: el pago queda para resolución manual. Necesitamos confirmar que una billetera rechaza pagar una intención cancelada o, si no, cómo identificar ese cobro para anularlo.

E. Homologación y seguridad

  1. ¿Hay ambiente de homologación, con URLs, comercios, CBUs y billeteras de prueba, y una lista de casos de certificación?
  2. ¿Publican las IPs de origen de los callbacks? ¿Cómo se rotan las apikey?
  3. Nos faltan anexos: tabla de tarjetas de beneficio, lista de MCC válidos, planilla de alta de QR, tabla de billeteras, tabla de Cuotas MiPyME y la tabla de códigos de respuesta legible (la del PDF está rota).

Uso interno: qué depende de cada respuesta

Esta sección no forma parte del envío a Prisma. Para las preguntas que condicionan el diseño dice por qué importan y qué pasa hoy si la respuesta es «no».

# Por qué importa Si la respuesta es «no»
1 Podría eliminar el reloj de 27 s. —
3 Define el camino de COMPLETE_FAILED. —
4, 4b Compensación cuando no llegó el intention_id. —
8 — Solo de formato.
9 — El código no viaja y AC-16 sigue abierto.
10 Habilita los recargos y descuentos en producción. Los recargos y los descuentos quedan sin habilitar en producción: hasta entonces se ofrecen únicamente planes cuyo total es igual al importe.
11 — Ajustar la última cuota o el total.
12 — Recalcular el importe final de otra forma.
13 — Habría que ofrecerlo al menos en 1 pago.
14 Seguridad de los reintentos. —
15 Riesgo R-10: compensar con una devolución forzada no devuelve el cashback. —
18 Riesgo R-01: la homologación no está documentada en v27 y no la controlamos. —
21, 22 — Hoy se compensa todo pago con cashback que no coincida con lo pedido.
23 Define cómo se da de alta y se muestra el QR de cada caja (impreso o en el pinpad con qr_raw). —
24 Sin esos datos la anulación forzada no se puede armar y el pago queda en COMPENSATION_FAILED. —