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 dePLANES-CUOTAS.md. El detalle de las 27 ambigüedades detectadas está enresearch/prisma-gc-v27.md§10. Responsable del envío: el equipo de Tipre.
A. Arquitectura del flujo¶
- La tabla de "crear intención" marca
payment_methods_datacomo 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? - ¿Puede llegar más de un callback de BINs para la misma intención? ¿Se puede reenviar la intención completa?
- ¿Qué pasa si la intención completa llega después de los 27 segundos? ¿Desde qué momento corre el reloj? ¿Qué código devuelven?
- ¿Cuál es el TTL de una intención en estado
created? ¿Qué haceDELETE /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 elintention_id, ¿podemos consultar o cancelar la intención por nuestrointegrator_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¶
- 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,annulledyrefunded. ¿Puede llegar algún estado intermedio (pendiente, en proceso)? ¿Una notificaciónapprovedpuede cambiar después? ¿annulledyrefundedllegan por esta ruta o solo por/annulmenty/refund? Hoy soloapprovedaprueba y solorejectedrechaza; cualquier otro valor se guarda y no cambia el pago. 5c. Transferencia (medio 112): ¿la notificación de compra de una transferencia traeinstallments? 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 siemprepayment_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ónrejected: ¿es definitiva para la intención, o la billetera deja reintentar con otra tarjeta y después puede llegar unapprovedpara la misma intención? Hoy unrejectedrechaza el pago y unapprovedposterior se compensa (anulación automática). 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 detrace_numberyticket_number, y cuándo se reinician?- ¿Cuál es el campo del código postal que exige BCRA (CIMPRA 530)? Está mencionado pero no aparece en el contrato.
- Formato de
cftytna: ¿porcentaje con 2 decimales (40.05) o tasa (0.4005)? - 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¶
- ¿Aceptan un
total_amountdistinto deloriginal_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. - Si
amount_per_installment × quantityno da exactamentetotal_amountpor redondeo, ¿cuál de los dos cobran? - En la notificación, ¿
amountes eltotal_amountdel plan elegido? 12b. En la notificación, ¿card_data.bintiene 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. -
Si nos llega un BIN de un medio que el comercio no acepta, ¿podemos omitirlo en la intención completa?
-
Cashback, importe de la notificación. En una compra con cashback (solo Visa Débito), ¿el
amountde la notificación (y el delGET /payments/qr) incluye el efectivo retirado o es solo el importe de la compra? ¿Yoriginal_amountde la intención es la compra sola, sin el cashback? Hoy suponemos queamountes 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 deresearch/prisma-gc-v27.md§10, que esta lista no recogía; el ejemplo de v27 traeamount500.99 concashback_amount1000.00.) - Cashback, retiro y método. Con
absolute_cashback = true, ¿el cliente puede no retirar (la notificación llega sincashback_amounto con 0)? ¿La billetera puede informarcashback_amountcon 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¶
- ¿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? - ¿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?
- En una anulación forzada de un pago con recargo por cuotas, ¿se anula el
total_amountcobrado (incluido el recargo)? ¿Y en la devolución? - ¿El indicador QR del campo 59 del cierre de lote ISO nos aplica a nosotros o al adquirente?
- 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_numberniticket_number. ¿La notificación de ese pago trae esos tres campos (asignados por Prisma o por la billetera) y tambiénestablishment_idy 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 enCOMPENSATION_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 quePOST /forcedannulmentsresponde 201 (la reversa queda en curso) y que el rechazo llega después, como el estado de la reversa enGET /annulmentso en la notificaciónPOST /annulment; solo entonces pedimos la devolución forzada. Cualquier otra respuesta delPOST(400, 403, 5xx, timeout) la tratamos como un intento fallido y reintentamos, sin pasar nunca a devolución. ¿Es así, o elPOSTpuede 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 porintention_id,payment_method_id,establishment_id,trace_numberyticket_number, y no por elpayment_idde Prisma. Si una intención recibe dos cobros (la billetera cobra dos veces), ¿el segundo cobro lleva los mismostrace_number/ticket_numberde la intención completa o Prisma le asigna otros? ¿Cómo hacemos para anular solo el segundo? 17d.GET /annulmentsyGET /refundssolo aceptanintention_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éstatustiene una reversa en curso, y vuelve a notificarse porPOST /annulmenty/refundcuando 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/qry el 404 mientras un pago está en curso. ¿PuedeGET /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, cuandoDELETE /intentions/{id}responde 404, consultamosGET /payments/qry, 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 deDELETE /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¶
- ¿Hay ambiente de homologación, con URLs, comercios, CBUs y billeteras de prueba, y una lista de casos de certificación?
- ¿Publican las IPs de origen de los callbacks? ¿Cómo se rotan las
apikey? - 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. |
— |