Skip to main content
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 to its Alias Accounts. You can run the flow two ways. Via API gives you the endpoint, an example payload, and the compliance rationale for each step. 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:
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).
  • 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.
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 of the account. Then update each balance to disable receiving. Retrieve the account balances:
For each balanceId returned, block incoming funds:
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.

​
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 or 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.
  • Confirm available = 0 on every balance of every account in the Ledger before you proceed. You can check 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

After you zero the balances and clear pending activity, delete each Ledger Account.
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 the CRM and any regulatory exports reflect when the relationship ended.
The closingDate field lives in the bankingDetails object of the Alias Account and uses YYYY-MM-DD format. See 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.
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.

​
Step 8 — Archive the Holder in CRM

After you archive all of its alias accounts, archive the Holder itself with a soft delete.
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.

​
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 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.
1
From the Holders page, find the Holder to close.
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.
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.

​
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 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.
1
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.
2
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 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. 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 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.
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.
BACEN account-lifecycle reporting needs an accurate closing date. See Editing an 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.
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. 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.

​
Step 8 — Archive the Holder in CRM

After you archive all of its alias accounts, 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. Keep the Holder record under the applicable retention policy for audit and regulatory inspection. See 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.