# Métodos y pago en línea del Paso 4 de nuevo ingreso

- **Código:** FEAT-005
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-28
- **Autor:** opencode (agente)

## Objetivo

Completar el Paso 4 de nuevo ingreso con la selección de métodos de pago y el pago en línea. El aspirante con una intención en estado `pagando` podrá elegir entre reportar un pago o pagar en línea, ver las formas disponibles por familia, abrir la pasarela correspondiente y procesar el POST de forma segura. Se reutilizan `PaymentService` y `PaymentOrchestrator`, se excluye `saldofavor` y se validan propiedad, estado y forma permitida. No se generan recibos ni se sincroniza con GHL u Orbis.

## Alcance

- Incluye:
  - Endurecimiento de `FormasPagoModel::getFormasPagoPorTipo()`: orden por `orden` si existe o por `id` como respaldo, whitelist de `po`/`rp`, solo formas y bancos activos, exclusión de registros con borrado lógico y datos de banco (`nombre`, `logo`).
  - Métodos `prepararPago()` y `procesarPago()` en `NuevoIngresoPagoService`, con validación de propiedad, estado `pagando` y forma permitida.
  - Exposición pública de `estaAprobada()` y `estaPendienteVerificacion()` para que el controlador resuelva la idempotencia.
  - Métodos `metodos()`, `reportar()`, `enLinea()`, `prePago()` y `postPago()` en `Paso3`.
  - Rutas GET para métodos, familias y preparación de pasarela; ruta POST para el procesamiento.
  - Vistas `metodos.php` y `formas_pago.php`, y parciales compartidos `_metodos_pago.php` y `_formas_pago.php`.
  - Render condicional: solo se muestran las familias con al menos una forma permitida; si no hay ninguna, se informa y se ofrece volver.
  - Parametrización de las seis vistas de pasarela soportadas (`bnscboton`, `bncc2p`, `bncvpos`, `c2pmercant`, `pagomovilb`, `zelle`): flag `$embebida` para ocultar el header legado y uso de `$post_pago_url` en el formulario POST.
  - Corrección del `PaymentOrchestrator::preparar()` para que un fallo de pasarela produzca una excepción capturable y no un error fatal por una clase no importada.
  - Pruebas del modelo, del servicio, del orquestador y de la integración del controlador.
- No incluye:
  - Recibo PDF, GHL, Orbis, sincronización académica ni verificación administrativa de Zelle (ya existe fuera de este flujo).
  - Pasarelas nuevas ni cambios internos en las clases de pago existentes.
  - Migraciones, seeds, cambios de esquema, `gb_config` o `ni_inscripciones`.
  - CSRF. Se registra como riesgo y deuda técnica.
  - Persistir `formas_pago_id` durante `prePago`.
  - Pagos parciales, abonos o cuotas. La palabra "parciales" de la petición se interpreta como vistas parciales (partials) de métodos y formas.
  - Cambios funcionales en la SPA administrativa, en el portal regular o en la API. Las vistas de pasarela compartidas se parametrizan con valores por defecto para conservar el comportamiento del portal regular.
  - `saldofavor` como método de nuevo ingreso.

> **Decisión de alcance:** se evaluó dividir la petición en dos cambios secuenciales (preparar pasarela y procesar pago). El usuario decidió explícitamente mantener un solo documento asumiendo el riesgo. Para reducir ese riesgo, la implementación se ordena en tres fases internas dentro de esta misma especificación.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`. El Paso 4 ya tiene estado, plan, intención, cancelación e intentos (FEAT-004); el estado `pagando` muestra hoy un aviso de que la selección de método estará disponible después.
- `NuevoIngresoPagoService` ya expone `formasPagoDisponibles()` y `esFormaPagoPermitida()`. `formasPagoDisponibles()` agrupa por `po`/`rp`, excluye `saldofavor` y descarta códigos no soportados por `PaymentService`.
- `PaymentService` es el mapa único de formas soportadas y despacha `prePayment()`/`postPayment()`. En la rama, `PaymentOrchestrator` solo exponía `prePayment()` y `postPayment()`; durante la ejecución se agregaron `preparar()` y `procesar()` con intención explícita, y `preparar()` lanza una excepción capturable si la pasarela no devuelve un arreglo.
- La tabla `pg_formas_pago` no tiene la columna `orden` en la migración base. El modelo actual ordena por `orden` y falla en una base limpia; el respaldo de la implementación de referencia usa `fieldExists()` y ordena por `id` cuando no existe.
- La familia `po` corresponde a pago en línea y la familia `rp` a reporte/validación. `pagomovilb` está catalogada como `rp`, pero su pasarela consulta al banco y, si confirma, el flujo actual la aprueba en estado 3. Se respeta el comportamiento de cada pasarela: Zelle deja la intención en 7; `pagomovilb` puede aprobarla en 3; las `po` confirmadas pasan a 3.
- Zelle ya implementa en su `postPayment()` la validación del comprobante, el registro en `pg_zelle_reportes`, la auditoría, el historial y el estado 7. Devuelve `gestionado = true`, por lo que el orquestador no debe volver a actualizar el estado.
- El comprobante de Zelle se guarda en `writable/uploads/comprobantes` con las validaciones existentes (PDF/JPG/PNG, máximo 5 MB, MIME real y nombre seguro). No se agrega lógica de subida nueva.
- `getBaseDatosBySucursal()` (helper `estudiantes`) devuelve el grupo de conexión de la sede a partir de `AASUCURSID`. Se usa para que Zelle convierta bolívares a dólares y para pasar la conexión correcta al procesar.
- La identidad y la sede se resuelven desde la sesión `nuevo_ingreso` y `NuevoIngresoContextService`; nunca desde un `AASUCURSID` enviado por el cliente.
- No se aplica CSRF en el módulo. Este cambio tampoco lo agrega; se registra como riesgo.
- Las pruebas de integración usan SQLite en archivo, como `Paso4NuevoIngresoTest`, porque el controlador abre la conexión de la sede.
- No se agregan dependencias ni se modifican `vendor/`, `public/vendor/`, `system/` ni `app/ThirdParty/`.

## Fases internas de implementación

Aunque la especificación es única, la implementación debe respetar este orden. Cada fase termina con `php -l`, pruebas del área y revisión antes de continuar.

1. **Fase A - Catálogo y selección:** `FormasPagoModel`, parciales `_metodos_pago`/`_formas_pago`, vistas `metodos` y `formas_pago`, métodos `metodos()`/`reportar()`/`enLinea()`, rutas GET y enlace desde el estado `pagando`.
2. **Fase B - Preparación de pasarela:** `prepararPago()` en el servicio y su contrato, `prePago()` en el controlador, ruta GET, parametrización de las seis vistas de pasarela y corrección de `PaymentOrchestrator::preparar()`.
3. **Fase C - Procesamiento:** `procesarPago()` en el servicio y su contrato, `postPago()` en el controlador, ruta POST, normalización de respuestas, manejo de Zelle y pruebas de estados.

## Flujo normal

1. Paso 1: El aspirante con sesión `nuevo_ingreso`, `paso_actual >= 4` y una intención en estado `pagando` abre `GET /inscripciones/nuevo-ingreso/paso-4`. El filtro `nuevoIngresoAuth:4` valida la sesión y el paso.
2. Paso 2: La pantalla del Paso 4 muestra el resumen, el estado `pagando` y la acción "Elegir método de pago", además de cancelar e intentos.
3. Paso 3: El aspirante envía `GET /inscripciones/nuevo-ingreso/paso-4/metodos`.
4. Paso 4: `Paso3::metodos()` valida la sesión y el paso, resuelve el contexto con `Services::nuevoIngresoContext()->resolver()`, obtiene la intención vigente y comprueba que su estado sea `pagando`. Si no lo es, redirige a `/paso-4` con un flash explicativo.
5. Paso 5: Consulta `formasPagoDisponibles()`. El servicio obtiene las formas activas de `pg_formas_pago` y `pg_bancos`, agrupadas por `po` y `rp`, y descarta `saldofavor` y los códigos no soportados.
6. Paso 6: Si ambas familias están vacías, renderiza la pantalla de métodos con un mensaje de indisponibilidad y el enlace de volver. No muestra tarjetas de familia.
7. Paso 7: Si al menos una familia tiene formas, renderiza solo las tarjetas de las familias no vacías: "Reportar pagos" para `rp` y "Pagar en línea" para `po`.
8. Paso 8: El aspirante elige "Reportar pagos" (`GET /paso-4/reportar`) o "Pagar en línea" (`GET /paso-4/en-linea`).
9. Paso 9: `renderFormas($tipo)` valida que `$tipo` sea `po` o `rp`, valida sesión, paso y estado `pagando`, y obtiene la lista de formas de esa familia.
10. Paso 10: Si la familia no tiene formas, redirige a `/paso-4` con un flash. Si tiene formas, renderiza el resumen de la intención, la lista con descripción y logo del banco, el botón de volver a métodos y la acción de cancelar.
11. Paso 11: El aspirante selecciona una forma y envía `GET /paso-4/prepago/{codigo}/{id}`. El código se valida como cadena no vacía y el id como entero positivo.
12. Paso 12: `Paso3::prePago()` valida sesión y paso, y llama a `NuevoIngresoPagoService::prepararPago($id, $niId, $codigo)`.
13. Paso 13: `prepararPago()` obtiene la intención con `obtenerIntencion($id, $niId)`, lo que valida propiedad y borrado lógico. Si no existe o es ajena, lanza una excepción de dominio.
14. Paso 14: `prepararPago()` verifica que el estado sea `pagando` (2), que `esFormaPagoPermitida($codigo)` sea verdadero y que la sede de la intención coincida con la sede resuelta de la postulación.
15. Paso 15: `prepararPago()` agrega `descuento_dolar` a la intención, resuelve el grupo de conexión de la sede y llama a `PaymentOrchestrator::preparar($codigo, $intencion, $dbGroup)`.
16. Paso 16: El orquestador despacha a `PaymentService::prePayment()`. La pasarela devuelve al menos `vista` y los datos que necesita su formulario. Si no hay vista, `prepararPago()` lanza una excepción de forma no disponible.
17. Paso 17: `Paso3::prePago()` enriquece la respuesta con `detalles_intencion_p` (la intención), `detalles_intencion`, bancos activos, `post_pago_url`, breadcrumbs de nuevo ingreso, `embebida = true` y `urls`.
18. Paso 18: Renderiza el layout de nuevo ingreso, un contenedor y la vista de pasarela parametrizada. La vista no repite el header legado y su formulario apunta a `POST /paso-4/postpago/{codigo}/{id}`.
19. Paso 19: El aspirante completa el formulario y lo envía por POST. En Zelle adjunta el comprobante.
20. Paso 20: `Paso3::postPago()` exige método POST. Si llega otro método, devuelve 405 con mensaje y enlace de retorno.
21. Paso 21: `postPago()` valida sesión y paso, lee `$this->request->getPost()` y normaliza los archivos con `archivosDeRequest()`/`archivoComoArray()`, y llama a `procesarPago($id, $niId, $codigo, $data, $files)`.
22. Paso 22: `procesarPago()` obtiene la intención propia y valida sede. Si está aprobada (3/8) o pendiente de verificación (7), devuelve una respuesta idempotente de éxito sin volver a escribir. Si no está en estado 2, lanza una excepción de transición.
23. Paso 23: `procesarPago()` valida que la forma siga permitida, construye el pagador desde la postulación (`cedula`, `sucursal`, `nombre`), agrega `descuento_dolar` y llama a `PaymentOrchestrator::procesar($codigo, $intencion, $data, $files, $dbGroup, $pagador)`.
24. Paso 24: El orquestador despacha a `PaymentService::postPayment()`. Si la pasarela no marcó `gestionado`, actualiza el estado con `IntencionesPagoModel::actualizaStatus()`: las pasarelas confirmadas no Zelle pasan a 3 y registran referencia, monto, respuesta y forma; Zelle ya dejó la intención en 7 y registró el reporte.
25. Paso 25: El controlador normaliza `estatus` y `mensaje` de la respuesta. Si `estatus` es `success`, redirige a `/paso-4` con `exito_pago`; en cualquier otro caso, redirige con `error_pago`.
26. Paso 26: La pantalla del Paso 4 muestra el estado actualizado. Si sigue en `pagando` por un error, conserva la acción de elegir método para reintentar; si quedó `aprobado` o `pendiente`, muestra solo el historial de intentos.
27. Paso 27: Si el aspirante cancela desde las pantallas de métodos o formas, el formulario POST existente de cancelación pasa la intención a 5 y redirige a `/paso-4`. Las pantallas de métodos, familias y pasarela dejan de estar disponibles para esa intención.
28. Paso 28: Todas las pantallas GET de este flujo son de solo lectura respecto de la base de datos. `prePago` solo consulta y prepara la vista; la escritura ocurre en `postPago`.

## Flujos alternativos / variantes

### Solo una familia tiene formas

1. Paso 1: `formasPagoDisponibles()` devuelve `po` con formas y `rp` vacío, o al revés.
2. Paso 2: La pantalla de métodos oculta la tarjeta de la familia vacía.
3. Paso 3: Si el aspirante intenta abrir por URL la familia vacía, `renderFormas()` redirige a `/paso-4` con un flash.
4. Paso 4: La familia disponible conserva su flujo normal.

### Ninguna familia tiene formas

1. Paso 1: `formasPagoDisponibles()` devuelve ambas listas vacías.
2. Paso 2: La pantalla de métodos muestra un aviso de que no hay métodos disponibles y el enlace de volver.
3. Paso 3: No se ofrecen tarjetas de familia ni enlaces a pasarelas.
4. Paso 4: Las rutas `reportar` y `en-linea` redirigen a `/paso-4` con flash.

### Forma no soportada o excluida

1. Paso 1: El catálogo contiene `saldofavor` o un código que `PaymentService` no despacha.
2. Paso 2: `formasPagoDisponibles()` lo descarta antes de renderizar.
3. Paso 3: Si el aspirante fuerza `GET /prepago/saldofavor/{id}`, `prepararPago()` lanza `porMetodoNoPermitido()`.
4. Paso 4: El controlador redirige a `/paso-4` con el mensaje; no se prepara la pasarela.

### Intención aprobada

1. Paso 1: La intención vigente o última está en estado 3 u 8.
2. Paso 2: `metodos`, `reportar`, `enLinea` y `prePago` redirigen a `/paso-4` con un flash de pago ya aprobado.
3. Paso 3: `postPago` devuelve una respuesta idempotente de éxito si recibe un envío viejo.
4. Paso 4: No se crea otra intención, no se cambia el estado y no se registra otro pago.

### Intención pendiente de verificación (7)

1. Paso 1: La intención está en estado 7 (por ejemplo, Zelle ya reportado).
2. Paso 2: Las pantallas de métodos y pasarela redirigen a `/paso-4` con un flash de pago en verificación.
3. Paso 3: `postPago` devuelve una respuesta idempotente: el pago ya fue reportado y está pendiente.
4. Paso 4: No se permite elegir otra forma sobre la misma intención.

### Intención creada (1) o cancelada (5)

1. Paso 1: La intención no está en estado `pagando`.
2. Paso 2: Las pantallas de métodos y pasarela redirigen a `/paso-4` con un mensaje que indica que primero debe iniciar o crear un nuevo intento.
3. Paso 3: No se prepara ni se procesa una pasarela.
4. Paso 4: El aspirante usa las acciones existentes de iniciar o reintentar.

### Zelle

1. Paso 1: El aspirante elige Zelle desde la familia `rp`.
2. Paso 2: `prePago` prepara la vista de Zelle y el orquestador calcula el total en dólares con el descuento de nuevo ingreso.
3. Paso 3: El formulario envía remitente, número de confirmación, fecha y comprobante por POST.
4. Paso 4: La pasarela valida campos y archivo, rechaza referencias duplicadas, guarda el comprobante, registra el reporte y la auditoría, y deja la intención en 7.
5. Paso 5: Devuelve `gestionado = true`; el orquestador no vuelve a actualizar el estado.
6. Paso 6: El controlador redirige a `/paso-4` con el mensaje de reporte registrado.

### Pago Móvil Banesco (`pagomovilb`)

1. Paso 1: El aspirante elige `pagomovilb` desde la familia `rp`.
2. Paso 2: La pasarela consulta al banco con los datos enviados.
3. Paso 3: Si el banco confirma el pago, la pasarela devuelve éxito y el orquestador actualiza la intención a 3.
4. Paso 4: Si no confirma o hay error, devuelve error y la intención permanece en 2.
5. Paso 5: La interfaz de la familia `rp` usa textos de "reportar o validar", no promete que todo `rp` quedará pendiente.

### Pasarela sin vista configurada

1. Paso 1: La forma está permitida y la intención está en 2.
2. Paso 2: `PaymentService::prePayment()` devuelve una respuesta sin `vista`.
3. Paso 3: `prepararPago()` lanza una excepción de forma no disponible.
4. Paso 4: El controlador redirige a `/paso-4` con flash; no se procesa ni se escribe.

### Envío duplicado o referencia repetida

1. Paso 1: El aspirante reenvía el formulario o repite una referencia ya registrada.
2. Paso 2: Si la intención ya está aprobada o pendiente, el servicio responde de forma idempotente.
3. Paso 3: Si la pasarela detecta la referencia duplicada, devuelve error y el orquestador no aprueba de nuevo.
4. Paso 4: El controlador redirige con `error_pago`; el estado anterior se conserva.

### Acceso directo por auto-routing

1. Paso 1: Un método público nuevo se invoca por una URI no prevista en `Routes.php`.
2. Paso 2: El método ejecuta `sesionValida()` y la comprobación de estado antes de cualquier lectura o escritura.
3. Paso 3: Sin sesión o sin paso 4, redirige o responde con el mensaje de error correspondiente.
4. Paso 4: Con sesión válida, el comportamiento es el mismo que por la ruta explícita.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Sesión de nuevo ingreso ausente o inválida | Filtro `nuevoIngresoAuth:4`; comprobación defensiva en cada método | Redirección a `/inscripciones/nuevo-ingreso`; en AJAX/JSON el filtro responde 401 | Sin pantalla de pago; no se escribe |
| `paso_actual` menor a 4 | Filtro; comprobación defensiva | Redirección a `/inscripciones/nuevo-ingreso/materias`; en AJAX 403 | Sin pantalla de pago |
| Sin intención vigente en métodos, familias o pasarela | `obtenerIntencionVigente()` devuelve null | Redirección a `/paso-4` con flash de error | Sin escritura |
| Intención en estado distinto de `pagando` | `estadoDeIntencion()` o `estados_id` | Redirección a `/paso-4` con mensaje según el estado | Estado intacto |
| Intención inexistente o de otra postulación | `obtenerIntencion($id, $niId)` devuelve null | Redirección a `/paso-4` con mensaje genérico; no se revela si el id existe | Sin datos de la intención ajena |
| Sede de la intención distinta de la sede resuelta | Comparación de `AASUCURSID` con el contexto | Excepción de configuración; redirección con mensaje genérico | Sin escritura |
| Forma no permitida, excluida o no soportada | `esFormaPagoPermitida()` o `PaymentService::soporta()` | Redirección a `/paso-4` con "La forma de pago no está disponible." | Sin escritura |
| Pasarela sin `vista` configurada | `prepararPago()` comprueba `response['vista']` | Redirección a `/paso-4` con mensaje; log técnico | Sin escritura |
| Error al preparar la pasarela | Excepción del orquestador o de la pasarela | Redirección a `/paso-4` con mensaje genérico; log técnico | Sin escritura |
| Método distinto de POST en `postPago` | `$this->request->getMethod()` | Página HTML 405 con enlace de retorno | Sin escritura |
| Método distinto de POST en `cancelar` | Comprobación existente | Página HTML 405 con enlace de retorno | Sin escritura |
| Intención aprobada al procesar | `estaAprobada()` | Respuesta idempotente de éxito y redirección con flash | Estado 3/8 intacto |
| Intención pendiente al procesar | `estaPendienteVerificacion()` | Respuesta idempotente y redirección con flash | Estado 7 intacto |
| Intención en estado no pagable al procesar | `estados_id` distinto de 2 | Redirección con `error_pago` | Estado anterior intacto |
| Pasarela devuelve error de validación | Respuesta con `estatus` distinto de `success` | Redirección con `error_pago` y mensaje de la pasarela | Estado 2, salvo que la pasarela haya gestionado otro estado |
| Referencia duplicada | Validación de la pasarela o de `actualizaStatus()` | Redirección con `error_pago` | Sin nueva aprobación |
| Zelle sin comprobante o con archivo inválido | Validación existente de `PagosZelleServices` | Redirección con `error_pago` y mensaje | Estado 2 |
| Fallo de base de datos en Zelle | Transacción de la pasarela | Rollback, eliminación del comprobante y `error_pago` | Estado 2 |
| Error inesperado en métodos o familias | `catch (\Throwable)` | Mensaje HTML 500 o redirección con flash; log técnico | Sin escritura |
| Error inesperado en `prePago` | `catch (\Throwable)` | Redirección a `/paso-4` con mensaje genérico; log técnico | Sin escritura |
| Error inesperado en `postPago` | `catch (\Throwable)` | Redirección a `/paso-4` con mensaje genérico; log técnico | Sin escritura parcial |
| Tipo de familia inválido en el modelo | Whitelist `po`/`rp` | Devuelve `[]` y registra advertencia | Sin consulta |
| Columna `orden` ausente en `pg_formas_pago` | `fieldExists()` | Ordena por `id` | Consulta exitosa |
| Forma o banco inactivo, o registro borrado | Filtros del modelo | Se excluye de la lista | No se ofrece |
| Ninguna forma disponible | Listas vacías | Mensaje en métodos o redirección desde familias | Sin escritura |

## Reglas de negocio y validaciones

- La identidad de la postulación es `ni_inscripcion_id` de la sesión/contexto, nunca un `AASUCURSID` ni un id de intención enviado libremente por el cliente.
- La sede se resuelve con `NuevoIngresoContextService` y debe coincidir con `pg_intenciones_pago.AASUCURSID`. Una discrepancia se trata como error de configuración y no permite preparar ni procesar.
- `metodos`, `reportar`, `enLinea` y `prePago` solo proceden cuando la intención vigente está en estado `pagando` (2). Cualquier otro estado redirige a `/paso-4` con un mensaje, sin revelar datos de intenciones ajenas.
- `postPago` solo acepta POST. `prePago` y las pantallas de selección son GET. `cancelar` conserva su POST obligatorio.
- La forma solicitada debe pertenecer a `formasPagoDisponibles()` y a la familia correspondiente (`po` o `rp`). `saldofavor` queda excluido y los códigos no soportados por `PaymentService` no se listan ni se preparan.
- El monto y la moneda salen de la intención persistida. No se acepta ni se recalcula un monto enviado por el cliente.
- `prePago` no persiste la forma elegida. `formas_pago_id` se actualiza al procesar, por `actualizaStatus()` o por la propia pasarela Zelle.
- El estado final depende de la pasarela:
  - Zelle: 7 (sin verificar) y `gestionado = true`.
  - `pagomovilb`: 3 si el banco confirma; 2 si no confirma o hay error.
  - Pasarelas `po` confirmadas: 3 mediante `actualizaStatus()`.
  - Cualquier error de pasarela: la intención permanece en 2, salvo que la pasarela haya gestionado un estado distinto.
- `prepararPago()` y `procesarPago()` son idempotentes para intenciones aprobadas o pendientes: devuelven un mensaje de éxito sin volver a escribir.
- La validación de propiedad se hace siempre con `obtenerIntencion($id, $niId)`; un id ajeno se trata como inexistente.
- El pagador que recibe la pasarela se construye desde la postulación (`identificacion_valor`, nombre y apellido) y la sede de la intención. No se confía en datos de sesión del portal regular.
- Zelle conserva sus reglas existentes: comprobante obligatorio, PDF/JPG/PNG, máximo 5 MB, MIME real, referencia única, límite configurable de pendientes y almacenamiento bajo `writable/uploads/comprobantes`.
- No se genera recibo PDF, no se marca GHL y no se sincroniza Orbis en este flujo.
- `FormasPagoModel::getFormasPagoPorTipo()` acepta solo `po` o `rp`; cualquier otro valor devuelve `[]` y no consulta. Ordena por `pg_formas_pago.orden` si la columna existe; si no, por `pg_formas_pago.id`. Exige `pg_formas_pago.in_activo = '1'`, `pg_bancos.in_activo = '1'` y `borrado_dt IS NULL`.
- Las vistas escapan toda salida con `esc()`; los atributos usan `esc(..., 'attr')`. No se insertan datos de usuario directamente en JavaScript.
- Las vistas de pasarela conservan compatibilidad con el portal regular: si `$embebida` no está definido o es falso, muestran su header y breadcrumbs actuales; si `$post_pago_url` no se pasa, conservan la URL legada como respaldo.
- Todos los métodos públicos nuevos ejecutan `sesionValida()` y la comprobación de estado, aunque exista una ruta con filtro, para cubrir el auto-routing.
- No se agregan dependencias, migraciones, seeds ni cambios de esquema.
- No se agrega CSRF. Los POST quedan protegidos por sesión, filtro y validaciones de dominio; el endurecimiento CSRF se registra como deuda técnica.

## Contratos y diseño propuesto

### `NuevoIngresoPagoService` y su interfaz

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `prepararPago(int $intencionId, int $niInscripcionId, string $codigo): array` | Validar propiedad, estado 2, sede y forma; preparar la pasarela y devolver `intencion` y `response`. | Solo lectura de la intención; la pasarela puede consultar datos externos. No escribe en la intención. |
| `procesarPago(int $intencionId, int $niInscripcionId, string $codigo, array $data, array $files): array` | Validar propiedad, estado, sede y forma; resolver el pagador; procesar y devolver la respuesta normalizada. | Escribe el estado a través de la pasarela o de `actualizaStatus()`. |
| `estaAprobada(array $intencion): bool` | Indicar si el estado es 3 u 8. | Sin efectos. |
| `estaPendienteVerificacion(array $intencion): bool` | Indicar si el estado es 7. | Sin efectos. |
| `formasPagoDisponibles(): array` | Devolver `po` y `rp` filtradas. | Solo lectura. Ya existe. |
| `esFormaPagoPermitida(string $codigo): bool` | Validar el código contra las formas disponibles. | Solo lectura. Ya existe. |

- `prepararPago()` reutiliza `obtenerIntencion()`, `estadoDeIntencion()`, `esFormaPagoPermitida()`, `descuentoDolarNuevoIngreso()` y `resolverContexto()`. Captura `\Throwable` del orquestador y lo traduce a `NuevoIngresoPagoException::porFormaPagoNoDisponible()`, sin exponer el detalle técnico.
- `procesarPago()` reutiliza `obtenerIntencion()`, `estaAprobada()`, `estaPendienteVerificacion()`, `esFormaPagoPermitida()`, `descuentoDolarNuevoIngreso()` y `resolverContexto()`.
- Ambos métodos cargan `helper('estudiantes')` antes de usar `getBaseDatosBySucursal((int) $intencion['AASUCURSID'])`; si no hay grupo, se lanza `porConfiguracionInvalida()`.
- `prepararPago()` devuelve:
  ```php
  [
      'intencion' => $intencion, // incluye descuento_dolar
      'response'  => $response,  // respuesta de la pasarela, con 'vista'
  ]
  ```
- `procesarPago()` devuelve la respuesta de la pasarela/orquestador con `estatus`, `mensaje` y, cuando aplique, `referencia`, `monto`, `gestionado` y `forma_pago`.
- La interfaz declara `prepararPago`, `procesarPago`, `estaAprobada` y `estaPendienteVerificacion` además de los métodos existentes.
- `Services::nuevoIngresoPago()` no cambia su construcción; el servicio obtiene el orquestador con `Services::paymentOrchestrator()`.

### `PaymentOrchestrator`

- El orquestador real de la rama solo exponía `prePayment($forma, $estudiante)` y `postPayment($forma, $intencion, $contexto)`; `prePayment` busca por cédula y excluye nuevo ingreso. Por decisión de ejecución se agregan `preparar(string $forma, array $intencion, string $dbGroup)` y `procesar(string $forma, array $intencion, array $data, array $files, string $dbGroup, array $pagador)`, reutilizando el despacho de `PaymentService` sin alterar los métodos del portal regular.
- `preparar()` lanza `\RuntimeException('No se pudo preparar la forma de pago.')` cuando `PaymentService::prePayment()` no devuelve un arreglo. El servicio de dominio traduce esa excepción a `NuevoIngresoPagoException::porFormaPagoNoDisponible()`. Además recalcula el desglose en dólares con `descuento_dolar` y la conexión de la sede.
- `procesar()` decodifica JSON, agrega `forma_pago` y, si la pasarela no marcó `gestionado`, llama a `IntencionesPagoModel::actualizaStatus()`.
- No se modifica `PaymentService` ni el mapa de formas soportadas.

### `FormasPagoModel`

| Aspecto | Regla |
| --- | --- |
| Tipo | Solo `po` o `rp`; otro valor devuelve `[]` y registra advertencia. |
| Orden | `pg_formas_pago.orden ASC` si `fieldExists('orden', 'pg_formas_pago')`; si no, `pg_formas_pago.id ASC`. |
| Formas | `pg_formas_pago.in_activo = '1'` y `borrado_dt IS NULL`. |
| Bancos | `pg_bancos.in_activo = '1'`; se conserva el join para obtener `banco_nombre` y `logo`. |
| Selección | `pg_formas_pago.*`, `pg_bancos.nombre AS banco_nombre`, `pg_bancos.logo AS logo`. |
| Salida | Arreglo de filas; no lanza excepciones por datos del catálogo. |

### `Paso3`

| Método | Responsabilidad |
| --- | --- |
| `metodos()` | Renderizar la selección de familias. |
| `reportar()` | Renderizar las formas de la familia `rp`. |
| `enLinea()` | Renderizar las formas de la familia `po`. |
| `prePago($codigo = '', $id = 0)` | Validar GET, sesión, paso, propiedad, estado y forma; preparar y renderizar la pasarela. |
| `postPago($codigo = '', $id = 0)` | Validar POST, sesión, paso, propiedad, estado y forma; procesar y redirigir con flash. |
| `renderMetodos()` | Privado. Resolver contexto, intención vigente, estado y formas; renderizar. |
| `renderFormas(string $tipo)` | Privado. Validar familia, contexto, estado y formas; renderizar. |
| `archivosDeRequest()` | Privado. Normalizar `$this->request->getFiles()` a un arreglo compatible con las pasarelas. |
| `archivoComoArray($archivo)` | Privado. Convertir un `UploadedFile` en `name`, `type`, `tmp_name`, `error`, `size`. |
| `mensajeEstadoNoPagable(string $estado)` | Privado. Devolver el mensaje de redirección para estados distintos de `pagando`. |
| `urls()` | Privado. Agregar `metodos`, `reportar`, `en_linea`, `prepago` y `postpago` a las URLs existentes. |
| `bancosModel()` | Privado. Devolver `BancosModel` para los bancos activos. |
| `sesionValida()` | Privado. Comprobar sesión y `paso_actual >= 4`; se reutiliza. |

- Los métodos auxiliares deben ser `private` para no exponerlos por auto-routing.
- `prePago` y `postPago` validan `$codigo` como cadena no vacía y `$id` como entero positivo antes de llamar al servicio.
- `postPago` usa `$this->request->getPost()` y normaliza archivos; no usa `$_POST` ni `$_FILES` directamente.
- Las respuestas de error de dominio usan redirección con flash. El 405 se conserva como página HTML para métodos incorrectos.
- `index()` agrega `metodos` a `urls()` para que la vista de estado pueda enlazar la selección.

### Rutas

| Método | URI | Acción | Filtro |
| --- | --- | --- | --- |
| GET | `inscripciones/nuevo-ingreso/paso-4/metodos` | `Paso3::metodos` | `nuevoIngresoAuth:4` |
| GET | `inscripciones/nuevo-ingreso/paso-4/reportar` | `Paso3::reportar` | `nuevoIngresoAuth:4` |
| GET | `inscripciones/nuevo-ingreso/paso-4/en-linea` | `Paso3::enLinea` | `nuevoIngresoAuth:4` |
| GET | `inscripciones/nuevo-ingreso/paso-4/prepago/(:segment)/(:num)` | `Paso3::prePago/$1/$2` | `nuevoIngresoAuth:4` |
| POST | `inscripciones/nuevo-ingreso/paso-4/postpago/(:segment)/(:num)` | `Paso3::postPago/$1/$2` | `nuevoIngresoAuth:4` |

- Se conservan `paso-4`, `paso-4/iniciar`, `paso-4/cancelar/(:num)` y `paso-4/intentos/(:num)`.
- No se agrega CSRF a estas rutas en este cambio.

### Vistas

| Archivo | Responsabilidad |
| --- | --- |
| `app/Views/inscripciones/nuevo_ingreso/paso3/metodos.php` | Layout de nuevo ingreso, resumen, tarjetas de familia, cancelar, intentos y volver. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/formas_pago.php` | Layout de nuevo ingreso, resumen, lista de formas de la familia, volver y cancelar. |
| `app/Views/pagos/partials/_metodos_pago.php` | Parcial de tarjetas "Reportar pagos" y "Pagar en línea"; oculta las vacías. |
| `app/Views/pagos/partials/_formas_pago.php` | Parcial de formas con logo, descripción, enlace a `prepago` y estado vacío. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | En `pagando`, reemplaza el aviso por el enlace "Elegir método de pago"; conserva cancelar e intentos. |
| `app/Views/pagos/pagar_int_bnscboton.php` | `$embebida` y `$post_pago_url`; botón convertido en formulario POST para nuevo ingreso. |
| `app/Views/pagos/pagar_int_bncc2p.php` | `$embebida` y `$post_pago_url` en el formulario. |
| `app/Views/pagos/pagar_int_bncvpos.php` | `$embebida` y `$post_pago_url` en el formulario. |
| `app/Views/pagos/pagar_int_c2pmercant.php` | `$embebida` y `$post_pago_url` en el formulario. |
| `app/Views/pagos/pagar_int_pagomovilb.php` | `$embebida` y `$post_pago_url` en el formulario. |
| `app/Views/pagos/pagar_int_zelle.php` | `$embebida`; ya usa `$post_pago_url` y `enctype` para el comprobante. |

- Las vistas de pasarela conservan el layout legado cuando `$embebida` es falso. En modo embebido no muestran breadcrumbs ni banner BCV propios, porque el layout de nuevo ingreso ya aporta el contexto.
- Los formularios usan `method="POST"` y `action="<?= $post_pago_url ?: base_url('/Pagos/postPago/...') ?>"` para no romper el portal regular.
- Los montos se muestran con `number_format()`; no se recalculan en el navegador.
- El logo del banco se muestra si existe; si falta, se usa la descripción como texto de respaldo.
- No se modifica `public/css/tailwind-v4.css`; se usan clases Tailwind existentes.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Modificar | `app/Models/PagosOnline/FormasPagoModel.php` | Whitelist de familia, filtros activos, borrado lógico y fallback de orden. |
| Modificar | `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php` | `prepararPago()`, `procesarPago()`, `estaAprobada()` y `estaPendienteVerificacion()` públicas. |
| Modificar | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/NuevoIngresoPagoServiceInterface.php` | Declarar los nuevos métodos. |
| Modificar | `app/Libraries/Payments/PaymentOrchestrator.php` | Corregir la excepción de `preparar()` para evitar el error fatal. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Nuevos métodos públicos y auxiliares privados. |
| Modificar | `app/Config/Routes.php` | Rutas GET/POST del flujo con `nuevoIngresoAuth:4`. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Enlace a métodos desde el estado `pagando`. |
| Crear | `app/Views/inscripciones/nuevo_ingreso/paso3/metodos.php` | Pantalla de selección de familia. |
| Crear | `app/Views/inscripciones/nuevo_ingreso/paso3/formas_pago.php` | Pantalla de formas por familia. |
| Crear | `app/Views/pagos/partials/_metodos_pago.php` | Parcial de familias. |
| Crear | `app/Views/pagos/partials/_formas_pago.php` | Parcial de formas. |
| Modificar | `app/Views/pagos/pagar_int_bnscboton.php` | `$embebida` y POST a `$post_pago_url`. |
| Modificar | `app/Views/pagos/pagar_int_bncc2p.php` | `$embebida` y POST a `$post_pago_url`. |
| Modificar | `app/Views/pagos/pagar_int_bncvpos.php` | `$embebida` y POST a `$post_pago_url`. |
| Modificar | `app/Views/pagos/pagar_int_c2pmercant.php` | `$embebida` y POST a `$post_pago_url`. |
| Modificar | `app/Views/pagos/pagar_int_pagomovilb.php` | `$embebida` y POST a `$post_pago_url`. |
| Modificar | `app/Views/pagos/pagar_int_zelle.php` | `$embebida` y POST a `$post_pago_url`. |
| Crear | `tests/app/Integration/Paso4PagoTest.php` | Cobertura de métodos, familias, preparación y procesamiento. |
| Crear | `tests/app/Models/PagosOnline/FormasPagoModelTest.php` | Cobertura del modelo robusto. |
| Modificar | `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | Cobertura de `prepararPago()` y `procesarPago()`. |
| Modificar | `tests/app/Libraries/Payments/PaymentOrchestratorTest.php` | Cobertura de la excepción capturable en `preparar()`. |
| Documentar | `docs/features/005-metodos-pago-en-linea-paso-4/plan.md` | Este plan. |

No se modifican migraciones, seeds, `gb_config`, `ni_inscripciones`, `NuevoIngresoContextService`, `PaymentService`, la SPA ni la lógica de las pasarelas internas. Las vistas de pasarela compartidas y `FormasPagoModel` se tocan con compatibilidad hacia el portal regular, que conserva su comportamiento por los valores por defecto y el fallback de URLs.

## Criterios de finalización

- [x] `FormasPagoModel::getFormasPagoPorTipo()` acepta solo `po` o `rp`; un valor inválido devuelve `[]` sin consultar.
- [x] El modelo ordena por `orden` si la columna existe y por `id` si no, sin lanzar error en una base limpia.
- [x] El modelo exige forma activa, banco activo y `borrado_dt IS NULL`, y devuelve `banco_nombre` y `logo`.
- [x] `formasPagoDisponibles()` excluye `saldofavor` y los códigos no soportados, agrupa por `po`/`rp` y conserva una fila por registro activo; no se promete deduplicación por código.
- [x] `GET /paso-4/metodos` exige `nuevoIngresoAuth:4` y estado `pagando`; renderiza solo familias con formas y muestra un mensaje si no hay ninguna.
- [x] `GET /paso-4/reportar` y `GET /paso-4/en-linea` exigen filtro y estado `pagando`; renderizan la familia correcta y redirigen si está vacía.
- [x] La pantalla de métodos oculta la familia vacía y muestra cancelar, intentos y volver; la pantalla de formas muestra descripción, logo, volver y cancelar.
- [x] `GET /paso-4/prepago/{codigo}/{id}` valida sesión, paso, propiedad, estado 2, sede y forma permitida; renderiza la pasarela embebida y no escribe en la intención.
- [x] `prePago` pasa `detalles_intencion_p`, `detalles_intencion`, `bancos`, `post_pago_url`, `breadcrumbs`, `embebida` y `urls` a la vista.
- [x] `POST /paso-4/postpago/{codigo}/{id}` rechaza métodos distintos de POST con 405.
- [x] `postPago` valida propiedad, estado, sede y forma; las intenciones aprobadas o pendientes responden de forma idempotente sin volver a escribir.
- [x] `postPago` llama a `PaymentOrchestrator::procesar()` con el monto persistido, los datos POST, los archivos normalizados, el grupo de conexión de la sede y el pagador de la postulación.
- [x] Las pasarelas no Zelle confirmadas dejan la intención en 3; Zelle la deja en 7 y no recibe una segunda actualización del orquestador.
- [x] `pagomovilb` puede aprobar en 3 cuando el banco confirma; un error conserva el estado 2.
- [x] Las respuestas de `postPago` redirigen a `/paso-4` con `exito_pago` o `error_pago`; no se genera recibo ni se marca GHL.
- [x] Las seis vistas de pasarela soportan `$embebida` y usan `$post_pago_url`; el portal regular conserva su comportamiento cuando no se pasan esos datos.
- [x] Todos los formularios de pasarela usan `method="POST"`; `bnscboton` deja de ser un enlace GET en modo nuevo ingreso.
- [x] `estado.php` muestra "Elegir método de pago" en `pagando` y conserva cancelar e intentos.
- [x] `PaymentOrchestrator::preparar()` lanza una excepción capturable y no un error fatal cuando la pasarela no devuelve un arreglo.
- [x] Todos los métodos públicos nuevos ejecutan `sesionValida()` y validación de estado, incluso por auto-routing.
- [x] Las vistas escapan toda salida con `esc()` y no insertan datos de usuario sin escapar.
- [x] Las pruebas cubren el modelo, el servicio, el orquestador y la integración de métodos/familias/prePago/postPago, incluidos Zelle, `pagomovilb`, intención ajena, estado no pagable, forma no permitida y respuesta de error.
- [x] Las pruebas existentes de `Paso4NuevoIngresoTest` y del área de pagos siguen pasando.
- [x] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [x] `graphify update .` se ejecuta después de los cambios de código.
- [x] No se agregaron migraciones, seeds, CSRF, dependencias ni cambios en `vendor/` o `system/`.
- [x] No se persistió `formas_pago_id` en `prePago` y no se modificó la máquina de estados de FEAT-004.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| División | Se mantiene un solo documento por decisión explícita del usuario, aunque se recomendó dividir en preparar/procesar. Se mitiga con las tres fases internas. |
| Pasarelas | Todas las formas activas soportadas por `PaymentService`, excluyendo `saldofavor`. |
| Familias | `rp` reporta/valida y `po` paga en línea. `pagomovilb` puede aprobar en 3; Zelle queda en 7. |
| Vistas | Reutilizar `pagos/pagar_int_*` con flag `$embebida` y `$post_pago_url`, sin duplicar markup. |
| POST | Solo `postPago` y `cancelar`; `prePago` y las pantallas de selección son GET. |
| `FormasPagoModel` | Fallback de orden, whitelist de tipo y filtros de activos/borrado lógico. |
| Render condicional | Ocultar familias vacías; si no hay ninguna, mensaje y volver. |
| Zelle | Usar su `postPayment()` existente; sin recibo ni GHL. |
| Persistencia del método | No persistir en `prePago`; se registra al procesar. |
| CSRF | No agregar en este cambio; registrar riesgo. |
| Acceso fuera de estado | Redirigir a `/paso-4` con flash explicativo. |
| Resultado del POST | Redirigir a `/paso-4` con flash de éxito o error. |
| Orquestador | Se agregan `preparar()` y `procesar()` con intención explícita; los métodos del portal regular se conservan sin cambios. |

## Riesgos y deuda técnica

- El cambio es amplio y se documenta en un solo plan. La implementación debe respetar las fases A, B y C para no mezclar catálogo, preparación y procesamiento en un mismo commit.
- No hay CSRF en el módulo. Los POST dependen de la sesión, el filtro y las validaciones de dominio; se recomienda abordar el endurecimiento CSRF en una tarea separada.
- No se prueba contra pasarelas reales ni sandbox. Las pruebas usan SQLite y dobles del orquestador; no cubren tiempos de espera, respuestas reales ni diferencias de driver.
- `pagomovilb` está en `rp` pero puede aprobar en 3. La copia de la familia debe hablar de "reportar o validar" para no prometer verificación manual en todos los casos.
- `PaymentOrchestrator::preparar()` tiene hoy una referencia a una excepción no importada; este cambio la corrige, pero conviene cubrirla con una prueba para evitar regresiones.
- El auto-routing puede exponer métodos públicos por URIs no previstas. Se mitiga con `sesionValida()` y validación de estado dentro de cada método.
- `actualizaStatus()` es legacy y puede registrar un intento con estado de error; no se rediseña en este cambio.
- La referencia de Zelle y la creación de intenciones concurrentes tienen condiciones de carrera preexistentes; no se abordan aquí.
- No se incluye recibo PDF, GHL ni Orbis; si el negocio los requiere, deben especificarse en otra feature.
- El cambio en `FormasPagoModel` también mejora el portal regular, que comparte el modelo; no se altera su contrato de salida.

## Preguntas abiertas

No quedan preguntas bloqueantes. Las decisiones de entrevista anteriores se registran como acuerdos. Si durante la implementación aparece una pasarela que no cumple el contrato de `vista`, `estatus` o `mensaje`, se debe detener la fase y actualizar este plan antes de continuar.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | Creación del plan FEAT-005 tras revisar `Paso3`, `NuevoIngresoPagoService`, `PaymentOrchestrator`, `PaymentService`, `FormasPagoModel`, las vistas de pasarela y la implementación de referencia del respaldo. Se acordó un solo documento con tres fases internas, todas las formas soportadas excepto `saldofavor`, vistas parametrizadas, POST solo para `postPago`/`cancelar`, sin CSRF, sin recibo y sin GHL. | opencode (agente) |
| 2026-10-28 | Ejecución en `p-feature/metodos-pago-en-linea-paso-4`. Se detectó que `PaymentOrchestrator` no tenía `preparar()`/`procesar()`; con autorización del usuario se agregaron como métodos nuevos, conservando `prePayment()`/`postPayment()` para el portal regular. Se ajustó la prueba existente del aviso `pagando` al enlace de métodos. | opencode (agente) |
