Pagamento em massa
Pré-requisitos de acesso
- Permissão (módulo):
executeMassPayment(necessária para criar, aprovar e cancelar; sem ela, a tela é apenas de consulta) - Licença/Feature: Nenhuma específica.
- Contêiner do menu: GERAL → grupo Investimentos / Distribuições Financeiras
O que é / quando usar
O Pagamento em massa permite ao administrador executar transferências de tokens em lote a partir de uma lista pré-configurada — eliminando intervenções manuais repetidas. Cada lote tem um título, uma lista de itens (carteira de destino, valor, token) e percorre um ciclo de vida com aprovação obrigatória e execução assíncrona por um scheduler.
Use-a para pagar muitos destinatários de uma vez: rendimentos, repasses, campanhas, folha em token etc. Os destinatários podem ser usuários cadastrados ou carteiras externas (sem user_id).
O ciclo é: criação (rascunho) → aprovação (libera execução) → execução (scheduler paga item a item, a cada 5 min) → finalizado (quando todos os itens foram pagos).
Pré-condições
- Permissão:
executeMassPayment(dupla — enum CPM no backend + módulo no DB). Os botões Criar (na lista) e Aprovar (no detalhe) só aparecem com ela. - Step-up / MFA: tanto a criação quanto a aprovação/cancelamento exigem um código MFA (autenticação adicional). Sem o código, a operação não é enviada.
- Dependências: os tokens usados precisam estar cadastrados (a tela valida cada item contra a lista de tokens e a rede da carteira).
Passo a passo
- Acesse Investimentos → Pagamento em massa (rota
/mass-payment). - Clique em Criar para abrir o modal.
- Escolha o método: Manual (preencher item a item) ou Upload (CSV com colunas
wallet,amount,token). - Informe o título do lote e revise os itens (carteira, valor, token). O sistema valida cada item.
- Confirme — será solicitado o código MFA. O lote é salvo em
waiting_approval, com todos os itens emwaiting_processment. Nada é pago ainda. - Abra os detalhes do lote e clique em Aprovar (exige confirmação + MFA novamente). O status vira
approvede o lote entra na fila do scheduler. - O scheduler executa a cada 5 minutos: paga os itens, marca cada um como
paid(oufailed, com retry no ciclo seguinte). Quando todos estão pagos, o lote virafinished.
Campos (modal de criação)
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
| Título | Nome do lote de pagamento | Sim | title do mass_payment (até 100 caracteres) |
| Método | Manual ou Upload (CSV) | Sim | Define como os itens são montados; o CSV exige colunas wallet, amount/value, token |
| Carteira (item) | Endereço de destino | Sim | wallet do mass_payment_item; validada conforme a rede do token (BTC/TRON/Solana/EVM); pode ser carteira externa |
| Valor (item) | Quantia a transferir | Sim | amount; deve ser > 0 (BigNumber) |
| Token (item) | Token/moeda do pagamento | Sim | unit_of_money; validado contra a lista de tokens cadastrados (tokenValid) |
| Código MFA | Código de autenticação adicional | Sim | mfaCode enviado a createMassPayment; sem ele a criação não ocorre |
A confirmação só é habilitada quando o título está preenchido e todos os itens têm token válido, valor > 0 e carteira válida para a rede.
Filtros e colunas (listagem)
| Filtro / Coluna | O que mostra | Origem do dado |
|---|---|---|
| Busca por título | Filtra os lotes pelo título | title |
| Ordem | Mais novos / mais antigos | order (DESC/ASC) |
| Status | waiting_approval, approved, canceled, finished | status |
| Token | Filtra por token (unidade de pagamento) | unitOfMoney |
| Data | Data de criação do lote | createdAt |
| Título (coluna) | Nome do lote | title |
| Status (coluna) | Estado atual; approved/finished em verde, canceled em vermelho | status |
Ações e modais
- Criar: abre o modal (Manual/Upload). Valida os itens e, mediante MFA, chama
createMassPayment. Salva emwaiting_approval. - Baixar CSV de exemplo: gera um modelo com as colunas
wallet,amount,token. - Ver detalhes: abre o lote com o resumo dos itens (total, aguardando, pagos, falhos, cancelados) e o estado de cada item.
- Aprovar (no detalhe): disponível apenas em
waiting_approval. Abre um alerta de confirmação e, em seguida, pede o MFA; chamaupdateMassPaymentStatus(..., APPROVED, mfaCode). Libera para o scheduler. - Cancelar (no detalhe): pede MFA e chama
updateMassPaymentStatus(..., CANCELED, mfaCode). Nenhum pagamento é executado para um lote cancelado.
Regras de negócio / cuidados
Atenção
- Lista vazia é bloqueada — não é possível confirmar um lote sem itens.
- O CSV inválido (colunas faltando, sem linhas) é rejeitado com mensagem de erro; corrija o cabeçalho (
wallet,amount/value,token) e reenvie. - A carteira é validada pela rede do token: BTC, TRON, Solana e EVM (Ethereum e compatíveis) têm validações diferentes. Carteira inválida para a rede bloqueia a confirmação.
- O lote não vira
finishedenquanto houver itens pendentes; itensfailedsão reprocessados no próximo ciclo do scheduler.
Irreversível
- A aprovação libera pagamentos reais aos destinatários. Após
approved, o scheduler executa as transferências automaticamente — revise a lista antes de aprovar. - O MFA é obrigatório em criação, aprovação e cancelamento (step-up): é a barreira de segurança contra execução indevida de lote.
- Valores financeiros: os valores são tratados como BigNumber — sem arredondamento; valores ≤ 0 são rejeitados.
- Idempotência / retry: a execução é por item; um item que falha é retentado no ciclo seguinte (a cada 5 min) sem reexecutar os já pagos. No FIN, transferências repetidas protegidas por
externalIdretornamE00021("already processed"), que significa sucesso (já pago), não falha. - Carteiras externas: itens podem ter apenas
wallet(semuser_id) — o pagamento a carteira externa/não cadastrada é suportado.
Exemplos
Cenário 1 — Repasse manual a poucos beneficiários
Você precisa pagar 5 parceiros em USDC. Clique em Criar → Manual, adicione 5 itens (carteira EVM + valor + USDC), dê um título ("Repasse parceiros - junho"), confirme e informe o MFA. O lote nasce em waiting_approval. Abra os detalhes, Aprove (MFA de novo). Em até 5 min o scheduler paga os itens; quando todos ficam paid, o lote vira finished.
Cenário 2 — Folha em token via upload de CSV
Para pagar dezenas de colaboradores, baixe o CSV de exemplo, preencha as colunas wallet, amount, token e faça o Upload. O sistema pré-visualiza os itens e valida cada carteira pela rede do token. Dê o título, confirme com MFA. Revise no detalhe e Aprove. Um item com carteira inválida bloqueia a confirmação — corrija antes de prosseguir.
Cenário 3 — Pagamento a carteira externa + tratamento de falha
Um dos beneficiários é uma carteira externa (não tem conta na plataforma): basta informar o endereço, sem user_id. Após aprovar, se a transferência de um item falhar (ex.: erro transitório na rede), o item fica failed e é reprocessado automaticamente no próximo ciclo de 5 min; os demais itens já pagos não são reexecutados. O lote só fecha (finished) quando todos os itens forem paid.