Skip to main content
Para encerrar a conta de um cliente no Midaz, você trabalha em duas áreas: o Ledger (contas e saldos) e o CRM (titulares e contas alias). As regras do BACEN tornam o encerramento de contas um evento regulado, então a ordem importa. Interrompa primeiro os novos créditos, depois liquide a atividade pendente e devolva os fundos restantes. Desative os registros subjacentes por último. Este guia cobre o fluxo de encerramento completo, do Titular até suas Contas Alias. Você pode executar o fluxo de duas formas. Via API dá a você o endpoint, um payload de exemplo e a justificativa de conformidade de cada etapa. Via Console dá a você as mesmas etapas como ações de apontar e clicar no Console do Midaz.
Siga as etapas na ordem. Não encerre contas nem arquive registros do CRM antes de zerar os saldos. Um encerramento antecipado pode deixar fundos órfãos ou quebrar a trilha de auditoria que os relatórios regulatórios exigem.

​
Visão geral

O fluxo de encerramento tem oito etapas, agrupadas em três fases:
Ao longo deste guia, {organization_id} e {ledger_id} identificam a Organização e o Ledger do Midaz que são donos das contas. Este guia abrevia os caminhos como /v1/.../accounts/{accountId} para facilitar a leitura.

​
Pré-requisitos

Antes de começar, certifique-se de ter:
  • O holderId do cliente a ser desligado.
  • A lista de valores de accountId vinculados a esse Titular no Ledger (obtenha-os a partir das Contas Alias do Titular).
  • A confirmação da sua equipe de conformidade de que você pode encerrar o relacionamento com o cliente (sem bloqueios legais, disputas abertas ou requisitos regulatórios pendentes).
  • Credenciais de API apropriadas com permissão para modificar titulares, saldos e contas.
O encerramento de contas é irreversível do ponto de vista do cliente. Antes de prosseguir, confirme que não há produtos ativos, transações agendadas ou obrigações em aberto.

​
Via API

Execute o fluxo de encerramento completo de forma programática. Cada etapa lista o endpoint, um payload de exemplo e a justificativa de conformidade.

​
Etapa 1 — Congele o Titular

Marque o Titular como inativo para registrar o encerramento em todos os seus sistemas. Atualize o Titular e defina o campo status do seu perfil de pessoa com um valor inativo.
Marcar o Titular como inativo é uma mudança de registro, não uma exclusão. O registro do Titular permanece totalmente legível para auditoria. Esse status não bloqueia novos créditos por si só — a Etapa 2 bloqueia as entradas no nível do saldo. Para uma pessoa jurídica, defina legalPerson.status em vez disso.

​
Etapa 2 — Bloqueie os créditos nas contas

Para cada conta vinculada ao Titular, impeça a entrada de novos fundos. Primeiro, liste os Saldos da conta. Depois atualize cada saldo para desativar o recebimento. Obtenha os saldos da conta:
Para cada balanceId retornado, bloqueie os fundos de entrada:
Repita esta etapa para cada balanceId de cada conta pertencente ao Titular. Um único saldo deixado em aberto ainda pode receber créditos e bloquear o encerramento mais adiante.
Quando você define allowReceiving como false, o saldo bloqueia novas entradas, mas ainda permite saídas. Isso é exatamente o que você precisa na Etapa 4 para devolver o saldo restante ao cliente. Para mais detalhes sobre os flags de permissão, consulte Saldos.

​
Etapa 3 — Liquide a atividade pendente

Antes de poder zerar um saldo, a conta não pode ter movimentações em andamento.
  • Verifique as transações em processamento. Confirme que a conta não tem transações pendentes ou não confirmadas. Confirme-as ou cancele-as conforme apropriado usando Confirmar uma transação pendente ou Cancelar uma transação pendente.
  • Cancele os agendamentos ativos. Cancele quaisquer transações recorrentes ou agendadas vinculadas à conta. Isso interrompe novas entradas após o início do encerramento.
Se você pular esta etapa, uma conta encerrada pode receber lançamentos atrasados. Lançamentos atrasados quebram a conciliação e a trilha de auditoria do BACEN.

​
Etapa 4 — Zere o saldo

Devolva os fundos restantes ao cliente (o titular da conta) e confirme que cada saldo chega a zero.
  • Registre uma transação de devolução que mova o valor available restante de cada conta do cliente para o destino designado do titular (por exemplo, uma conta de liquidação externa). Use Criar uma transação.
  • Confirme que available = 0 em cada saldo de cada conta do Ledger antes de prosseguir. Você pode verificar isso com Obter saldos por conta.
O Midaz não permite excluir uma conta que ainda mantém saldo. Todos os saldos devem estar zerados antes da Etapa 5.

​
Etapa 5 — Encerre as Contas do Ledger no Midaz

Depois de zerar os saldos e liquidar a atividade pendente, exclua cada Conta do Ledger.
Uma requisição bem-sucedida retorna 204 No Content. Repita para cada conta vinculada ao Titular. Consulte Excluir uma conta para ver o contrato completo.
Excluir uma Conta do Ledger é uma remoção lógica. A conta e suas operações históricas permanecem disponíveis para auditoria e relatórios, sujeito à sua política de retenção.

​
Etapa 6 — Registre a data de encerramento no alias

Registre a data oficial de encerramento na Conta Alias do Titular para que o CRM e quaisquer exportações regulatórias reflitam quando o relacionamento terminou.
O campo closingDate fica no objeto bankingDetails da Conta Alias e usa o formato YYYY-MM-DD. Consulte Contas Alias para ver a referência completa de campos. Os relatórios de ciclo de vida de contas do BACEN exigem uma data de encerramento precisa.

​
Etapa 7 — Arquive as contas alias no CRM

Arquive cada Conta Alias no CRM. Use um soft delete. Ele remove o registro do uso ativo, mas o mantém durante o período de retenção regulatório.
Não passe hard_delete=true. Um encerramento regulado deve arquivar (soft delete) o registro e mantê-lo. Ele não deve apagar o registro permanentemente. Consulte Excluir uma conta alias.

​
Etapa 8 — Arquive o Titular no CRM

Depois de arquivar todas as suas contas alias, arquive o próprio Titular com um soft delete.
Como na Etapa 7, omita hard_delete=true. Mantenha o registro do Titular sob a política de retenção aplicável para auditoria e inspeção regulatória. Consulte Excluir um titular.

​
Via Console

Execute o mesmo fluxo de encerramento de oito etapas a partir do Console do Midaz. O Console cobre a maior parte do fluxo por apontar e clicar, mas duas etapas — bloquear créditos (Etapa 2) e cancelar transações agendadas (Etapa 3) — ainda exigem a API. Cada etapa abaixo indica a etapa de API equivalente nesta página.
A ordem é a mesma do fluxo de API. Não exclua contas nem arquive registros do CRM antes de zerar os saldos.

​
Etapa 1 — Congele o Titular

Marque o Titular como inativo para registrar o encerramento. Isso é uma mudança de registro e não bloqueia novos créditos por si só.
1
Na página de Titulares, encontre o Titular a ser encerrado.
2
Clique nos três pontos () na coluna Ações e selecione Editar.
3
No formulário do Titular, defina o Status como Inativo.
4
Clique em Salvar.
Marcar o Titular como inativo é uma mudança de registro, não uma exclusão. O registro permanece totalmente legível para auditoria. Não bloqueia novos créditos por si só — a Etapa 2 bloqueia as entradas no nível do saldo. Consulte Editar um Titular.

​
Etapa 2 — Bloqueie os créditos nas contas

Esta etapa requer a API. O Console não permite editar os flags de saldo após a criação da conta. O Console só permite definir allowReceiving quando você cria uma Conta pela primeira vez, não quando você edita um saldo existente. Use a API para desativar o recebimento em cada saldo.Siga a Etapa 2 — Bloqueie os créditos nas contas na seção Via API.
Para cada conta vinculada ao Titular, use a API para definir allowReceiving como false em cada balanceId. Isso bloqueia novas entradas enquanto as saídas permanecem disponíveis para a transação de devolução da Etapa 4.

​
Etapa 3 — Liquide a atividade pendente

Confirme que não há movimentações em andamento antes de zerar qualquer saldo.
1
Na página de Transações, filtre pelas contas vinculadas ao Titular. Confirme que a conta não tem transações pendentes ou não confirmadas, e confirme ou cancele as que estiverem em andamento.
2
Cancele quaisquer transações recorrentes ou agendadas vinculadas à conta. Isso interrompe novas entradas após o início do encerramento.
As transações agendadas exigem a API. O Console permite visualizar e cancelar transações individuais, mas não oferece o gerenciamento de transações agendadas (recorrentes). Use a API para cancelar os agendamentos ativos — consulte a Etapa 3 — Liquide a atividade pendente na seção Via API.

​
Etapa 4 — Zere o saldo

Devolva os fundos restantes ao cliente e confirme que cada saldo chega a zero.
1
Na página de Transações, clique em Nova Transação. Crie uma transação de devolução que mova o valor available restante de cada conta do cliente para o destino designado do titular, por exemplo uma conta de liquidação externa. Consulte Criar uma Transação.
2
Abra cada conta e confirme que o saldo available é 0 antes de continuar.
O Midaz não permite excluir uma conta que ainda mantém saldo. Todos os saldos devem estar zerados antes da Etapa 5.

​
Etapa 5 — Encerre as Contas do Ledger no Midaz

Depois de zerar os saldos e liquidar a atividade pendente, exclua cada Conta do Ledger.
1
Na página de Contas, encontre a Conta vinculada ao Titular, clique nos três pontos () na coluna Ações e selecione Excluir.
2
Uma caixa de diálogo de confirmação aparecerá. Clique em Confirmar para finalizar a exclusão.
3
Repita para cada conta vinculada ao Titular.
Excluir uma Conta do Ledger é uma remoção lógica. A conta e suas operações históricas permanecem disponíveis para auditoria e relatórios, sujeito à sua política de retenção. Consulte Excluir uma Conta.

​
Etapa 6 — Registre a data de encerramento no alias

Registre a data oficial de encerramento na Conta Alias do Titular para que o CRM e as exportações regulatórias reflitam quando o relacionamento terminou.
1
Na página de Contas Alias, encontre a conta alias a ser atualizada, clique nos três pontos () na coluna Ações e selecione Editar.
2
No formulário da Conta Alias, defina a Data de Encerramento (em bankingDetails) como a data oficial de encerramento usando o formato YYYY-MM-DD.
3
Clique em Salvar.
Os relatórios de ciclo de vida de contas do BACEN exigem uma data de encerramento precisa. Consulte Editar uma Conta Alias.

​
Etapa 7 — Arquive as contas alias no CRM

Arquive cada Conta Alias com um soft delete. Ele remove o registro do uso ativo, mas o mantém durante o período de retenção regulatório.
1
Na página de Contas Alias, encontre a conta alias a ser arquivada, clique nos três pontos () na coluna Ações e selecione Excluir.
2
Uma caixa de diálogo de confirmação aparecerá. Clique em Confirmar para finalizar.
Use a exclusão padrão (soft delete). Ela arquiva e mantém o registro em vez de apagá-lo permanentemente. Em implantações reguladas, o Midaz mantém o registro subjacente durante o período de retenção. Consulte Excluir uma Conta Alias.

​
Etapa 8 — Arquive o Titular no CRM

Depois de arquivar todas as suas contas alias, arquive o próprio Titular com um soft delete.
1
Na página de Titulares, encontre o Titular a ser arquivado, clique nos três pontos () na coluna Ações e selecione Excluir.
2
Uma caixa de diálogo de confirmação aparecerá. Clique em Confirmar para finalizar.
Use Soft Delete (o padrão), não Hard Delete. Mantenha o registro do Titular sob a política de retenção aplicável para auditoria e inspeção regulatória. Consulte Excluir um Titular.

​
Notas de conformidade do BACEN

  • A ordem é obrigatória. Congele primeiro (Etapas 1–2), depois liquide e zere (Etapas 3–4). Essa ordem evita que fundos entrem em uma conta que está em processo de encerramento.
  • Devolva os fundos antes de encerrar. Devolva qualquer saldo residual ao cliente e confirme-o em zero antes de excluir uma conta. O Midaz bloqueia o encerramento de uma conta que mantém fundos, e esse encerramento também violaria a conformidade.
  • Arquive, não apague. Um soft delete (sem hard_delete) mantém titulares e contas alias disponíveis durante o período de retenção regulatório. A exclusão permanente removeria evidências que as auditorias do BACEN exigem.
  • Registre a data de encerramento. O closingDate no alias dá aos reguladores um carimbo de data/hora autoritativo de quando o relacionamento terminou.
  • Preserve a trilha de auditoria. O Midaz remove as Contas do Ledger e as operações de forma lógica. Elas permanecem consultáveis para conciliação e relatórios.
Trate as oito etapas como uma única transação do ponto de vista da conformidade. Se alguma etapa falhar, pause e resolva-a antes de continuar. Não deixe o cliente em um estado de encerramento parcial.