El flujo del pago
Análisis Funcional: Pago con documentos — parte 2 de 5. ← Resumen del alcance · Índice · Siguiente: Datos y documentos →
Actualizado el 2026-10-05 (G3, ajustes v3 del cliente): el medio de pago es solo efectivo. Donde este documento dice «efectivo o transferencia», lo tachado ya no rige: la transferencia se lee (las
PAIDviejas) pero no se escribe (el backend responde422). Ver Preguntas Abiertas, #3.
El orden de este flujo no lo inventamos: sale casi textual de la hoja Módulo caja del Excel de CIS-EC, filas 5 a 14. Lo que sigue es esa secuencia, con lo que la app hace en cada paso y por qué.
El flujo se fue ajustando después de E5 con tres decisiones que cambiaron el orden de los pasos: ADR-008 (Carta e identificación antes de pagar), ADR-011 (los datos del pago, también antes de pagar) y ADR-013 (la caja opera solo el día en que se abrió). Esta página describe el flujo tal como queda con las tres, más una cuarta causa que no es del operador: el vencimiento del MTCN (2026-10-05, §1.7).
1.1 La ventanilla, de punta a punta
Los pasos 1 y 2 —identificación física, cotejo contra la carta y el rostro— ocurren fuera de la app. La app no los puede verificar del todo; desde ADR-008 (2026-09-12), sí deja de confiar ciegamente en que ocurrieron: exige que esos mismos documentos (Carta + identificación) se suban antes de confirmar el pago (paso H), no después.
Desde L2 (2026-10-19, pedido del cliente del 14/10) los pasos van en orden. Primero los datos del pago (paso G); el botón Iniciar pago se habilita cuando están completos y guardados (paso I), no solo tipeados: se habilita con lo guardado, y mientras haya cambios sin guardar queda deshabilitado con un texto que manda a tocar Guardar datos. Los documentos no se ven al consultar: aparecen al tocar Iniciar pago (paso J), y el pago se confirma con un botón Pagar debajo de ellos (paso J2), que se habilita cuando están los tres (paso H). Antes de L2 los dos bloques estaban siempre a la vista y Iniciar pago exigía los dos. El medio de pago es lo único que no se carga en el formulario: aparece recién al tocar Pagar (paso J2), dentro de la ventana de confirmación, con Efectivo ya elegido y como única opción (desde G3, 2026-10-05: la transferencia salió de los medios de pago; ver Preguntas Abiertas, #3). Se puede confirmar sin tocar nada.
En un país con módulo Caja, la condición «caja del día» del paso I significa que la caja que el operador tiene abierta se abrió hoy. Una caja que quedó abierta de un día anterior no paga (ADR-013): la pantalla lo avisa antes de que el operador cargue nada y lo destraba cerrando la caja y abriéndola de nuevo, que es un trámite de otra pantalla. En un país sin módulo Caja esa condición no existe.
Y el cierre del flujo (paso P) no es solo un cartel: una transacción pagada a la que le falta la papeleta firmada frena el cierre de la caja en la que se pagó, hasta que el escaneo se suba (A6.3, ADR-013). El resto de los soportes no frena nada. Qué es «incompleta» se explica en Datos y documentos, §2.4; el cierre, en el manual de Apertura y cierre de caja.
El paso Q (G5, 2026-10-06) es una salida lateral, no parte del camino feliz: si al subir los soportes de una transacción ya pagada se cargó uno equivocado, quien pagó no lo reemplaza; lo corrige un Supervisor con alcance sobre el PDV o un Admin, y queda constancia en Auditoría. Quien pagó sí sigue subiendo lo que falta (paso M), que es lo que le permite cerrar la caja. La regla completa está en §1.6.
1.2 El PIN es el MTCN, y por eso no se pide
Es la definición que más vueltas dio, y termina en una función que se construyó y se sacó. Vale dejar escrito el recorrido completo, porque el razonamiento sigue siendo válido para cualquiera que proponga volver a agregarla.
El análisis del material de CIS-EC (doc/plans/2026-08-07-analisis-definiciones-cis-ec.md, §3.6) leyó la carta al beneficiario y concluyó que el "PIN de Pago" era un control de seguridad separado del MTCN, que no teníamos modelado. Sobre esa lectura, el primer borrador del diseño técnico agregaba una columna pin a transactions.
Carlos lo corrigió el 2026-08-07: no son dos datos, es uno solo impreso dos veces.
Cuando llega una nota de Soterex, la app genera el MTCN y se lo responde. Soterex lo imprime en la carta que le manda al beneficiario, donde figura en dos renglones:
MTCN: C-5436014032
Payment PIN: 5436014032El mismo número, con y sin el prefijo C-. Por eso no se agregó ninguna columna: guardar el PIN aparte habría duplicado un dato que ya teníamos, con la garantía de que en algún momento los dos se desincronizan.
El prefijo es de la carta y nunca se guarda: el MTCN en la app y en la API son los 10 dígitos. Solo se tolera en dos lugares, siempre descartándolo antes de comparar: la búsqueda de Pago y el filtro del Reporte individual (G9.5: el operador copia lo que dice la carta, C-5436014032), y se agrega en un tercero, la columna 21 del reporte de Cumplimiento (G9.3), porque así lo escribe la planilla del cliente.
Por qué se sacó la verificación
Con esa corrección, se implementó igual un paso de verificación: el operador tipeaba el PIN y el botón de pagar no se habilitaba hasta que coincidiera con el MTCN.
Carlos lo probó el 2026-08-10 y encontró el problema: buscando por número de transacción, la pantalla le pedía volver a tipear el número que acababa de tipear. Un paso que no verifica nada.
El argumento con el que se había defendido era la búsqueda por nombre: por ese camino el operador nunca vio el MTCN antes —lo obtuvo del resultado— así que pedir el PIN confirmaba que la persona trae la carta de esa transacción y no de otra a nombre parecido. Protegía contra pagarle al homónimo equivocado, no contra un operador deshonesto (ese ya tiene el número en pantalla).
Ese argumento sólo se sostiene en el camino de búsqueda por nombre. En el otro —que es el habitual, porque el cliente llega con la carta en la mano— el control era puro rozamiento. Y un paso obligatorio que en el caso más frecuente no aporta nada es un paso que la gente aprende a completar en piloto automático, lo que además lo debilita donde sí serviría.
Así que se sacó entero: el endpoint, el método del modelo, el bloque de la pantalla y sus tests.
Si vuelve a discutirse, la forma correcta no es reponerlo como estaba: sería pedirlo sólo cuando el resultado vino de una búsqueda por nombre, que es el único caso donde verifica algo. Con esa forma el operador que llega por MTCN no ve el paso, y el que llega por nombre sí. Nadie lo pidió todavía; queda anotado por si el escenario del homónimo aparece en la operación real.
Desde B1 (2026-10-02) ese escenario no puede darse en la pantalla Pago: busca solo por MTCN, y un nombre no se consulta (avisa «Ingresá un MTCN»). Sigue existiendo en el listado de Transacciones: ahí se busca por nombre, y la ficha de una transacción disponible permite pagarla (Cambiar a PAID) a quien ve la bolsa del país (Supervisor y Admin; el Cajero —el Backoffice de antes— ve en ese listado solo lo que resolvió él, nunca una transacción disponible). Quien lea este apartado para reponer el control tiene que empezar por ahí: el lugar es la ficha de Transacciones y no Pago, y la regla de arriba sigue valiendo, pedirlo solo cuando se llegó por nombre.
1.3 Una transacción ya pagada se muestra igual
Hasta E5a, el buscador de la pantalla Pago descartaba lo que no estuviera ACCEPTED. El material del cliente pide lo contrario:
"Si la tx está pagada, corrobora soportes del pago para eliminar posibilidades de error" — hoja Módulo caja, fila 11.
Tiene sentido operativo: el caso más común es un cliente que vuelve porque falta un papel, o un supervisor revisando un pago del día anterior. Que la transacción "desaparezca" apenas se paga convierte esa revisión en imposible.
Con la transacción en PAID, la pantalla muestra el formulario de datos y la lista de soportes en lugar de las acciones de pago.
Con una salvedad de alcance (G2.1, 2026-10-06). La búsqueda acota por país y no por PDV, así que una PAID que se pagó en otro PDV aparece igual: su estado, el nombre y el monto se ven. Lo que está acotado por PDV —los datos personales cargados al pagar, los soportes y la papeleta— no se ve, salvo para quien la pagó (§1.6). Quien la mira desde fuera de ese alcance no ve el stepper de soportes ni los botones de Imprimir papeleta: ve un aviso que le dice que se pagó en otro punto de venta. El formulario de Datos del pago aparece vacío, porque el backend no manda esos datos fuera del alcance; no hay que leerlo como que no se cargó nada.
1.4 Qué bloquea el pago, y qué no
Hasta el 2026-09-12 esta sección se llamaba "El pago no se bloquea por documentos faltantes", sin excepciones, y era la decisión de diseño más importante del paquete. Sigue siéndolo, pero la lista de lo que sí bloquea creció en tres pasos, cada uno pedido por el cliente o por Carlos y registrado en su ADR:
| Qué tiene que estar | Desde | Dónde lo hace cumplir el backend | Qué ve el operador |
|---|---|---|---|
| Carta de Soterex, Identificación (anverso) e Identificación (reverso) subidas | ADR-008 (2026-09-12) | pay() → 422 MISSING_REQUIRED_DOCUMENTS | "Faltan documentos: …" |
| Los datos del pago, completos y guardados: todos salvo Notas (con la fecha de nacimiento y la nacionalidad desde B4.0); el medio de pago aparece al confirmar, en Efectivo | ADR-011 (2026-09-28) | pay() → 422 MISSING_PAYMENT_DATA | "Faltan datos: …", o el aviso de cambios sin guardar |
| La caja del operador, abierta hoy (solo países con módulo Caja) | ADR-013 (2026-10-02) | pay() → 422 CASH_SESSION_FROM_PREVIOUS_DAY, antes de descontar nada | Primer renglón del motivo, y un aviso fijo arriba de la pantalla |
| Saldo suficiente: el de la caja (con módulo Caja) o el del prefondeo del país (sin él) | ADR-007 | pay() → 422 INSUFFICIENT_CASH_BALANCE / INSUFFICIENT_PREFUNDING | Un aviso al confirmar |
| El MTCN vigente: que el último día de cobro no haya pasado (solo transacciones de la API) | ADR-017 (2026-10-05) | pay() → 422 MTCN_EXPIRED, antes de los documentos, los datos y todo lo que toca plata | Aviso rojo fijo, Iniciar pago deshabilitado con ese único motivo, y la etiqueta Vencida en la búsqueda. Ver §1.7 |
En todos los casos el backend es quien decide: la pantalla deshabilita el botón y dice por qué, pero el 422 existe aunque alguien llame a la API sin pasar por ella.
Todo lo demás sigue sin bloquear nada: la foto del cliente, la papeleta firmada y los cuatro documentos de transferencia (desde G3 esos cuatro solo los piden las PAID viejas que se pagaron por transferencia: el medio de pago es siempre efectivo y un 422 rechaza cualquier otro). La razón original no cambió, y es por qué el resto no bloquea: cuando el operador llega al paso de subir esos escaneos, la plata ya salió del cajón. El cliente la contó, firmó la papeleta y se fue. Si la app se negara a registrar el pago porque falta, por ejemplo, la papeleta firmada, el resultado no sería "no se pagó": sería una caja con menos efectivo del que el sistema dice que tiene, y una transacción que figura disponible para cobrar por segunda vez.
Frenar el registro no evita el problema, lo convierte en un descuadre. La app tiene que reflejar lo que pasó en el mostrador, no lo que hubiera preferido que pasara.
Carta e identificación son distintas por una razón física, no de alcance: son exactamente lo que el operador coteja contra el beneficiario antes de entregarle la plata (§1.1, pasos 1-2), y ese cotejo hoy ocurre fuera de la app sin dejar rastro verificable hasta que alguien sube el escaneo — a veces mucho después, o nunca. Exigirlo antes de pagar no es agregarle fricción a un paso que ya existe en el mostrador: es hacerlo auditable. La Papeleta firmada, en cambio, no podría exigirse antes de pagar aunque quisiéramos: es el comprobante que el cliente firma después de recibir la plata, no puede existir todavía en ese momento.
Los datos tienen su propia razón. Una vez que la transacción está PAID (o CANCELLED) quedan inmutables, Admin incluido: son el respaldo de lo que se reportó al regulador y no hay flujo de corrección (PAYMENT_DATA_LOCKED, 409). Si pudieran faltar al pagar, nadie podría completarlos después, y el reporte saldría con la columna vacía para siempre. Por eso se cargan antes; el botón Guardar datos acepta datos parciales (datosPago()) solo para que lo tipeado no se pierda si el operador se distrae, pero pay() exige el estado completo en la misma llamada y lo guarda junto con el cambio de estado, atómicamente.
El cliente había pedido la no-bloqueante en estos términos —"podría evaluarse la posibilidad de que la tx se quede pagada pero incompleta, si todos los soportes no se han guardado", hoja Módulo caja fila 14— y el diseño técnico de E5a lo adoptó tal cual para los nueve tipos. Las ADR posteriores no lo contradicen: separan "verificar antes de pagar" (nuevo) de "completar el legajo después de pagar" (sin cambios).
Lo que sí hace la app, para los documentos que no bloquean, es no dejar que se olvide: la transacción queda marcada como incompleta, con la lista exacta de lo que falta, visible en la ficha y filtrable en el listado; un aviso permanente en Pago y en Caja nombra cada MTCN pendiente; y la papeleta firmada pendiente frena el cierre de la caja (nunca un pago nuevo). Ver §2.4.
Completar no es corregir (G5, 2026-10-06). Todo lo de esta sección habla de lo que falta: subir la papeleta firmada o la foto del cliente después de pagar es siempre posible para quien pagó, justamente porque no puede existir antes (los documentos de transferencia, solo en las PAID viejas que se pagaron por transferencia: desde G3 un pago nuevo no los pide). Lo que ya está cargado es otra cosa: después de pagar, un documento cargado es parte del legajo que se cotejó y quien pagó no lo pisa. Reemplazarlo es de un Supervisor con alcance sobre el PDV y del Admin, y deja una constancia propia (TRANSACTION_DOCUMENT_REPLACED). Los datos del pago, en cambio, no se corrigen nunca: ni siquiera el Admin (PAYMENT_DATA_LOCKED). Hasta «Confirmar pago», con la transacción ACCEPTED, nada de esto aplica: el Cajero corrige la Carta y la identificación las veces que haga falta. Detalle en §1.6.
1.5 La secuencia completa, con actores
Notar el orden real: los datos y los documentos de identificación se cargan antes del pago, y el resto de los soportes después (ADR-008 y ADR-011). Al confirmar, pay() hace todo en una sola transacción de base de datos —re-chequea el estado con lock, los tres documentos y los datos, valida la caja, descuenta las tres capas, guarda los datos con el medio de pago y pasa a PAID—, así que no puede quedar una transacción pagada con datos a medias. Si el medio de pago o la cuenta bancaria es lo único que cambia respecto de lo guardado (típicamente, un borrador TRANSFERENCIA de antes de G3 que se paga con Efectivo), esa diferencia queda auditada como TRANSACTION_PAYMENT_DATA_UPDATED (con los nombres de los campos que cambiaron, nunca sus valores).
En la pantalla (PagoView.vue), con la transacción ACCEPTED se ven el bloque de solo lectura con lo que mandó Soterex, el formulario de datos y el bloque de Carta + identificación; con PAID se ven los mismos datos en solo lectura (deshabilitados de verdad: en gris), la papeleta (Imprimir papeleta tirilla e Imprimir papeleta A4, dos botones) y la lista completa de soportes. Es coherente con §1.4: primero se verifica identidad y se completan los datos, después se registra lo irreversible, después se completa el resto del legajo.
1.6 Permisos y alcance
Sin módulo de permisos nuevo: los documentos y los datos del pago son parte de la transacción.
Sobre el descuento del pago. El paso "descuenta" toca tres saldos con importes distintos —Holding
amount + fee, Paísamount, Cajaamounten la moneda de pago— pero valida uno solo: la caja del operador. El detalle está en Modelo de saldos §1.6.
| Acción | Permiso | Alcance |
|---|---|---|
| Completar datos del pago | transacciones E | País |
| Subir un soporte que falta a una transacción ya resuelta | transacciones E | Haberla resuelto uno mismo (G2.1), o ser Supervisor/Admin del PDV en una misma asignación (G5). Tener el PDV en el alcance no alcanza: un Cajero del mismo PDV que no la pagó solo consulta |
| Reemplazar un soporte ya cargado de una transacción ya resuelta | transacciones E y fondeo_caja L, en la misma asignación | Esa asignación tiene que cubrir el PDV de la tx. Quien la pagó no entra por haberla pagado (G5) |
Reemplazar un soporte de una ACCEPTED | transacciones E | País (bolsa compartida: el Cajero corrige hasta «Confirmar pago») |
Subir Carta/identificación a una ACCEPTED sin PDV todavía | transacciones E | País (bolsa compartida — ver más abajo) |
| Listar o descargar soportes | transacciones E | País y PDV (una vez asignado), o haberla resuelto uno mismo (G2.1) |
| Emitir la papeleta, en cualquiera de los dos formatos | transacciones L o E | País y PDV — quien puede ver u operar esa transacción — o haberla resuelto uno mismo (G2.1) |
Ver los datos personales del pago en la búsqueda de Pago (datos_pago) | transacciones E | País y PDV, o haberla resuelto uno mismo (G2.1) |
| Borrar un soporte | — | No existe |
El acotamiento por PDV sobre los documentos es más estricto que el de la transacción en sí, y a propósito. En el listado general, una transacción ACCEPTED es bolsa compartida del país: cualquier PDV la puede tomar. Los documentos, en cambio, están siempre acotados por PDV — pero desde ADR-008 (2026-09-12) ya no puede asumirse que "siempre" significa "solo sobre transacciones ya resueltas": Carta e identificación se suben mientras la transacción puede seguir siendo ACCEPTED, así que hay que distinguir tres casos:
// backend/app/Http/Controllers/TransactionDocumentController.php — authorizeScope()
// ACCEPTED sin PDV asignado todavía: bolsa compartida, mismo criterio que
// TransactionController::authorizeScope() para la transacción misma.
if ($transaction->status === 'ACCEPTED' && $transaction->station_id === null) {
return $user;
}
// G2.1: quien la resolvió (resolved_by_user_id) entra aunque su PDV no sea
// el de la transacción. Se evalúa DESPUÉS del permiso por país.
if ($this->permissions->isResolverOf($user, $transaction)) {
return $user;
}
// Ya resuelta, o ACCEPTED con PDV ya asignado por un upload anterior:
// acotamiento de siempre.
$stationIds = $this->permissions->allowedStationIds($user, self::MODULE, $action, $transaction->country_id);
if ($stationIds !== null && ! in_array($transaction->station_id, $stationIds, true)) {
abort(404);
}El primer documento subido sobre una ACCEPTED sin PDV le asigna el PDV del operador que lo sube (misma resolución que ya usa pay(): su PDV activo, el único de su alcance o, con módulo Caja, el de la caja que tiene abierta — ver «El PDV de cada pago», más abajo) — desde ese momento, los documentos de esa transacción quedan acotados a ese PDV, aunque la transacción en sí siga siendo bolsa compartida hasta que se resuelva. pay()/cancel() no reasignan el PDV si un documento ya lo hizo, para no dejar esos documentos huérfanos si termina resolviéndola un operador de otro PDV.
Antes de ADR-008, este acotamiento siempre asumía "transacción ya resuelta" — es el mismo agujero que se encontró y corrigió en Caja el 2026-08-06 (ver Módulo Caja, Preguntas Abiertas #5): un permiso que decía acotar por PDV y validaba solo a nivel país. Acá se escribió cerrado desde el principio para transacciones resueltas, y ADR-008 extendió el mismo criterio al caso nuevo.
Y se responde 404, no 403, cuando el usuario no alcanza la transacción: confirmar que existe ya sería información (TransactionDocumentController.php).
La excepción de quien pagó (G2.1, 2026-10-06)
Todo lo anterior deja una pregunta sin contestar: qué ve quien termina pagando una transacción cuyo PDV fijó otro. Si A sube la Carta y la identificación desde el PDV A, la transacción queda en el PDV A, y si B paga desde su caja del PDV B, pay() no la reasigna. Sin una excepción, B recibía 404 en los soportes y la papeleta de su propio pago: no podía imprimirla, ni subir la firmada, y el cierre de su caja quedaba bloqueado por PENDING_PAYMENT_DOCUMENTS sin que pudiera destrabarlo.
El mismo corte le pasaba a un segundo caso: quien paga con más de un PDV y ninguno activo. Ese usuario subía y pagaba igual, pero la transacción quedaba sin PDV (station_id nulo), y un alcance acotado a PDVs concretos no incluye un PDV nulo: el pagador recibía 404 en lo suyo. La regla de abajo no mira el PDV de la transacción, así que cubre los dos casos. Que ese caso deje de producir transacciones sin PDV es el trabajo de G2.2 y G4 (sección siguiente).
La regla, una sola vez en PermissionService::isResolverOf(): quien tiene resolved_by_user_id igual a su id y el permiso por país queda dentro del alcance de esa transacción. Cubre de un golpe la lista y la descarga de soportes, la subida de la papeleta firmada, la papeleta y el datos_pago de la búsqueda de Pago (y del panel «Mis transacciones»). El aviso «Tenés N pagos con documentación pendiente» aplica la misma idea: un Supervisor acotado a un PDV ve en él lo que pagó fuera de su PDV o sin PDV, porque esa tx le frena el cierre de caja igual. Y «supervisa» se lee dentro de una asignación (G5, P3-2): un Supervisor del PDV B que es Cajero del PDV A ve en el aviso lo de B y lo que pagó él en A, no lo que pagó otro en A, porque ahí no puede completarle los soportes (PermissionService::stationIdsWhereAssignmentHolds). El detalle de la decisión y lo que descartó está en la actualización de ADR-008.
Lo que no cambia, y los tests lo prueban por API (PagadorOtroPdvApiTest), no mirando que el botón no esté:
- Nadie más gana acceso. Un tercero del PDV de quien pagó, que no pagó, sigue recibiendo 404. Quien subió los documentos desde el PDV A ve la transacción como cualquier compañero de ese PDV, y no puede subir (403
CANNOT_MANAGE_DOCUMENTS) porque no la pagó. - Es por transacción, no por PDV. El pagador no gana las demás transacciones del PDV ajeno: ni las pagadas por otro, ni las canceladas, ni una
ACCEPTEDque ese PDV ya reclamó subiendo un documento. - Empieza al pagar.
resolved_by_user_idno existe antes del pago, así que unaACCEPTEDya reclamada por el PDV A sigue acotada a ese PDV: quien opera desde otro PDV acotado no puede ver los tres documentos previos (404) y la pantalla de Pago le deja Pagar deshabilitado (desde L2 los documentos se ven recién al tocar Iniciar pago, y ahí la tarjeta dice que no se pudo cargar la documentación), aunque el backend solo mire enpay()que los tres existan. No es nuevo y G2.1 no lo toca; queda como pregunta para Carlos en el plan de pruebas de G2, caso 4. - Se evalúa después del permiso por país. Quien pagó y hoy no tiene el permiso en ese país no entra.
- El listado y la ficha de Transacciones no cambian, tampoco para el pagador: un Supervisor acotado a un PDV que pagó una tx de otro entra a sus soportes y a su papeleta, y no la ve en Transacciones. Admin y Supervisor no ganan nada sobre las transacciones que no resolvieron; si pagaron o cancelaron una, rige la misma excepción que para el Cajero (también para quien canceló).
- Pagar es la puerta de entrada a esa PII. Como
pay()solo mira que los tres documentos existan, quien paga por API unaACCEPTEDque otro PDV ya reclamó pasa a ver sus soportes. Se acepta (el pago es real y se audita, cada lectura de un soporte y cada papeleta); lo registra el ADR-008 para la revisión de seguridad.
Qué ve quien mira una transacción pagada en otro PDV y no la pagó. La búsqueda la encuentra (acota por país), y el backend responde 404 a la lista de soportes y a la papeleta. La pantalla distingue ese 404 de una falla: en vez de «No se pudo cargar la documentación» muestra, en gris y no en rojo, «Esta transacción se pagó en otro punto de venta: sus soportes y su papeleta los ven ese PDV, un Supervisor o un Administrador» y no ofrece los botones de Imprimir papeleta (sería ofrecer un 404). Si el 404 aparece al pedir la papeleta y la lista sí cargó, el aviso dice «No tenés acceso a la papeleta de esta transacción: se pagó en otro punto de venta». Una falla de red o un 5xx sigue siendo «No se pudo generar la papeleta, probá de nuevo»: ahí sí tiene sentido reintentar.
Subir lo que falta y reemplazar lo cargado (G5, 2026-10-06)
Hasta G5 el backend no distinguía subir un tipo que falta de subir otro del mismo tipo que ya está: los dos insertaban una fila y la pantalla mostraba la más reciente, así que el Cajero que pagó veía Reemplazar sin límite. El cliente pidió que en una transacción pagada los documentos no se modifiquen y que reemplazar sea de Supervisor y Administrador. No se puede aplicar literal: la papeleta firmada existe recién después de pagar y el cierre de caja la exige. Por eso se leyó «modificar» como «reemplazar uno ya cargado», y quedó una regla con dos preguntas:
- Quien pagó sigue subiendo lo que falta (la papeleta firmada, la foto del cliente) y por eso puede cerrar la caja, pero no pisa lo que ya está cargado: si subió el archivo equivocado en el casillero equivocado, lo corrige un Supervisor del PDV o un Admin.
- Supervisa se decide con
PermissionService::assignmentHolds(): tiene que haber una asignación del país confondeo_caja:readytransacciones:writeque además cubra el PDV de la tx. Un Cajero que suma Tesorería, o un Supervisor del PDV B que es Cajero del PDV A, junta esas capacidades de asignaciones distintas y no es supervisor del PDV A. Esto cambia también quién puede subir en una pagada (antes la unión alcanzaba): en A solo sube lo que pagó él. - Un Supervisor de otro PDV no ve la transacción: 404, no 403.
- Cada reemplazo se audita con
TRANSACTION_DOCUMENT_REPLACED: tipo, id del documento reemplazado, estado de la transacción. No guarda el nombre del archivo, tampoco la subida común (H3-09). - El documento reemplazado no se borra. Queda en la base y en el almacenamiento; la pantalla muestra el más reciente de cada tipo.
- En la pantalla (G5.4): cada fila ofrece Subir o Reemplazar según
puede_subir/puede_reemplazar; quien no puede reemplazar ve la línea «Solo consulta» y quien sí ve «Subido pormailel dd/mm». Detalle en §2.7. - Lo prueban
PermissionServiceTransactionScopeTesty, por API,DocumentosReemplazoApiTest: el Cajero que pagó recibe 403 al reemplazar y puede subir la papeleta y cerrar la caja; el Supervisor del PDV y el Admin reemplazan; el de otro PDV recibe 404; con la txACCEPTEDel Cajero reemplaza Carta e identificación;CANCELLEDse comporta comoPAID.
El PDV de cada pago (G2.2 y G4, 2026-10-06)
Una transacción pagada siempre ocurrió en un PDV, y que el sistema lo registre importa: sin PDV, la persona acotada no ve su propio pago en Reporte individual, el Dashboard no se lo suma, Cumplimiento sale con las columnas 33 a 36 vacías y los totales por PDV no cierran. La decisión completa está en ADR-020; esto es lo que ve quien opera la ventanilla.
De dónde sale el PDV del pago, en este orden y sin que ninguno pise al anterior:
- el PDV que ya tiene la transacción, si un primer documento se lo fijó;
- el PDV activo de la persona en el país (lo fija un Administrador en su ficha de usuario);
- el único PDV de su alcance, si tiene uno solo;
- con módulo Caja, el PDV de la caja de la que sale la plata (la que la persona abrió hoy, en ese país): llena el hueco cuando no hubo ninguno de los anteriores. Nunca pisa a un PDV activo: si el activo es distinto del de la caja, gana el activo (y la plata sale de la caja igual). Una caja vencida, de un día anterior, no cuenta: no puede pagar, y el PDV que fijara al subir ya no se corrige al pagar;
- sin ninguno —un alcance sin acotar, como el del Admin, en un país sin Caja, o al subir el primer documento sin una caja abierta—: queda sin PDV, como siempre.
Con módulo Caja, pagar sin una caja abierta hoy nunca llega a la pregunta de los PDV: lo frena antes el 422 de la caja (el de siempre). El rombo de los dos o más PDV es, entonces, el de la subida del primer documento con Caja y el de pagar y subir en un país sin Caja.
El 422 ACTIVE_STATION_REQUIRED (G2.2): quien tiene dos o más PDV y ningún PDV activo, y no tiene una caja abierta en el país que lo desempate, no puede subir el primer documento ni pagar. Antes subía y pagaba igual y la transacción quedaba sin PDV. El mensaje le dice qué hacer: pedirle a un Administrador que fije su PDV activo en su ficha de usuario y, con módulo Caja, abrir su caja (el PDV pasa a ser el de esa caja). Detalles que conviene saber:
- Un alcance sin acotar no se rechaza. El Admin, o cualquier perfil con una asignación del país sin PDVs, sigue subiendo y pagando sin que haya un PDV que elegir.
- Con una sola asignación de un PDV no hay nada que elegir, y con PDV activo tampoco.
- No hay segunda vuelta: si la transacción ya tiene PDV (porque otro operador subió el primer documento), pagar no pide PDV activo.
- En un país con Caja, pagar sin caja abierta sigue dando
NO_CASH_BOX_OPEN_FOR_USER(oCASH_SESSION_FROM_PREVIOUS_DAYsi la tiene de un día anterior): es lo primero que hay que resolver, y al abrir la caja se resuelve también el PDV. - Una caja vencida tampoco desempata al subir el primer documento: quien se olvidó de cerrar ayer la caja de A y hoy trabaja en B tiene que cerrarla y abrir la de hoy; si no, la transacción quedaría atribuida a A con la plata saliendo de B.
- El PDV que fijó el primer documento gana sobre la caja de quien paga, aunque lo haya fijado otra persona (un Admin con su caja en B sube la Carta; paga un Cajero de A con la caja de A: queda en B). Es la causa 6 de RV3-17, ver ADR-020.
- El rechazo sale antes de escribir nada: no queda archivo, ni documento, ni PDV, ni saldo tocado, ni evento de Auditoría.
- Los tests lo prueban por API (
PdvDelPagoApiTest), no mirando que el botón no esté. - Cómo se ve: una notificación con el título «Falta tu PDV activo» y el mensaje del backend, al subir el primer documento, en Pago y en la ficha de la transacción. Quien administra usuarios lo ve antes, en la ficha del usuario: un aviso ámbar «Sin PDV activo en (país)» junto al campo PDV activo (G4.6), que no impide guardar.
Los pagos viejos. Los PAID que quedaron sin PDV y tienen un movimiento de caja PAGO lo completan con el PDV de esa caja en una migración de datos del deploy (D3-8); deja un solo evento de Auditoría, TRANSACTION_STATION_BACKFILLED, con el conteo. No toca los datos del pago, ni un PDV que ya estuviera fijado, ni lo ambiguo.
1.7 El MTCN vence
Hasta el 2026-10-05 un MTCN valía para siempre: la fecha de vencimiento que se calculaba al crear la transacción era informativa y no la aplicaba nadie. La especificación de Soterex dice lo contrario del expiration_date que devuelve CIS: "After this date the funds are no longer collectable". Una transacción que quedara pendiente para siempre además deja a Soterex esperando un desenlace que nunca llega: la especificación aclara que, para ellos, una transacción sin notificación es indistinguible de una que nunca se completó. La decisión es ADR-017 (D7 del plan de alineación).
La regla. El expiration_date es el último día en que se puede cobrar, inclusive. Una transacción está vencida cuando la fecha de hoy en America/Guatemala es posterior a ese día; una sin fecha de vencimiento no vence. Se mide en Guatemala y no en UTC por la misma razón que el «día» de la caja (ADR-013): a la noche de Guatemala ya es mañana en UTC, y una transacción cuyo último día es hoy tiene que poder cobrarse hasta las 23:59 de acá. La regla está escrita una sola vez, como un método de la transacción y un filtro SQL que un test compara, y la usan pay(), el comando de vencimiento y lo que informan las pantallas: lo que se muestra, lo que se rechaza y lo que se cancela no pueden diferir.
Qué hace.
pay()rechaza una vencida con 422MTCN_EXPIRED(y la fecha en la respuesta). Va con la fila bloqueada y después del chequeo de estado —una ya cancelada responde 409 como siempre: una cancelada o vencida nunca pasa aPAID— y antes de los documentos, los datos del pago, la caja y los saldos, de modo que no cueste ni toque plata. Es un 422, no un 409: Pago lee el 409 como "otro usuario la actualizó", y acá no es eso.- La pantalla lo avisa antes de que el operador cargue nada: aviso rojo fijo con la fecha, Iniciar pago deshabilitado con ese como único motivo (cargar documentos o datos no lo destraba), «Se puede cobrar hasta» en las disponibles y la etiqueta Vencida en las coincidencias. Si vence mientras el operador tenía la pantalla abierta, el 422 pone la pantalla al día. La decisión de si está vencida la toma el backend (
expired), nunca la pantalla recalculando con la fecha. - El comando
c2p:expirela cancela sola y le encola a Soterex unCANCELLEDconCXL_EXPIRED. Cancela de a una, con el lock de la fila, y vuelve a comprobar con el lock que sigaACCEPTEDy vencida: si un cajero la pagó entre medio, la saltea. Es idempotente (lo cancelado deja de cumplir el filtro) y tiene un--dry-runque lista sin cambiar nada. Corre desde el scheduler; sin él no vence nada. - No toca ningún saldo. Una
ACCEPTEDno consumió prefondeo ni caja —se debita al cobrar, principal más comisión (ADR-005, ADR-007)—, así que vencer solo cambia el estado.
Alcance: solo las transacciones que entraron por la API de Soterex (api_client_id no nulo). Las de demo de Staging llevan un expires_at sembrado para que se vea, no una vigencia real: aplicarles la regla las dejaría impagables a los 30 o 60 días, y QA las usa para practicar pagos. El mismo criterio vale para las notificaciones: Soterex solo conoce las suyas.
Vigencia. Es una cantidad de días por país (countries.mtcn_expiration_days). Guatemala: 60 días, que es el plazo que trae la carta de Soterex al beneficiario; el default de un país sin valor es de 30. Las transacciones que ya existían al desplegarlo conservan su vencimiento. La vigencia no está confirmada por Soterex (ver Preguntas Abiertas #15).
Análisis Funcional: Pago con documentos — parte 2 de 5. ← Resumen del alcance · Índice · Siguiente: Datos y documentos →

