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. Then close each account. The close operation refuses an account that still holds funds. Archive the CRM 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 archive CRM records before you close the accounts.

​
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} and /v2/.../accounts/{accountId} for readability.

​
Prerequisites

Before you start, make sure you have:
  • The holderId of the customer to offboard.
  • The accountId values linked to that Holder across every Ledger in the Organization. Retrieve them with GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts. The response is paginated, so retrieve every page. Add the optional ledger_id query parameter only when you need to narrow the list to one Ledger.
  • The instrument_id of each Alias Account, mapped to its corresponding accountId. List the Holder’s instruments with GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id} (also paginated) and use each instrument’s accountId field to map it to the Ledger Account. Steps 6 and 7 target these instrument_id values.
  • 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, instruments, balances, and accounts. Steps 6 and 7 update and delete instruments, so the credentials must carry patch and delete access on the instruments resource. Step 5 needs post and delete access on the accounts resource.
Closing an account cannot be undone. Before you proceed, confirm there are no active products 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. If a balance has a non-zero overdraftUsed, repay it first: a balance that refuses inflows also refuses the repayment. 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.
The close operation in Step 5 refuses an account whose funds a pending transaction still holds.

​
Step 4: Zero the balance

Return any remaining funds to the customer (the account holder) and confirm available = 0, onHold = 0, and overdraftUsed = 0 on every balance.
  • If a balance owes fee debt, settle it first with Collect open fee debts. The close operation refuses a balance that owes fee debt (0527).
  • 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, onHold = 0, and overdraftUsed = 0 on every balance of every account in the Ledger before you proceed. You can check this with Retrieve balances by account.
The close operation refuses an account with any balance whose available, onHold, or overdraftUsed amount is not exactly zero.

​
Step 5: Close the Ledger Accounts in Midaz

After you zero the balances and clear pending activity, close each Ledger Account.
The request takes no body. A successful request returns 204 No Content, and every later read of the account shows the closing instant in closedAt. Repeat for every account linked to the Holder. See Close an account for the full contract and the Midaz error list for each refusal. Then delete each closed account with DELETE /v2/.../accounts/{accountId}. Step 8 refuses to archive a Holder that still owns an account that is not deleted. See Delete an account.
Deleting an account is a logical removal. Its transactions remain available for audit and reporting. Midaz refuses every later movement on a closed account, and unblocking the account does not reopen it. An external account cannot be closed.

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

​
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 blocking credits (Step 2) and closing the accounts (Step 5) 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 archive CRM records before you close the accounts.

​
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
Confirm the update.
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. Repay any non-zero overdraftUsed before this step.

​
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
Review any pending transactions and commit or cancel them as appropriate.

​
Step 4: Zero the balance

Return any remaining funds to the customer and confirm available = 0, onHold = 0, and overdraftUsed = 0 on every balance.
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 available = 0, onHold = 0, and overdraftUsed = 0 before you continue.
The close operation refuses an account with any balance whose available, onHold, or overdraftUsed amount is not exactly zero.

​
Step 5: Close the Ledger Accounts in Midaz

Closing requires the API. Follow Step 5: Close the Ledger Accounts in Midaz in the Via API section.
Then delete each closed 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.
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
Confirm the update.
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 before you close an account. The close operation refuses an account that holds funds.
  • 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. The operations of a deleted account 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.