Saltar al contenido principal
Para cerrar una cuenta de cliente en Midaz, trabajas en dos áreas: el Ledger (cuentas y saldos) y CRM (titulares y cuentas alias). Las reglas de BACEN convierten el cierre de cuenta en un evento regulado, por lo que el orden importa. Primero, detén los nuevos créditos; luego, liquida la actividad pendiente y devuelve los fondos restantes. Después, cierra cada cuenta. La operación de cierre rechaza una cuenta que todavía tiene fondos. Archiva los registros de CRM al final. Esta guía cubre el flujo de cierre completo, desde el Titular hasta sus Cuentas Alias. Puedes ejecutar el flujo de dos formas. A través de la API te da el endpoint, un payload de ejemplo y la justificación de cumplimiento para cada paso. A través de la Console te da los mismos pasos como acciones de apuntar y hacer clic en la Console de Midaz.
Sigue los pasos en orden. No archives registros de CRM antes de cerrar las cuentas.

​
Resumen

El flujo de cierre tiene ocho pasos, agrupados en tres fases:
A lo largo de esta guía, {organization_id} y {ledger_id} identifican la Organización y el Ledger de Midaz que son propietarios de las cuentas. Esta guía abrevia las rutas a /v1/.../accounts/{accountId} y /v2/.../accounts/{accountId} para facilitar la lectura.

​
Requisitos previos

Antes de empezar, confirma que tienes lo siguiente:
  • El holderId del cliente que vas a dar de baja.
  • Los valores accountId vinculados a ese Titular en cada Ledger de la Organización. Recupéralos con GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts. La respuesta está paginada, así que recupera todas las páginas. Agrega el parámetro de consulta opcional ledger_id solo cuando necesites acotar la lista a un Ledger.
  • El instrument_id de cada Cuenta Alias, asociado con su accountId correspondiente. Lista los instrumentos del Titular con GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id} (también paginado) y usa el campo accountId de cada instrumento para asociarlo con la Cuenta del Ledger. El Paso 5 usa estos valores de instrument_id.
  • Confirmación de tu equipo de cumplimiento de que puedes finalizar la relación con el cliente (sin retenciones legales, disputas abiertas ni requisitos regulatorios pendientes).
  • Credenciales de API adecuadas con permiso para modificar titulares, instrumentos, saldos y cuentas. El Paso 5 actualiza instrumentos, por lo que las credenciales deben tener acceso patch sobre el recurso instruments. Los pasos 6 y 7 requieren acceso post y delete sobre el recurso accounts.
El cierre de una cuenta no se puede deshacer. Antes de continuar, confirma que no haya productos activos ni obligaciones abiertas.

​
A través de la API

Ejecuta el flujo de cierre completo mediante programación. Cada paso incluye el endpoint, un payload de ejemplo y la justificación de cumplimiento.

​
Paso 1: Congela al Titular

Marca al Titular como inactivo para registrar el cierre en todos tus sistemas. Actualiza al Titular y establece el campo status de su perfil de persona en un valor inactivo.
Marcar al Titular como inactivo es un cambio de registro, no una eliminación. El registro del Titular permanece totalmente legible para auditoría. Este estado no bloquea los nuevos créditos por sí solo. El Paso 2 bloquea las entradas en el nivel del saldo. Para una persona jurídica, establece legalPerson.status en su lugar.

​
Paso 2: Bloquea los créditos en las cuentas

Para cada cuenta vinculada al Titular, evita que ingresen nuevos fondos. Primero, lista los Saldos de la cuenta. Luego, actualiza cada saldo para deshabilitar la recepción. Si un saldo tiene un overdraftUsed distinto de cero, págalo antes: un saldo que rechaza entradas también rechaza el pago. Recupera los saldos de la cuenta:
Para cada balanceId que se devuelva, bloquea los fondos entrantes:
Repite este paso para todos los balanceId de todas las cuentas que pertenecen al Titular. Un solo saldo que quede abierto todavía puede recibir créditos y bloquear el cierre más adelante.
Cuando estableces allowReceiving en false, el saldo bloquea las nuevas entradas de fondos, pero sigue permitiendo las salidas. Esto es exactamente lo que necesitas en el Paso 4 para devolver el saldo restante al cliente. Para más detalles sobre los indicadores de permiso, consulta Saldos.

​
Paso 3: Liquida la actividad pendiente

Antes de poner en cero un saldo, la cuenta no debe tener movimientos en curso.
La operación de cierre del Paso 6 rechaza una cuenta cuyos fondos todavía retiene una transacción pendiente.

​
Paso 4: Pon el saldo en cero

Devuelve los fondos restantes al cliente (el titular de la cuenta) y confirma available = 0, onHold = 0 y overdraftUsed = 0 en todos los saldos.
  • Si un saldo debe deuda de comisión, liquídala primero con Cobrar deudas de comisión abiertas. La operación de cierre rechaza un saldo que debe deuda de comisión (0527).
  • Registra una transacción de devolución que mueva el monto available restante de cada cuenta del cliente al destino designado por el titular (por ejemplo, una cuenta de liquidación externa). Usa Crear una transacción.
  • Confirma available = 0, onHold = 0 y overdraftUsed = 0 en todos los saldos de todas las cuentas del Ledger antes de continuar. Puedes verificarlo con Recuperar saldos por cuenta.
La operación de cierre rechaza una cuenta con cualquier saldo cuyo monto available, onHold u overdraftUsed no sea exactamente cero.

​
Paso 5: Registra la fecha de cierre en el alias

Registra la fecha oficial de cierre en la Cuenta Alias del Titular para que el CRM y cualquier exportación regulatoria reflejen cuándo terminó la relación. Hazlo antes de eliminar la cuenta en el Paso 7. Después de la eliminación, Midaz responde a una actualización de la Cuenta Alias con no encontrado.
El campo closingDate está en el objeto bankingDetails de la Cuenta Alias y usa el formato YYYY-MM-DD. Consulta Cuentas Alias para ver la referencia completa de campos. Los informes de ciclo de vida de cuentas de BACEN necesitan una fecha de cierre exacta.

​
Paso 6: Cierra las Cuentas del Ledger en Midaz

Después de poner los saldos en cero y resolver la actividad pendiente, cierra cada Cuenta del Ledger.
La solicitud no tiene cuerpo. Una solicitud exitosa devuelve 204 No Content, y cada lectura posterior de la cuenta muestra el instante del cierre en closedAt. Repite el proceso para cada cuenta vinculada al Titular. Consulta Cerrar una cuenta para conocer el contrato completo y la lista de errores de Midaz para cada rechazo.
Midaz rechaza cualquier movimiento posterior en una cuenta cerrada, y desbloquear la cuenta no la reabre. Una cuenta externa no se puede cerrar.

​
Paso 7: Elimina las Cuentas del Ledger

Elimina cada cuenta cerrada. La eliminación también archiva (con un borrado lógico) todas las Cuentas Alias vinculadas a la cuenta.
El Paso 8 rechaza archivar un Titular que todavía posee una cuenta no eliminada. Consulta Eliminar una cuenta.
Eliminar una cuenta es una baja lógica. Sus transacciones permanecen disponibles para auditoría e informes.

​
Paso 8: Archiva al Titular en CRM

Después de eliminar todas sus cuentas, archiva al propio Titular con un borrado lógico.
No envíes hard_delete=true. Mantén el registro del Titular bajo la política de retención aplicable para auditoría e inspección regulatoria. Consulta Eliminar un titular.

​
A través de la Console

Ejecuta el mismo flujo de cierre de ocho pasos desde la Console de Midaz. La Console cubre la mayor parte del flujo con acciones de apuntar y hacer clic, pero bloquear los créditos (Paso 2) y cerrar las cuentas (Paso 6) requieren la API. Cada paso a continuación indica el paso equivalente de la API en esta página.
El orden es el mismo que en el flujo de la API. No archives registros de CRM antes de cerrar las cuentas.

​
Paso 1: Congela al Titular

Marca al Titular como inactivo para registrar el cierre. Esto es un cambio de registro y no bloquea los nuevos créditos por sí solo.
1
En la página Titulares, busca al Titular que quieres cerrar.
2
Haz clic en los tres puntos () en la columna Acciones y selecciona Editar.
3
En el formulario del Titular, establece el Estado en Inactivo.
4
Confirma la actualización.
Marcar al Titular como inactivo es un cambio de registro, no una eliminación. El registro permanece totalmente legible para auditoría. No bloquea los nuevos créditos por sí solo. El Paso 2 bloquea las entradas en el nivel del saldo. Consulta Editar un Titular.

​
Paso 2: Bloquea los créditos en las cuentas

Este paso requiere la API. La Console no permite editar los indicadores de saldo después de crear la cuenta. La Console permite establecer allowReceiving solo cuando creas una Cuenta por primera vez, no cuando editas un saldo existente. Usa la API para deshabilitar la recepción en todos los saldos.Sigue Paso 2: Bloquea los créditos en las cuentas en la sección A través de la API.
Para cada cuenta vinculada al Titular, usa la API para establecer allowReceiving en false en todos los balanceId. Esto bloquea las nuevas entradas mientras las salidas permanecen disponibles para la transacción de devolución del Paso 4. Paga cualquier overdraftUsed distinto de cero antes de este paso.

​
Paso 3: Liquida la actividad pendiente

Confirma que no haya movimientos en curso antes de poner en cero cualquier saldo.
1
En la página Transacciones, filtra por las cuentas vinculadas al Titular. Confirma que la cuenta no tenga transacciones pendientes ni sin confirmar, y confirma o cancela las que estén en curso.
2
Revisa las transacciones pendientes y confírmalas o cancélalas según corresponda.

​
Paso 4: Pon el saldo en cero

Devuelve los fondos restantes al cliente y confirma available = 0, onHold = 0 y overdraftUsed = 0 en todos los saldos.
1
En la página Transacciones, haz clic en Nueva transacción. Crea una transacción de devolución que mueva el monto available restante de cada cuenta del cliente al destino designado por el titular, por ejemplo una cuenta de liquidación externa. Consulta Crear una transacción.
2
Abre cada cuenta y confirma available = 0, onHold = 0 y overdraftUsed = 0 antes de continuar.
La operación de cierre rechaza una cuenta con cualquier saldo cuyo monto available, onHold u overdraftUsed no sea exactamente cero.

​
Paso 5: Registra la fecha de cierre en el alias

Registra la fecha oficial de cierre en la Cuenta Alias del Titular para que el CRM y las exportaciones regulatorias reflejen cuándo terminó la relación. Hazlo antes de eliminar la cuenta en el Paso 7.
1
En la página Cuentas Alias, busca la cuenta alias que quieres actualizar, haz clic en los tres puntos () en la columna Acciones y selecciona Editar.
2
En el formulario de la Cuenta Alias, establece la Fecha de cierre (en bankingDetails) con la fecha oficial de cierre en formato YYYY-MM-DD.
3
Confirma la actualización.
Los informes de ciclo de vida de cuentas de BACEN necesitan una fecha de cierre exacta. Consulta Editar una Cuenta Alias.

​
Paso 6: Cierra las Cuentas del Ledger en Midaz

El cierre requiere la API. Sigue el Paso 6: Cierra las Cuentas del Ledger en Midaz en la sección A través de la API.

​
Paso 7: Elimina las Cuentas del Ledger

Elimina cada cuenta cerrada. La eliminación también archiva todas las Cuentas Alias vinculadas a la cuenta.
1
En la página Cuentas, busca la Cuenta vinculada al Titular, haz clic en los tres puntos () en la columna Acciones y selecciona Eliminar.
2
Aparecerá un cuadro de diálogo de confirmación. Haz clic en Confirmar para finalizar la eliminación.
3
Repite el proceso para cada cuenta vinculada al Titular.
Consulta Eliminar una cuenta.

​
Paso 8: Archiva al Titular en CRM

Después de eliminar todas sus cuentas, archiva al propio Titular con un borrado lógico.
1
En la página Titulares, busca al Titular que quieres archivar, haz clic en los tres puntos () en la columna Acciones y selecciona Eliminar.
2
Aparecerá un cuadro de diálogo de confirmación. Haz clic en Confirmar para finalizar.
Usa Soft Delete (la opción predeterminada), no Hard Delete. Mantén el registro del Titular bajo la política de retención aplicable para auditoría e inspección regulatoria. Consulta Eliminar un Titular.

​
Notas de cumplimiento de BACEN

  • El orden es obligatorio. Primero congela (Pasos 1–2), luego liquida y pon en cero (Pasos 3–4). Este orden evita que entren fondos a una cuenta que está en proceso de cierre.
  • Devuelve los fondos antes de cerrar. Devuelve cualquier saldo residual al cliente antes de cerrar una cuenta. La operación de cierre rechaza una cuenta que tiene fondos.
  • Archiva, no borres. Un borrado lógico (sin hard_delete) mantiene disponibles a los Titulares y las cuentas alias durante el período de retención regulatorio. La eliminación permanente eliminaría evidencia que las auditorías de BACEN necesitan.
  • Registra la fecha de cierre. El closingDate del alias les da a los reguladores una marca de tiempo autorizada de cuándo terminó la relación.
  • Conserva el registro de auditoría. Las operaciones de una cuenta eliminada permanecen consultables para conciliación e informes.
Trata los ocho pasos como una sola transacción desde el punto de vista del cumplimiento. Si algún paso falla, pausa y resuélvelo antes de continuar. No dejes al cliente en un estado de cierre parcial.