Pago masivo

Requisitos previos de acceso

• Permiso (módulo): executeMassPayment (necesario para crear, aprobar y cancelar; sin él, la pantalla es solo de consulta)
• Licencia/Feature: Ninguna específica.
• Contenedor del menú: GENERAL → grupo Inversiones / Distribuciones Financieras

Qué es / cuándo usar

El Pago masivo permite al administrador ejecutar transferencias de tokens en lote a partir de una lista preconfigurada — eliminando intervenciones manuales repetidas. Cada lote tiene un título, una lista de ítems (billetera de destino, valor, token) y recorre un ciclo de vida con aprobación obligatoria y ejecución asíncrona por un scheduler.

Úselo para pagar a muchos destinatarios a la vez: rendimientos, traspasos, campañas, nómina en token, etc. Los destinatarios pueden ser usuarios registrados o billeteras externas (sin user_id).

El ciclo es: creación (borrador) → aprobación (habilita la ejecución) → ejecución (el scheduler paga ítem a ítem, cada 5 min) → finalizado (cuando todos los ítems han sido pagados).

Requisitos previos

• Permiso: executeMassPayment (doble — enum CPM en el backend + módulo en la BD). Los botones Crear (en la lista) y Aprobar (en el detalle) solo aparecen con él.
• Step-up / MFA: tanto la creación como la aprobación/cancelación requieren un código MFA (autenticación adicional). Sin el código, la operación no se envía.
• Dependencias: los tokens utilizados deben estar registrados (la pantalla valida cada ítem contra la lista de tokens y la red de la billetera).

Paso a paso

1. Acceda a Inversiones → Pago masivo (ruta /mass-payment).
2. Haga clic en Crear para abrir el modal.
3. Elija el método: Manual (completar ítem a ítem) o Upload (CSV con columnas wallet, amount, token).
4. Ingrese el título del lote y revise los ítems (billetera, valor, token). El sistema valida cada ítem.
5. Confirme — se solicitará el código MFA. El lote se guarda en waiting_approval, con todos los ítems en waiting_processment. Aún no se paga nada.
6. Abra los detalles del lote y haga clic en Aprobar (requiere confirmación + MFA nuevamente). El estado pasa a approved y el lote entra en la cola del scheduler.
7. El scheduler se ejecuta cada 5 minutos: paga los ítems, marca cada uno como paid (o failed, con reintento en el ciclo siguiente). Cuando todos están pagados, el lote pasa a finished.

Campos (modal de creación)

Campo	Descripción	¿Obligatorio?	Efecto en el sistema/backend
Título	Nombre del lote de pago	Sí	title del mass_payment (hasta 100 caracteres)
Método	Manual o Upload (CSV)	Sí	Define cómo se ensamblan los ítems; el CSV requiere columnas wallet, amount/value, token
Billetera (ítem)	Dirección de destino	Sí	wallet del mass_payment_item; validada según la red del token (BTC/TRON/Solana/EVM); puede ser una billetera externa
Valor (ítem)	Cantidad a transferir	Sí	amount; debe ser > 0 (BigNumber)
Token (ítem)	Token/moneda del pago	Sí	unit_of_money; validado contra la lista de tokens registrados (tokenValid)
Código MFA	Código de autenticación adicional	Sí	mfaCode enviado a createMassPayment; sin él la creación no se realiza

La confirmación solo se habilita cuando el título está completado y todos los ítems tienen token válido, valor > 0 y billetera válida para la red.

Filtros y columnas (listado)

Filtro / Columna	Qué muestra	Origen del dato
Búsqueda por título	Filtra los lotes por título	title
Orden	Más nuevos / más antiguos	order (DESC/ASC)
Estado	waiting_approval, approved, canceled, finished	status
Token	Filtra por token (unidad de pago)	unitOfMoney
Fecha	Fecha de creación del lote	createdAt
Título (columna)	Nombre del lote	title
Estado (columna)	Estado actual; approved/finished en verde, canceled en rojo	status

Acciones y modales

• Crear: abre el modal (Manual/Upload). Valida los ítems y, mediante MFA, llama a createMassPayment. Se guarda en waiting_approval.
• Descargar CSV de ejemplo: genera una plantilla con las columnas wallet, amount, token.
• Ver detalles: abre el lote con el resumen de ítems (total, pendientes, pagados, fallidos, cancelados) y el estado de cada ítem.
• Aprobar (en el detalle): disponible solo en waiting_approval. Abre una alerta de confirmación y luego solicita el MFA; llama a updateMassPaymentStatus(..., APPROVED, mfaCode). Habilita para el scheduler.
• Cancelar (en el detalle): solicita MFA y llama a updateMassPaymentStatus(..., CANCELED, mfaCode). No se ejecuta ningún pago para un lote cancelado.

Reglas de negocio / precauciones

Atención

• La lista vacía está bloqueada — no es posible confirmar un lote sin ítems.
• Un CSV inválido (columnas faltantes, sin filas) es rechazado con mensaje de error; corrija el encabezado (wallet, amount/value, token) y reenvíe.
• La billetera se valida por la red del token: BTC, TRON, Solana y EVM (Ethereum y compatibles) tienen validaciones distintas. Una billetera inválida para la red bloquea la confirmación.
• El lote no pasa a finished mientras haya ítems pendientes; los ítems failed son reprocesados en el próximo ciclo del scheduler.

Irreversible

• La aprobación libera pagos reales a los destinatarios. Tras approved, el scheduler ejecuta las transferencias automáticamente — revise la lista antes de aprobar.
• El MFA es obligatorio en creación, aprobación y cancelación (step-up): es la barrera de seguridad contra la ejecución indebida de lotes.

• Valores financieros: los valores se tratan como BigNumber — sin redondeo; los valores ≤ 0 son rechazados.
• Idempotencia / reintento: la ejecución es por ítem; un ítem que falla se reintenta en el ciclo siguiente (cada 5 min) sin re-ejecutar los ya pagados. En FIN, las transferencias repetidas protegidas por externalId retornan E00021 ("already processed"), que significa éxito (ya pagado), no falla.
• Billeteras externas: los ítems pueden tener solo wallet (sin user_id) — el pago a billetera externa/no registrada está soportado.

Ejemplos

Escenario 1 — Desembolso manual a pocos beneficiarios

Necesita pagar a 5 socios en USDC. Haga clic en Crear → Manual, agregue 5 ítems (billetera EVM + valor + USDC), asigne un título ("Desembolso socios - junio"), confirme e ingrese el MFA. El lote se crea en waiting_approval. Abra los detalles, Apruebe (MFA nuevamente). En hasta 5 min el scheduler paga los ítems; cuando todos quedan paid, el lote pasa a finished.

Escenario 2 — Nómina en token mediante carga de CSV

Para pagar a decenas de colaboradores, descargue el CSV de ejemplo, complete las columnas wallet, amount, token y haga el Upload. El sistema previsualiza los ítems y valida cada billetera según la red del token. Asigne el título, confirme con MFA. Revise en el detalle y Apruebe. Un ítem con billetera inválida bloquea la confirmación — corrija antes de continuar.

Escenario 3 — Pago a billetera externa + gestión de fallo

Uno de los beneficiarios tiene una billetera externa (sin cuenta en la plataforma): basta ingresar la dirección, sin user_id. Tras aprobar, si la transferencia de un ítem falla (ej.: error transitorio en la red), el ítem queda failed y se reprocesa automáticamente en el próximo ciclo de 5 min; los demás ítems ya pagados no se re-ejecutan. El lote solo cierra (finished) cuando todos los ítems estén paid.

Pantallas relacionadas

• Distribución
• Solicitudes de Préstamos
• Financiero