Pular para o conteúdo principal
Encerrar a conta de um cliente no Midaz é um processo de várias etapas que abrange tanto o Ledger (contas e saldos) quanto o CRM (titulares e contas alias). Como o encerramento de contas é um evento regulado pelas regras do BACEN, a ordem das operações importa: você precisa interromper novos créditos, liquidar a atividade pendente, devolver os fundos restantes e só então desativar os registros subjacentes. Este guia percorre o fluxo de encerramento completo, desde o congelamento do Titular até o arquivamento de suas Contas Alias. Você pode executar o fluxo de duas formas: Via API, com o endpoint, um payload de exemplo e a justificativa de conformidade de cada etapa; ou Via Console, com as etapas equivalentes de apontar e clicar no Console do Midaz.
Siga as etapas na ordem. Encerrar contas ou arquivar registros do CRM antes de os saldos estarem zerados pode deixar fundos órfãos ou quebrar a trilha de auditoria exigida para os relatórios regulatórios.

​
Visão geral

O fluxo de encerramento tem oito etapas, agrupadas em três fases:
FaseEtapasObjetivo
1. Congelar1–2Interromper novas entradas tanto no nível do Titular quanto do Saldo.
2. Liquidar e zerar3–4Liquidar a atividade pendente e devolver os fundos restantes ao cliente.
3. Encerrar e arquivar5–8Desativar as Contas do Ledger e arquivar os registros do CRM sob a política de retenção.
Ao longo deste guia, {organization_id} e {ledger_id} identificam a Organização e o Ledger do Midaz que são donos das contas. Eles são abreviados como /v1/.../accounts/{accountId} para facilitar a leitura.

​
Pré-requisitos

Antes de começar, certifique-se de ter:
  • O holderId do cliente que está sendo 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 o relacionamento com o cliente pode ser encerrado (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. Confirme que não há produtos ativos, transações agendadas ou obrigações em aberto antes de prosseguir.

​
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

Desative o Titular para que nenhuma nova conta alias ou fluxo de trabalho posterior do CRM possa ser iniciado para o cliente. Esse é o primeiro sinal em toda a plataforma de que o relacionamento está sendo encerrado. 
PUT /v1/holders/{holderId}

{
  "status": "INACTIVE"
}
Congelar o Titular é uma mudança de estado lógica, não uma exclusão. O registro permanece totalmente legível para fins de auditoria e regulatórios.

​
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 e depois atualize cada saldo para desativar o recebimento. Obtenha os saldos da conta: 
GET /v1/.../accounts/{accountId}/balances
Para cada balanceId retornado, bloqueie os fundos de entrada: 
PATCH /v1/.../balances/{balanceId}

{
  "allowReceiving": false
}
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.
Definir allowReceiving como false bloqueia novas entradas, mas ainda permite saídas — que é exatamente o que você precisa para devolver o saldo restante ao cliente na Etapa 4. 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 não há transações pendentes ou não confirmadas na conta. 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 para que nenhuma nova entrada seja gerada após o início do encerramento.
Pular esta etapa pode fazer com que uma conta encerrada receba lançamentos atrasados, o que quebra 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

Com os saldos zerados e a atividade pendente liquidada, exclua cada Conta do Ledger. 
DELETE /v1/.../accounts/{accountId}
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. 
PATCH /v1/holders/{holderId}/aliases/{aliasId}

{
  "bankingDetails": {
    "closingDate": "2026-06-09"
  }
}
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. Definir uma data de encerramento precisa é obrigatório para os relatórios de ciclo de vida de contas do BACEN.

​
Etapa 7 — Arquive as contas alias no CRM

Arquive cada Conta Alias no CRM. Use um soft delete para que o registro seja removido do uso ativo, mas preservado durante o período de retenção regulatório. 
DELETE /v1/holders/{holderId}/aliases/{aliasId}
Não passe hard_delete=true. Um encerramento regulado exige que o registro seja arquivado (soft delete) e retido, não apagado permanentemente. Consulte Excluir uma conta alias.

​
Etapa 8 — Arquive o Titular no CRM

Por fim, arquive o próprio Titular com um soft delete depois que todas as suas contas alias tiverem sido arquivadas. 
DELETE /v1/holders/{holderId}
Como na Etapa 7, omita hard_delete=true. O registro do Titular deve ser retido 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 os saldos estarem zerados.

​
Etapa 1 — Congele o Titular

Defina o Titular como INACTIVE para que nenhuma nova conta alias ou fluxo de trabalho posterior do CRM possa começar para o cliente.
1
Na página de Titulares, encontre o Titular que você está desligando.
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.
Congelar o Titular é uma mudança de estado lógica, não uma exclusão. O registro permanece totalmente legível para fins de auditoria e regulatórios. 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 uma Conta é criada pela primeira vez, não ao editar 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, defina allowReceiving como false em cada balanceId via API para que novas entradas fiquem bloqueadas 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 e confirme que não há transações pendentes ou não confirmadas. Confirme ou cancele as que estiverem em andamento.
2
Cancele quaisquer transações recorrentes ou agendadas vinculadas à conta para que nenhuma nova entrada seja gerada 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 e 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

Com os saldos zerados e a atividade pendente liquidada, 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.
Uma data de encerramento precisa é obrigatória para os relatórios de ciclo de vida de contas do BACEN. Consulte Editar uma Conta Alias.

​
Etapa 7 — Arquive as contas alias no CRM

Arquive cada Conta Alias com um soft delete para que o registro seja removido do uso ativo, mas preservado 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) para que o registro seja arquivado e retido, não apagado permanentemente. Em implantações reguladas, o registro subjacente é mantido durante o período de retenção. Consulte Excluir uma Conta Alias.

​
Etapa 8 — Arquive o Titular no CRM

Depois que todas as suas contas alias estiverem arquivadas, 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. O registro do Titular deve ser retido 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. Congelar as entradas (Etapas 1–2) antes de liquidar e zerar (Etapas 3–4) evita que fundos entrem em uma conta que está em processo de encerramento.
  • Devolva os fundos antes de encerrar. Qualquer saldo residual deve ser devolvido ao cliente e confirmado em zero antes de uma conta ser excluída. Encerrar uma conta com fundos é bloqueado pelo Midaz e, além disso, não está em conformidade.
  • Arquive, não apague. Titulares e contas alias passam por soft delete (sem hard_delete) para que os registros permaneçam disponíveis durante o período de retenção regulatório. A exclusão permanente removeria evidências exigidas para as auditorias do BACEN.
  • 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. As Contas do Ledger e as operações são removidas logicamente e 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, em vez de deixar o cliente em um estado de encerramento parcial.