Skip to main content
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 to archiving its Alias Accounts. You can run the flow two ways: Via API, with the endpoint, an example payload, and the compliance rationale for each step; or 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:
PhaseStepsGoal
1. Freeze1–2Stop new inflows at both the Holder and Balance level.
2. Settle and zero3–4Clear pending activity and return remaining funds to the customer.
3. Close and archive5–8Deactivate 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).
  • 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. 
PUT /v1/holders/{holderId}

{
  "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 of the account, then update each balance to disable receiving. Retrieve the account balances: 
GET /v1/.../accounts/{accountId}/balances
For each balanceId returned, block incoming funds: 
PATCH /v1/.../balances/{balanceId}

{
  "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.

​
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 or 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.
  • Confirm available = 0 on every balance of every account in the Ledger before proceeding. You can verify this with 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. 
DELETE /v1/.../accounts/{accountId}
A successful request returns 204 No Content. Repeat for every account linked to the Holder. See 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. 
PATCH /v1/holders/{holderId}/aliases/{aliasId}

{
  "bankingDetails": {
    "closingDate": "2026-06-09"
  }
}
closingDate lives in the bankingDetails object of the Alias Account and uses YYYY-MM-DD format. See 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. 
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.

​
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. 
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.

​
Via Console

Run the same eight-step closure flow from the 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.
1
From the Holders page, find the Holder you are offboarding.
2
Click the three dots () in the Actions column, and select Edit.
3
In the Holder form, set the Status to Inactive.
4
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.

​
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 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.
1
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.
2
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 in the Via API section.

​
Step 4 — Zero the balance

Return any remaining funds to the customer and confirm every balance reaches zero.
1
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.
2
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.
1
From the Accounts page, find the Account linked to the Holder, click the three dots () in the Actions column, and select Delete.
2
A confirmation dialog will appear. Click Confirm to finalize the deletion.
3
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.

​
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.
1
From the Alias Accounts page, find the alias account to update, click the three dots () in the Actions column, and select Edit.
2
In the Alias Account form, set the Closing Date (in bankingDetails) to the official closure date using YYYY-MM-DD format.
3
Click Save.
An accurate closing date is required for BACEN account-lifecycle reporting. See Editing an 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.
1
From the Alias Accounts page, find the alias account to archive, click the three dots () in the Actions column, and select Delete.
2
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.

​
Step 8 — Archive the Holder in CRM

Once all of its alias accounts are archived, archive the Holder itself with a soft delete.
1
From the Holders page, find the Holder to archive, click the three dots () in the Actions column, and select Delete.
2
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.

​
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.