Documentação

Português

English
Español

Português

English
Español

Appearance

Gerenciar Saques ​

Pré-requisitos de acesso

  • Permissão (módulo): viewWithdrawals (para ver a listagem). As ações de aprovar/recusar exigem ainda os módulos approveWithdrawal e cancelWithdrawal.
  • Licença/Feature: WITHDRAWAL_HANDLING. A aba Banco Digital (saque fiduciário interno) só aparece quando a feature DIGITAL_BANKING também está habilitada.
  • Contêiner do menu: GERAL → grupo Operações

O que é / quando usar ​

Tela central de aprovação de saques solicitados pelos usuários. As solicitações são separadas por tipo de destino em abas: Fiduciário (FIAT — saque bancário externo), Banco Digital (INTERNAL_FIAT — transferência interna entre contas digitais) e Bitcoin/ETH (cripto on-chain). O operador revisa os dados da solicitação (conta destino, chave PIX, endereço de carteira e os campos customizados por token), aprova — o que dispara a saída efetiva do dinheiro — ou recusa, devolvendo o valor reservado.

Pré-condições ​

  • Permissão: viewWithdrawals para ver; approveWithdrawal / cancelWithdrawal para agir (permissão dupla — enum CPM + módulo dinâmico no DB).
  • Licença/Feature: WITHDRAWAL_HANDLING habilitada; DIGITAL_BANKING para a aba Banco Digital.
  • Dependências de outras telas: o usuário-alvo deve estar APPROVED (KYC) e ter saldo reservado. Saques de carteiras em estado de captação (IN_CAPTATION) ficam bloqueados pela própria reserva. Só é possível agir sobre solicitações em Aguardando.

Passo a passo ​

  1. Acesse o menu Operações → Gerenciar saques.
  2. Escolha a aba de destino: Fiduciário, Banco Digital ou Bitcoin/ETH (a aba selecionada é guardada na sessão).
  3. Filtre por status (Todos, Aprovado, Cancelado, Aguardando) e busque por nome.
  4. Clique no ícone de detalhes (info) para abrir o modal com todos os dados da solicitação, inclusive os campos customizados por token e valores sensíveis mascarados.
  5. Aprove para liberar o dinheiro ou recuse para devolver o valor à carteira. Confirme no bottom-sheet.

Filtros e colunas ​

Filtro/ColunaO que mostraOrigem do dado
Aba (tipo)FIAT / INTERNAL_FIAT / BTC-ETHtype da solicitação; aba persistida em MANAGE_WITHDRAWAL_TABLETYPE
BuscaFiltro local por nome do solicitantename
StatusAguardando / Aprovado / Cancelado / Todosstatus
DataData da solicitaçãowhen (ordenado DESC)
ID / IdentificadorID da solicitação e CPF/CNPJ/passaporteid / identifier (resolvido pelo userId)
ValorMontante solicitadoamount (BigNumber)
StatusEstado da solicitaçãostatus

Mostra: nome, valor + unidade, banco, agência, conta, chave PIX, identificador, status, data e a lista de campos customizados definidos pelo token. Campos marcados como secure aparecem mascarados (••••••); booleanos viram Sim/Não; datas são formatadas. Esses campos vêm do schema withdrawal_custom_fields do token e são revalidados no backend (tipo, regex, faixas, opções de select).

Ações e modais ​

  • Aprovar: bottom-sheet de confirmação → updateWithdrawal(id, 'APPROVED'). O backend (FMS – Withdrawal) executa a saída efetiva do dinheiro (transferência bancária, transferência interna ou broadcast on-chain conforme o tipo). A página recarrega.
  • Recusar: bottom-sheet → updateWithdrawal(id, 'CANCELLED'). Devolve o valor reservado à carteira do usuário.
  • Abrir usuário: navega para os detalhes do usuário pelo e-mail.
  • Guia de ajuda (auto_stories): abre o modal de troubleshooting da tela.

Regras de negócio / cuidados ​

Atenção

  • Aprovar/recusar só está disponível para solicitações em Aguardando.
  • A aba Banco Digital depende da feature DIGITAL_BANKING; sem ela, só Fiduciário e Bitcoin/ETH aparecem.
  • Confira os campos customizados (ex.: endereço de carteira externo, chave PIX) antes de aprovar — eles carregam o destino real do dinheiro.

Irreversível

  • Aprovar dispara a saída efetiva do dinheiro (transferência bancária / on-chain). Após confirmado, não há rollback — um envio on-chain ou uma transferência bancária não podem ser desfeitos pela plataforma.
  • Valores financeiros: tratados como BigNumber — sem arredondamento; conferir as casas decimais do token/moeda.
  • Idempotência: a liquidação do saque no FinLib é idempotente por externalId. Se o backend retornar E00021 "already processed" (ex.: retry após timeout/crash), o saque já foi processado — trate como sucesso, não reenvie.
  • Status APPROVED: o usuário-alvo precisa estar APPROVED.

Exemplos ​

Cenário 1 — Saque fiduciário (FIAT) via PIX para banco externo
  1. Aba Fiduciário, status Aguardando.
  2. Abra os detalhes e confira nome, valor, banco, agência, conta e chave PIX.
  3. Confronte o nome do titular com o do usuário (prevenção de saque para terceiros).
  4. Aprovar → o FMS aciona a transferência bancária externa. Resultado: status vira APPROVED, o valor sai da casa e a reserva é consumida.
Cenário 2 — Saque interno entre contas digitais (Banco Digital)
  1. Aba Banco Digital (requer DIGITAL_BANKING).
  2. O destino é outra conta digital do ecossistema — não há transferência bancária externa.
  3. Aprovar → o FMS faz a transferência interna INTERNAL_FIAT. Liquidação imediata, sem janela bancária.
Cenário 3 — Saque cripto (BTC/ETH) com endereço em campo customizado
  1. Aba Bitcoin/ETH.
  2. Nos detalhes, o endereço da carteira de destino aparece nos campos customizados definidos pelo token (validados por regex no schema do token).
  3. Verifique o endereço com cuidado — envio on-chain é definitivo.
  4. Aprovar → broadcast on-chain. Se houver retry e o backend devolver E00021, a transação já foi enviada; não reenvie.

Telas relacionadas ​