Pular para o conteúdo principal
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. Em seguida, encerre cada conta. A operação de encerramento recusa uma conta que ainda tem fundos. Arquive os registros de CRM 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 arquive registros de CRM antes de encerrar as contas.

​
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} e /v2/.../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. A Etapa 5 tem 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. A Etapa 5 atualiza instrumentos, então as credenciais devem ter acesso patch no recurso instruments. As Etapas 6 e 7 exigem acesso post e delete no recurso accounts.
O encerramento de uma conta não pode ser desfeito. 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. Se um saldo tiver overdraftUsed diferente de zero, quite-o antes: um saldo que recusa entradas também recusa o pagamento. 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.
A operação de encerramento da Etapa 6 recusa uma conta cujos fundos uma transação pendente ainda retém.

​
Etapa 4: Zerar o saldo

Devolva quaisquer fundos remanescentes ao cliente (o titular da conta) e confirme available = 0, onHold = 0 e overdraftUsed = 0 em todos os saldos.
  • Se um saldo deve dívida de tarifa, liquide-a antes com Cobrar dívidas de tarifa em aberto. A operação de encerramento recusa um saldo que deve dívida de tarifa (0527).
  • 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, onHold = 0 e overdraftUsed = 0 em todos os saldos de todas as contas do Ledger antes de prosseguir. Você pode verificar isso com Recuperar saldos por conta.
A operação de encerramento recusa uma conta com qualquer saldo cujo valor available, onHold ou overdraftUsed não seja exatamente zero.

​
Etapa 5: 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. Faça isso antes de excluir a conta na Etapa 7. Depois da exclusão, o Midaz responde a uma atualização do Instrumento com não encontrado.
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 6: Encerrar as Contas do Ledger no Midaz

Depois de zerar os saldos e liquidar a atividade pendente, encerre cada Conta do Ledger.
A requisição não tem corpo. Uma requisição bem-sucedida retorna 204 No Content, e cada leitura posterior da conta mostra o instante do encerramento em closedAt. Repita para cada conta vinculada ao Titular. Veja Encerrar uma conta para o contrato completo e a lista de erros do Midaz para cada recusa.
O Midaz recusa qualquer movimentação posterior em uma conta encerrada, e desbloquear a conta não a reabre. Uma conta externa não pode ser encerrada.

​
Etapa 7: Excluir as Contas do Ledger

Exclua cada conta encerrada. A exclusão também arquiva (soft-delete) todos os Instrumentos vinculados à conta.
A Etapa 8 recusa arquivar um Titular que ainda possui uma conta não excluída. Veja Excluir uma conta.
Excluir uma conta é uma remoção lógica. Suas transações permanecem disponíveis para auditoria e relatórios.

​
Etapa 8: Arquivar o Titular no CRM

Depois de excluir todas as suas contas, arquive o próprio Titular com uma soft delete.
Não passe 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) e o encerramento das contas (Etapa 6) exigem a API. Cada etapa abaixo indica a etapa equivalente da API nesta página.
A ordem é a mesma do fluxo da API. Não arquive registros de CRM antes de encerrar as contas.

​
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. Quite qualquer overdraftUsed diferente de zero antes desta etapa.

​
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, onHold = 0 e overdraftUsed = 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, onHold = 0 e overdraftUsed = 0 antes de continuar.
A operação de encerramento recusa uma conta com qualquer saldo cujo valor available, onHold ou overdraftUsed não seja exatamente zero.

​
Etapa 5: 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. Faça isso antes de excluir a conta na Etapa 7.
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 6: Encerrar as Contas do Ledger no Midaz

O encerramento exige a API. Siga a Etapa 6: Encerrar as Contas do Ledger no Midaz na seção Via API.

​
Etapa 7: Excluir as Contas do Ledger

Exclua cada conta encerrada. A exclusão também arquiva todos os Instrumentos vinculados à conta.
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.
Veja Excluindo uma Conta.

​
Etapa 8: Arquivar o Titular no CRM

Depois de excluir todas as suas contas, 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 antes de encerrar uma conta. A operação de encerramento recusa uma conta que possui fundos.
  • 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. As operações de uma conta excluída 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.