Resumen del alcance — Pago con documentos
Análisis Funcional: Pago con documentos — parte 1 de 5. Índice · Siguiente: El flujo del pago →
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.
Este paquete cubre todo lo que ocurre en el mostrador cuando un beneficiario viene a cobrar un giro de Soterex: cómo se lo identifica, qué se le pide, qué datos carga el operador, qué papel se imprime y firma, y qué escaneos quedan guardados contra la transacción.
Lo que pasa con la plata —de qué caja sale, contra qué prefondeo se descuenta— vive en el Módulo Caja. Lo que pasa con la transacción como registro —cómo llega, qué estados tiene, quién la puede ver— vive en el Análisis Funcional original.
0.1 Qué problema resuelve y para quién
Hasta E4b, pagar era un botón. El operador buscaba el MTCN, confirmaba, y la transacción pasaba a PAID. Eso alcanzaba para el control interno, pero no alcanza para el regulador ni para una auditoría.
El material de CIS-EC del 2026-08-07 lo dejó explícito en dos requerimientos:
"Si Soterex no envía la columna por la API, favor incluir los campos en la pestaña del pago de la tx (Módulo Cajero)" — requerimiento #1, hoja Requerimientos.
"Permitir guardar en c/tx los siguientes documentos: la carta que envía Soterex, la identificación del cliente (anverso y reverso), foto del cliente con la identificación junto al rostro, la papeleta firmada por el cliente y el operador" — requerimiento #5.
Traducido: de las 36 columnas que quedan en el reporte transaccional de CIS, una parte no la manda Soterex — la tipea el cajero mientras el cliente está enfrente, porque es el único momento en que esa información existe. Y el respaldo de que el pago ocurrió no es el registro en la base: es un legajo de escaneos que hay que poder mostrar meses después.
Los tres destinatarios reales de este módulo:
| Quién | Qué necesita |
|---|---|
| El operador de ventanilla | Un flujo que no lo frene: si el cliente ya se llevó la plata, poder registrar el pago aunque le falte un escaneo. |
| Cumplimiento / el regulador | Las 36 columnas completas y el legajo documental de cada transacción. |
| Auditoría interna | Saber quién miró el documento de identidad de quién, y cuántas veces se reimprimió una papeleta. |
0.2 Qué incluye
| Capacidad | Estado |
|---|---|
| ❌ Se implementó y se sacó el 2026-08-10 — ver §1.2 | |
| 13 campos del pago que el cajero carga en ventanilla (11 desde E5a; la fecha de nacimiento y la nacionalidad se suman con B4.0) | ✅ Implementado |
PAID viejas por transferencia quedan como historia de solo lectura | ✅ Implementado |
| Catálogo de 9 tipos de soporte documental, con obligatoriedad por medio de pago | ✅ Implementado |
| Completitud derivada — "pagada pero incompleta" sin agregar un estado nuevo | ✅ Implementado |
| Descarga auditada de cada documento, sin URL directa, acotada por PDV | ✅ Implementado |
| Papeleta en PDF, en dos formatos: la tirilla de 58 mm (réplica del modelo Word del cliente) y la hoja A4 con dos copias (B5). Cada país define el suyo y se puede bajar el otro. Reimprimible | ✅ Implementado |
| Formulario de enrolamiento generado por el sistema | 📋 Sin implementar — hoy se sube escaneado |
| Reporte regulatorio de 36 columnas | ✅ Implementado el 2026-10-02 (B4) como reporte de Cumplimiento: permiso propio, solo Admin, Excel de descarga auditado. Ver Secuencias de pantalla, 5.7 |
0.3 Qué explícitamente NO incluye
- No hay wizard de pasos obligatorios — para los nueve documentos post-pago. El plan v2 hablaba de un "wizard de tres uploads"; lo que se construyó para esos nueve tipos (después de pagar) es un formulario y un stepper visual (1, 2, 3...) — desde 2026-09-11 dibujado como pasos numerados en vez de una lista plana, pero puramente decorativo: se completa en cualquier orden y en cualquier momento, incluso días después, nunca hay un paso bloqueado ahí. Los tres documentos previos al pago (Carta + identificación) son la excepción, desde el 2026-09-12 — ver el punto siguiente y ADR-008.
- El pago se bloquea solo por Carta + identificación (anverso y reverso) — el resto de los datos y documentos, no. Hasta el 2026-09-12 esto decía "el pago nunca se bloquea"; Carlos pidió invertirlo para esos tres tipos específicamente, porque son lo que el operador tiene que cotejar contra el beneficiario antes de entregarle la plata. Ver §1.4 — la razón original (no frenar el registro después de que la plata salió del cajón) sigue vigente para todo lo demás, y es exactamente por eso que la Papeleta firmada —que no puede existir todavía— sigue sin bloquear.
- No hay borrado de documentos. No existe endpoint de baja: un soporte contable no se borra. Un escaneo mal tomado se reemplaza subiendo otro del mismo tipo, y el anterior queda (
backend/routes/api.php:58-69, sin rutaDELETE). Desde G5 (2026-10-06) reemplazar uno ya cargado, una vez pagada o cancelada la transacción, es solo del Supervisor del PDV y del Admin: quien pagó sigue subiendo lo que falta, pero no pisa lo que ya está (ver R8). - No hay entidad Cliente. El material dice que los cuatro documentos de transferencia van "por una sola vez" por cliente, pero no hay nada que agrupe transacciones de la misma persona: hoy se piden por transacción. Ver Preguntas Abiertas #4.
- No se guarda el PDF de la papeleta. Se genera al vuelo cada vez. Ver §3.6.
- No hay género ni estado civil, que el formulario de enrolamiento pide y el reporte no. Ver Preguntas Abiertas #6.
- El recibo no convierte moneda. Imprime el monto de la transacción tal cual, con la moneda de pago del país, tasa
1.00000000y los tres montos iguales (PapeletaService::datosBase()). Es correcto mientras el país pague en dólares (Guatemala, ADR-007 §6). El cambio de moneda ya existe del lado de la caja (E4b): un país conpago_en_moneda_localdescuenta la caja convertida y el recibo no lo refleja. Ver Preguntas Abiertas #14.
0.4 Reglas de negocio de más alto nivel
| # | Regla | Estado | Fuente |
|---|---|---|---|
| R1 | El PIN de la carta es el MTCN. No es un dato aparte y no se guarda en una columna propia | ✅ | Decisión de Carlos, 2026-08-07 |
| R2 | No se pide el PIN. Siendo el MTCN, por el camino habitual —buscar por número— el operador tenía que retipear lo que acababa de tipear | ✅ | Probado por Carlos y sacado el 2026-08-10 · §1.2 |
| R3 | El pago se bloquea solo por Carta + identificación (anverso y reverso) — el resto de los datos y documentos, no | ✅ | Hoja Módulo caja fila 14 · §3 del diseño técnico de E5a · modificado por ADR-008 el 2026-09-12 — ver §1.4 |
| R4 | "Pagada pero incompleta" no es un estado: se deriva de los documentos que tiene contra los que su medio de pago exige | ✅ | §1.3 del diseño técnico de E5a |
| R5 | La selfie es opcional y nunca afecta la completitud | ✅ | Hoja Módulo caja fila 18: "DESEABLE, no es obligatorio" |
| R6 | 422. Los cuatro documentos de transferencia solo los piden las PAID viejas que se pagaron así (historia: no se reescribe ni se deja de pedirlos) | ✅ | |
| R7 | Los documentos son PII sensible: nunca se sirven por URL directa, se acotan por PDV y cada acceso queda auditado | ✅ | §2 y §4 del diseño técnico de E5a |
| R8 | Un documento no se edita ni se borra. Reemplazarlo es subir otro del mismo tipo; el anterior queda. Subir un tipo que falta y reemplazar uno ya cargado son dos permisos (G5): con la tx ACCEPTED el Cajero corrige hasta «Confirmar pago»; pagada o cancelada, reemplazar es solo del Supervisor con alcance del PDV y del Admin, y quien pagó solo sube lo que falta (la papeleta firmada, sin la cual la caja no cierra). Cada reemplazo deja TRANSACTION_DOCUMENT_REPLACED en Auditoría | ✅ | TransactionDocument::$timestamps = false · PermissionService::canReplaceTransactionDocuments() · ADR-011, actualización G5 |
| R9 | Una transacción ya pagada se sigue mostrando en la búsqueda, con sus soportes, para corroborarlos | ✅ | Hoja Módulo caja fila 11 |
| R10 | La papeleta es reimprimible y siempre sale idéntica: muestra la fecha del pago, no la de impresión | ✅ | PapeletaService::datosBase() |
| R11 | El MTCN vence: una transacción que entró por la API de Soterex no se puede pagar después de su último día de cobro, y el sistema la cancela sola | ✅ | Especificación de Soterex ("After this date the funds are no longer collectable") · D7 del plan de alineación · ADR-017 · §1.7 |
0.5 Actores
| Actor | Qué hace acá | Permiso |
|---|---|---|
| Operador de ventanilla (Cajero, el Backoffice de antes) | Identifica al cliente contra la carta, paga, completa los datos, sube los soportes, imprime la papeleta. Es quien tiene el documento de identidad en la mano. | pago E para pagar; transacciones E para cargar los datos y subir los soportes, sobre su país y su PDV |
| Supervisor | Revisa qué transacciones quedaron incompletas y con qué soportes. Puede completarlas y pagar. | transacciones E · pago E |
| Admin | Igual que el Supervisor, y es el único que puede cancelar una transacción (desde B6). | transacciones E·B · pago E |
| Cumplimiento (CIS-EC) | Consume los datos en el reporte regulatorio. No opera en esta pantalla. | ⚠️ No es un rol del sistema — ver Módulo Caja §0.5 |
| Auditoría | Lee TRANSACTION_DOCUMENT_VIEWED y PAPELETA_GENERATED en el módulo de Auditoría. | auditoria L |
Ojo con el permiso. Ver y descargar los soportes no va con
transacciones:readsino contransacciones:write(backend/routes/api.php:61-69). No es un descuido: desde E2, el rol Backoffice (hoy Cajero) tuvo la lectura general de transacciones apagada a propósito —opera solo por la pantalla Pago— así que exigirlereadle habría cerrado la puerta a sus propios documentos. (Desde A5.1 el Cajero sí lee Transacciones, acotado a lo que resolvió él; la regla de los soportes no cambió.) Desde B6, pagar ya no va contransacciones:writesino conpago:write; cargar los datos y subir los soportes siguen entransacciones:write.
0.6 Glosario del dominio
| Término | Qué es |
|---|---|
| Carta | El documento que Soterex le envía al beneficiario avisándole que tiene un giro para cobrar. Trae el MTCN, el PIN de pago y el plazo de retiro. Es el primer soporte que se escanea. |
| MTCN | Money Transfer Control Number. El número de control de la transacción. Lo genera la app al recibir la nota de Soterex y se lo responde; Soterex lo imprime en la carta. |
| PIN de pago | Es el mismo MTCN, impreso en la carta sin el prefijo C-. La app no lo pide: ver §1.2. |
| Soporte (o documento) | Cada archivo escaneado o fotografiado que respalda el pago. Nueve tipos posibles, PDF/JPG/PNG, hasta 20 MB. |
| Papeleta | El comprobante que se imprime al pagar, firman el cliente y el operador, y vuelve escaneada como soporte. |
| Formulario de enrolamiento | Alta del beneficiario para giros no presenciales. Solo aplicaba a pagos por transferencia bancaria, que ya no se hacen (G3): hoy lo piden solo las PAID viejas. Se sube escaneado. |
| Cartola bancaria | El extracto de cuenta que prueba la titularidad del beneficiario. Solo con transferencia: hoy, solo en las PAID viejas. |
Medio de pago (delivery_type) | Desde G3 se escribe solo EFECTIVO; TRANSFERENCIA se sigue leyendo en las PAID viejas, y determina qué documentos piden. Columna AA del reporte. |
| Documentación completa | Booleano derivado, no almacenado: si están todos los tipos obligatorios para el medio de pago de esa transacción. |
| Pagada pero incompleta | Transacción PAID cuya documentación no está completa. No es un estado — es la conjunción de dos hechos. Ver §2.4. |
| Reporte regulatorio | El informe de 36 columnas que CIS le presenta al regulador. Se llama reporte de Cumplimiento en la app (B4, 2026-10-02): Excel de descarga, solo Admin. E5a dejó los datos que le faltaban y B4.0 sumó fecha de nacimiento y nacionalidad. |
0.7 Cómo sigue
El flujo del pago reconstruye la ventanilla paso a paso, tal como la describió el cliente en la hoja Módulo caja, y explica las dos decisiones que más definen el módulo: qué es realmente el PIN (y por qué no se pide), y por qué el pago no se frena aunque falte documentación.
Análisis Funcional: Pago con documentos — parte 1 de 5. Índice · Siguiente: El flujo del pago →

