> ## 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
> Follow the eight-step flow to freeze, settle, and archive a customer account across Ledger and CRM in line with BACEN account closure and audit requirements.
To close a customer account in Midaz, you work across two areas: the **Ledger** (accounts and balances) and **CRM** (holders and alias accounts). BACEN rules make account closure a regulated event, so the order matters. Stop new credits first, then settle pending activity and return any remaining funds. Deactivate the underlying records last.
This guide covers the full closure flow, from the [Holder](/en/midaz/crm/holders) to its [Alias Accounts](/en/midaz/crm/alias-accounts). You can run the flow two ways. **[Via API](#via-api)** gives you the endpoint, an example payload, and the compliance rationale for each step. **[Via Console](#via-console)** gives you the same steps as point-and-click actions in the Midaz Console.
Follow the steps in order. Do not close accounts or archive CRM records before you zero the balances. Early closure can leave orphaned funds or break the audit trail that regulatory reporting needs.
## Overview
***
The closure flow has eight steps, grouped into three phases:
| Phase | Steps | Goal |
| :----------------------- | :---- | :------------------------------------------------------------------------- |
| **1. Freeze** | 1–2 | Mark the Holder inactive and stop new credits at the 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. This guide abbreviates the paths to `/v1/.../accounts/{accountId}` for readability.
## Prerequisites
***
Before you start, make sure you have:
* The `holderId` of the customer to offboard.
* 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 you can end the customer relationship (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. Before you proceed, confirm there are no active products, scheduled transactions, or open obligations.
## 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
Mark the Holder as inactive to record the closure across your systems. Update the Holder and set the `status` field on its person profile to an inactive value.
```http theme={null}
PATCH /v1/holders/{holderId}
```
```json theme={null}
{
"naturalPerson": {
"status": "INACTIVE"
}
}
```
Marking the Holder inactive is a record change, not a deletion. The Holder record stays fully readable for audit. This status does not block new credits on its own — Step 2 blocks inflows at the balance level. For a legal person, set `legalPerson.status` instead.
### 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.
When you set `allowReceiving` to `false`, the balance blocks new inflows but still allows outflows. This is exactly what you need in Step 4 to return the remaining balance to the customer. 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 the account has no pending or uncommitted transactions. 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. This stops new entries after closure begins.
If you skip this step, a closed account can receive late entries. Late entries break 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 you proceed. You can check 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
After you zero the balances and clear pending activity, 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 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"
}
}
```
The `closingDate` field 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. BACEN account-lifecycle reporting needs an accurate closing date.
### Step 7 — Archive the alias accounts in CRM
Archive each Alias Account in CRM. Use a **soft delete**. It removes the record from active use but keeps it for the regulatory retention period.
```http theme={null}
DELETE /v1/holders/{holderId}/aliases/{aliasId}
```
Do **not** pass `hard_delete=true`. A regulated closure must archive (soft-delete) the record and keep it. It must not erase the record permanently. See [Delete an alias account](/en/reference/midaz/crm/delete-alias-account).
### Step 8 — Archive the Holder in CRM
After you archive all of its alias accounts, archive the Holder itself with a soft delete.
```http theme={null}
DELETE /v1/holders/{holderId}
```
As in Step 7, omit `hard_delete=true`. Keep the Holder record 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/midaz/console/midaz-module). 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 you zero the balances.
### Step 1 — Freeze the Holder
Mark the Holder as inactive to record the closure. This is a record change and does not block new credits on its own.
From the **Holders** page, find the Holder to close.
Click the three dots () in the **Actions** column, and select **Edit**.
In the Holder form, set the **Status** to **Inactive**.
Click **Save**.
Marking the Holder inactive is a record change, not a deletion. The record stays fully readable for audit. It does not block new credits on its own — Step 2 blocks inflows at the balance level. See [Editing a Holder](/en/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 lets you set `allowReceiving` only when you first create an Account, not when you edit 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, use the API to set `allowReceiving` to `false` on every `balanceId`. This blocks new inflows while outflows remain available for the return transaction in Step 4.
### Step 3 — Settle pending activity
Confirm there are no in-flight movements before you zero any balance.
From the **Transactions** page, filter by the accounts linked to the Holder. Confirm the account has no pending or uncommitted transactions, and commit or cancel any that are in flight.
Cancel any recurring or scheduled transactions tied to the account. This stops new entries 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**. 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/midaz/console/creating-a-transaction).
Open each account and confirm the **available** balance is **0** before you continue.
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
After you zero the balances and clear pending activity, 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/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**.
BACEN account-lifecycle reporting needs an accurate closing date. See [Editing an Alias Account](/en/midaz/console/crm-editing-alias-account).
### Step 7 — Archive the alias accounts in CRM
Archive each Alias Account with a **soft delete**. It removes the record from active use but keeps it 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. It archives and keeps the record instead of erasing it permanently. In regulated deployments, Midaz keeps the underlying record for the retention period. See [Deleting an Alias Account](/en/midaz/console/crm-deleting-alias-account).
### Step 8 — Archive the Holder in CRM
After you archive all of its alias accounts, 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. Keep the Holder record under the applicable retention policy for audit and regulatory inspection. See [Deleting a Holder](/en/midaz/console/crm-deleting-a-holder).
## BACEN compliance notes
***
* **Order is mandatory.** Freeze first (Steps 1–2), then settle and zero (Steps 3–4). This order stops funds from entering an account that is mid-closure.
* **Return funds before closing.** Return any residual balance to the customer and confirm it at zero before you delete an account. Midaz blocks closing an account that holds funds, and that closure would also break compliance.
* **Archive, don't erase.** A soft delete (no `hard_delete`) keeps Holders and alias accounts available for the regulatory retention period. Permanent deletion would remove evidence that BACEN audits need.
* **Record the closing date.** The `closingDate` on the alias gives regulators an authoritative timestamp for when the relationship ended.
* **Preserve the audit trail.** Midaz removes Ledger Accounts and operations logically. They 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 you continue. Do not leave the customer in a partially closed state.