> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Closing a customer account
> End-to-end flow on how to close a customer account in line with BACEN account-closure rules.
Closing a customer account in Midaz is a multi-step process that spans both the **Ledger** (accounts and balances) and **CRM** (holders and alias accounts). Because account closure is a regulated event under BACEN rules, the order of operations matters: you must stop new credits, settle pending activity, return any remaining funds, and only then deactivate the underlying records.
This guide walks through the complete closure flow, from freezing the [Holder](/en/midaz/crm/holders) to archiving its [Alias Accounts](/en/midaz/crm/alias-accounts). You can run the flow two ways: **[Via API](#via-api)**, with the endpoint, an example payload, and the compliance rationale for each step; or **[Via Console](#via-console)**, with the equivalent point-and-click steps in the Midaz Console.
Follow the steps in order. Closing accounts or archiving CRM records before balances are zeroed can leave orphaned funds or break the audit trail required for regulatory reporting.
## Overview
***
The closure flow has eight steps, grouped into three phases:
| Phase | Steps | Goal |
| :----------------------- | :---- | :------------------------------------------------------------------------- |
| **1. Freeze** | 1–2 | Stop new inflows at both the Holder and Balance level. |
| **2. Settle and zero** | 3–4 | Clear pending activity and return remaining funds to the customer. |
| **3. Close and archive** | 5–8 | Deactivate Ledger Accounts and archive CRM records under retention policy. |
Throughout this guide, `{organization_id}` and `{ledger_id}` identify the Midaz Organization and Ledger that own the accounts. They are abbreviated as `/v1/.../accounts/{accountId}` for readability.
## Prerequisites
***
Before starting, make sure you have:
* The `holderId` of the customer being offboarded.
* The list of `accountId` values linked to that Holder across the Ledger (retrieve them from the Holder's [Alias Accounts](/en/midaz/crm/alias-accounts)).
* Confirmation from your compliance team that the customer relationship can be terminated (no legal holds, open disputes, or pending regulatory requirements).
* Appropriate API credentials with permission to modify holders, balances, and accounts.
Account closure is irreversible from the customer's perspective. Confirm there are no active products, scheduled transactions, or open obligations before proceeding.
## Via API
***
Run the full closure flow programmatically. Each step lists the endpoint, an example payload, and the compliance rationale.
### Step 1 — Freeze the Holder
Deactivate the Holder so that no new alias accounts or downstream CRM workflows can be initiated for the customer. This is the first signal across the platform that the relationship is being closed.
```http theme={null}
PUT /v1/holders/{holderId}
```
```json theme={null}
{
"status": "INACTIVE"
}
```
Freezing the Holder is a logical state change, not a deletion. The record remains fully readable for audit and regulatory purposes.
### Step 2 — Block credits on the accounts
For each account linked to the Holder, prevent new funds from entering. First, list the [Balances](/en/midaz/balances) of the account, then update each balance to disable receiving.
**Retrieve the account balances:**
```http theme={null}
GET /v1/.../accounts/{accountId}/balances
```
**For each `balanceId` returned, block incoming funds:**
```http theme={null}
PATCH /v1/.../balances/{balanceId}
```
```json theme={null}
{
"allowReceiving": false
}
```
Repeat this step for **every** `balanceId` on **every** account belonging to the Holder. A single balance left open can still receive credits and block closure later.
Setting `allowReceiving` to `false` blocks new inflows while still allowing outflows — which is exactly what you need to return the remaining balance to the customer in Step 4. For details on the permission flags, see [Balances](/en/midaz/balances).
### Step 3 — Settle pending activity
Before you can zero a balance, the account must have no in-flight movements.
* **Check for transactions in processing.** Confirm there are no pending or uncommitted transactions on the account. Commit or cancel them as appropriate using [Commit a pending transaction](/en/reference/midaz/commit-a-pending-transaction) or [Cancel a pending transaction](/en/reference/midaz/cancel-a-pending-transaction).
* **Cancel active schedules.** Cancel any recurring or scheduled transactions tied to the account so that no new entries are generated after closure begins.
Skipping this step can cause a closed account to receive late entries, which breaks reconciliation and the BACEN audit trail.
### Step 4 — Zero the balance
Return any remaining funds to the customer (the account holder) and confirm every balance reaches zero.
* Record a **return transaction** that moves the remaining `available` amount from each customer account to the holder's designated destination (for example, an external settlement account). Use [Create a transaction](/en/reference/midaz/create-a-transaction-using-json).
* **Confirm `available = 0`** on every balance of every account in the Ledger before proceeding. You can verify this with [Retrieve balances by account](/en/reference/midaz/retrieve-balances-by-account).
Midaz **does not allow deleting an account that still holds a balance**. All balances must be zero before Step 5.
### Step 5 — Close the Ledger Accounts in Midaz
With balances zeroed and pending activity cleared, delete each Ledger Account.
```http theme={null}
DELETE /v1/.../accounts/{accountId}
```
A successful request returns `204 No Content`. Repeat for every account linked to the Holder. See [Delete an account](/en/reference/midaz/delete-an-account) for the full contract.
Deleting a Ledger Account is a logical removal. The account and its historical operations remain available for audit and reporting, subject to your retention policy.
### Step 6 — Register the closing date on the alias
Record the official closure date on the Holder's Alias Account so that the CRM and any regulatory exports reflect when the relationship ended.
```http theme={null}
PATCH /v1/holders/{holderId}/aliases/{aliasId}
```
```json theme={null}
{
"bankingDetails": {
"closingDate": "2026-06-09"
}
}
```
`closingDate` lives in the `bankingDetails` object of the Alias Account and uses `YYYY-MM-DD` format. See [Alias Accounts](/en/midaz/crm/alias-accounts) for the full field reference. Setting an accurate closing date is required for BACEN account-lifecycle reporting.
### Step 7 — Archive the alias accounts in CRM
Archive each Alias Account in CRM. Use a **soft delete** so the record is removed from active use but preserved for the regulatory retention period.
```http theme={null}
DELETE /v1/holders/{holderId}/aliases/{aliasId}
```
Do **not** pass `hard_delete=true`. A regulated closure requires the record to be archived (soft-deleted) and retained, not permanently erased. See [Delete an alias account](/en/reference/midaz/crm/delete-alias-account).
### Step 8 — Archive the Holder in CRM
Finally, archive the Holder itself with a soft delete once all of its alias accounts have been archived.
```http theme={null}
DELETE /v1/holders/{holderId}
```
As in Step 7, omit `hard_delete=true`. The Holder record must be retained under the applicable retention policy for audit and regulatory inspection. See [Delete a holder](/en/reference/midaz/crm/delete-holder).
## Via Console
***
Run the same eight-step closure flow from the [Midaz Console](/en/lerian-console/midaz-console). The Console covers most of the flow point-and-click, but two steps — blocking credits (Step 2) and cancelling scheduled transactions (Step 3) — still require the API. Each step below notes the equivalent API step on this page.
The order is the same as the API flow. Do not delete accounts or archive CRM records before balances are zeroed.
### Step 1 — Freeze the Holder
Set the Holder to `INACTIVE` so no new alias accounts or downstream CRM workflows can start for the customer.
From the **Holders** page, find the Holder you are offboarding.
Click the three dots () in the **Actions** column, and select **Edit**.
In the Holder form, set the **Status** to **Inactive**.
Click **Save**.
Freezing the Holder is a logical state change, not a deletion. The record stays fully readable for audit and regulatory purposes. See [Editing a Holder](/en/lerian-console/midaz-console/crm-editing-a-holder).
### Step 2 — Block credits on the accounts
**This step requires the API — the Console does not support editing balance flags after account creation.** The Console only lets you set `allowReceiving` when an Account is first created, not when editing an existing balance. Use the API to disable receiving on every balance.
Follow [Step 2 — Block credits on the accounts](#step-2--block-credits-on-the-accounts) in the Via API section.
For each account linked to the Holder, set `allowReceiving` to `false` on every `balanceId` via the API so new inflows are blocked while outflows remain available for the return transaction in Step 4.
### Step 3 — Settle pending activity
Confirm there are no in-flight movements before zeroing any balance.
From the **Transactions** page, filter by the accounts linked to the Holder and confirm there are no pending or uncommitted transactions. Commit or cancel any that are in flight.
Cancel any recurring or scheduled transactions tied to the account so no new entries are generated after closure begins.
**Scheduled transactions require the API.** The Console lets you view and cancel individual transactions, but it does not provide management of scheduled (recurring) transactions. Use the API to cancel active schedules — see [Step 3 — Settle pending activity](#step-3--settle-pending-activity) in the Via API section.
### Step 4 — Zero the balance
Return any remaining funds to the customer and confirm every balance reaches zero.
From the **Transactions** page, click **New Transaction** and create a **return transaction** that moves the remaining `available` amount from each customer account to the holder's designated destination (for example, an external settlement account). See [Creating a Transaction](/en/lerian-console/midaz-console/creating-a-transaction).
Open each account and confirm the **available** balance is **0** before continuing.
Midaz **does not allow deleting an account that still holds a balance**. All balances must be zero before Step 5.
### Step 5 — Close the Ledger Accounts in Midaz
With balances zeroed and pending activity cleared, delete each Ledger Account.
From the **Accounts** page, find the Account linked to the Holder, click the three dots () in the **Actions** column, and select **Delete**.
A confirmation dialog will appear. Click **Confirm** to finalize the deletion.
Repeat for every account linked to the Holder.
Deleting a Ledger Account is a logical removal. The account and its historical operations remain available for audit and reporting, subject to your retention policy. See [Deleting an Account](/en/lerian-console/midaz-console/deleting-an-account).
### Step 6 — Register the closing date on the alias
Record the official closure date on the Holder's Alias Account so the CRM and regulatory exports reflect when the relationship ended.
From the **Alias Accounts** page, find the alias account to update, click the three dots () in the **Actions** column, and select **Edit**.
In the Alias Account form, set the **Closing Date** (in `bankingDetails`) to the official closure date using `YYYY-MM-DD` format.
Click **Save**.
An accurate closing date is required for BACEN account-lifecycle reporting. See [Editing an Alias Account](/en/lerian-console/midaz-console/crm-editing-alias-account).
### Step 7 — Archive the alias accounts in CRM
Archive each Alias Account with a **soft delete** so the record is removed from active use but preserved for the regulatory retention period.
From the **Alias Accounts** page, find the alias account to archive, click the three dots () in the **Actions** column, and select **Delete**.
A confirmation dialog will appear. Click **Confirm** to finalize.
Use the standard (soft) delete so the record is archived and retained, not permanently erased. In regulated deployments the underlying record is kept for the retention period. See [Deleting an Alias Account](/en/lerian-console/midaz-console/crm-deleting-alias-account).
### Step 8 — Archive the Holder in CRM
Once all of its alias accounts are archived, archive the Holder itself with a **soft delete**.
From the **Holders** page, find the Holder to archive, click the three dots () in the **Actions** column, and select **Delete**.
A confirmation dialog will appear. Click **Confirm** to finalize.
Use **Soft Delete** (the default), not Hard Delete. The Holder record must be retained under the applicable retention policy for audit and regulatory inspection. See [Deleting a Holder](/en/lerian-console/midaz-console/crm-deleting-a-holder).
## BACEN compliance notes
***
* **Order is mandatory.** Freezing inflows (Steps 1–2) before settling and zeroing (Steps 3–4) prevents funds from entering an account that is mid-closure.
* **Return funds before closing.** Any residual balance must be returned to the customer and confirmed at zero before an account is deleted. Closing an account with funds is both blocked by Midaz and non-compliant.
* **Archive, don't erase.** Holders and alias accounts are **soft-deleted** (no `hard_delete`) so the records remain available for the regulatory retention period. Permanent deletion would remove evidence required for BACEN audits.
* **Record the closing date.** The `closingDate` on the alias gives regulators an authoritative timestamp for when the relationship ended.
* **Preserve the audit trail.** Ledger Accounts and operations are logically removed and remain queryable for reconciliation and reporting.
Treat the eight steps as a single transaction from a compliance standpoint: if any step fails, pause and resolve it before continuing, rather than leaving the customer in a partially closed state.