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 instrumentos). As regras do BACEN tornam o encerramento de conta um evento regulado, então a ordem importa. Bloqueie novos créditos primeiro, depois liquide a atividade pendente e devolva os fundos remanescentes. Desative os registros subjacentes por último. Este guia cobre o fluxo completo de encerramento, do Titular aos seus Instrumentos. Você pode executar o fluxo de duas formas. Via API fornece o endpoint, um payload de exemplo e a justificativa de compliance para cada etapa. Via Console fornece as mesmas etapas como ações de apontar e clicar no Console Midaz.
Siga as etapas na ordem. Não feche contas nem arquive registros de CRM antes de zerar os saldos. O 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 possuem as contas. Este guia abrevia os caminhos para /v1/.../accounts/{accountId} para facilitar a leitura.

​
Pré-requisitos

Antes de começar, confirme que você tem:
  • O holderId do cliente a ser desligado.
  • Os valores de accountId vinculados a esse Titular em cada Ledger da Organização. Recupere-os com GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts; a resposta é paginada, então recupere todas as páginas. Adicione o parâmetro de consulta opcional ledger_id apenas quando precisar restringir a lista a um único Ledger.
  • O instrument_id de cada Instrumento, mapeado ao accountId correspondente. Liste os instrumentos do Titular com GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id} (também paginado) e use o campo accountId de cada instrumento para mapeá-lo à Conta do Ledger. As Etapas 6 e 7 têm como alvo esses valores de instrument_id.
  • Confirmação da sua equipe de compliance de que você pode encerrar o relacionamento com o cliente (sem retenções legais, disputas em aberto ou exigências regulatórias pendentes).
  • Credenciais de API apropriadas com permissão para modificar titulares, instrumentos, saldos e contas. As Etapas 6 e 7 atualizam e excluem instrumentos, então as credenciais devem ter acesso patch e delete no recurso instruments.
O encerramento de conta é irreversível do ponto de vista do cliente. Antes de prosseguir, confirme que não há produtos ativos ou obrigações em aberto.

​
Via API

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

​
Etapa 1: Congelar 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 como 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: Bloquear 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. Recupere os saldos da conta:
Para cada balanceId retornado, bloqueie a entrada de fundos:
Repita esta etapa para todos os balanceId de todas as contas pertencentes ao Titular. Um único saldo deixado aberto ainda pode receber créditos e bloquear o encerramento mais tarde.
Quando você define allowReceiving como false, o saldo bloqueia novas entradas, mas continua permitindo saídas. É exatamente isso que você precisa na Etapa 4 para devolver o saldo remanescente ao cliente. Para detalhes sobre os flags de permissão, veja Saldos.

​
Etapa 3: Liquidar a atividade pendente

Antes de zerar um saldo, a conta não pode ter movimentações em andamento.
Se você pular esta etapa, uma conta encerrada pode receber lançamentos tardios. Lançamentos tardios quebram a conciliação e a trilha de auditoria do BACEN.

​
Etapa 4: Zerar o saldo

Devolva quaisquer fundos remanescentes ao cliente (o titular da conta) e confirme available = 0 e onHold = 0 em todos os saldos.
  • Registre uma transação de devolução que move o valor available remanescente 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 available = 0 e onHold = 0 em todos os saldos de todas as contas do Ledger antes de prosseguir. Você pode verificar isso com Recuperar saldos por conta.
O Midaz não permite excluir uma conta que ainda tenha saldo. Todos os saldos devem estar zerados antes da Etapa 5.

​
Etapa 5: Encerrar as Contas do Ledger no Midaz

Depois de zerar os saldos e liquidar a atividade pendente, exclua cada Conta do Ledger.
Uma solicitação bem-sucedida retorna 204 No Content. Repita para cada conta vinculada ao Titular. Veja Excluir uma conta para 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, sujeitas à sua política de retenção.

​
Etapa 6: Registrar a data de encerramento no instrumento

Registre a data oficial de encerramento no Instrumento do Titular para que o CRM e quaisquer exportações regulatórias reflitam quando o relacionamento terminou.
O campo closingDate fica no objeto bankingDetails do Instrumento e usa o formato YYYY-MM-DD. Veja Instrumentos para a referência completa dos campos. Os relatórios de ciclo de vida de conta do BACEN precisam de uma data de encerramento precisa.

​
Etapa 7: Arquivar os instrumentos no CRM

Arquive cada Instrumento no CRM. Use uma soft delete. Isso remove o registro do uso ativo, mas o mantém pelo período de retenção regulatória.
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. Veja Excluir um instrumento.

​
Etapa 8: Arquivar o Titular no CRM

Depois de arquivar todos os seus instrumentos, arquive o próprio Titular com uma 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. Veja Excluir um titular.

​
Via Console

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

​
Etapa 1: Congelar 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 Titulares, encontre o Titular a encerrar.
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
Confirme a atualização.
Marcar o Titular como inativo é uma mudança de registro, não uma exclusão. O registro permanece totalmente legível para auditoria. Isso não bloqueia novos créditos por si só: a Etapa 2 bloqueia as entradas no nível do saldo. Veja Editando um Titular.

​
Etapa 2: Bloquear créditos nas contas

Esta etapa exige a API. O Console não permite editar os flags de saldo depois que a conta é criada. O Console permite definir allowReceiving apenas ao criar uma Conta pela primeira vez, não ao editar um saldo existente. Use a API para desativar o recebimento em cada saldo.Siga a Etapa 2: Bloquear créditos nas contas na seção Via API.
Para cada conta vinculada ao Titular, use a API para definir allowReceiving como false em todos os balanceId. Isso bloqueia novas entradas enquanto as saídas permanecem disponíveis para a transação de devolução na Etapa 4.

​
Etapa 3: Liquidar a atividade pendente

Confirme que não há movimentações em andamento antes de zerar qualquer saldo.
1
Na página 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
Revise as transações pendentes e confirme ou cancele conforme apropriado.

​
Etapa 4: Zerar o saldo

Devolva os fundos remanescentes ao cliente e confirme available = 0 e onHold = 0 em todos os saldos.
1
Na página Transações, clique em Nova Transação. Crie uma transação de devolução que move o valor available remanescente de cada conta do cliente para o destino designado do titular, por exemplo, uma conta de liquidação externa. Veja Criando uma Transação.
2
Abra cada conta e confirme available = 0 e onHold = 0 antes de continuar.
O Midaz não permite excluir uma conta que ainda tenha saldo. Todos os saldos devem estar zerados antes da Etapa 5.

​
Etapa 5: Encerrar 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 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, sujeitas à sua política de retenção. Veja Excluindo uma Conta.

​
Etapa 6: Registrar a data de encerramento no instrumento

Registre a data oficial de encerramento no Instrumento do Titular para que o CRM e as exportações regulatórias reflitam quando o relacionamento terminou.
1
Na página Instrumentos, encontre o instrumento a atualizar, clique nos três pontos () na coluna Ações e selecione Editar.
2
No formulário do Instrumento, defina a Data de Encerramento (em bankingDetails) para a data oficial de encerramento usando o formato YYYY-MM-DD.
3
Confirme a atualização.
Os relatórios de ciclo de vida de conta do BACEN precisam de uma data de encerramento precisa. Veja Editando um Instrumento.

​
Etapa 7: Arquivar os instrumentos no CRM

Arquive cada Instrumento com uma soft delete. Isso remove o registro do uso ativo, mas o mantém pelo período de retenção regulatória.
1
Na página Instrumentos, encontre o instrumento a arquivar, 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 deploys regulados, o Midaz mantém o registro subjacente pelo período de retenção. Veja Excluindo um Instrumento.

​
Etapa 8: Arquivar o Titular no CRM

Depois de arquivar todos os seus instrumentos, arquive o próprio Titular com uma soft delete.
1
Na página Titulares, encontre o Titular a arquivar, 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. Veja Excluindo um Titular.

​
Notas de compliance do BACEN

  • A ordem é obrigatória. Congele primeiro (Etapas 1–2), depois liquide e zere (Etapas 3–4). Essa ordem impede 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 available = 0 e onHold = 0 antes de excluir uma conta. O Midaz bloqueia o encerramento de uma conta que possui fundos, e esse encerramento também violaria a compliance.
  • Arquive, não apague. Uma soft delete (sem hard_delete) mantém Titulares e instrumentos disponíveis pelo período de retenção regulatória. A exclusão permanente removeria evidências que as auditorias do BACEN precisam.
  • Registre a data de encerramento. O closingDate no instrumento fornece aos reguladores um registro de data e hora oficial de quando o relacionamento terminou.
  • Preserve a trilha de auditoria. O Midaz remove Contas do Ledger e 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 de compliance. Se qualquer etapa falhar, pause e resolva antes de continuar. Não deixe o cliente em um estado parcialmente encerrado.