> ## 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. # Overdraft de Saldo > Habilita el Balance Overdraft controlado en Midaz con operaciones de split automáticas, prioridad de reembolso de crédito y límites para cuentas BNPL o de liquidación. El Balance Overdraft te permite debitar un saldo más allá de sus fondos disponibles. El saldo primario nunca queda negativo. Midaz rastrea el déficit como **OverdraftUsed** y divide la operación entre el saldo primario y un saldo companion interno. Cuando llegan créditos, Midaz paga el overdraft primero. Cualquier excedente va al Available. Este mecanismo soporta líneas de crédito, BNPL, cuentas de liquidación, anticipo salarial y cualquier producto que necesite posiciones negativas controladas. ## Dirección del saldo *** Los saldos llevan un campo `direction` que define cómo los débitos y créditos afectan al saldo: | Dirección | Comportamiento | Uso típico | | ---------------------- | --------------------------------- | ------------------------------------------------------ | | `credit` (por defecto) | Débito disminuye, crédito aumenta | Cuentas corrientes, billeteras, reservas | | `debit` | Débito aumenta, crédito disminuye | Préstamos, seguimiento de overdraft, cuentas por pagar | Defines la dirección en el momento de la creación. Es **inmutable**. El saldo companion de overdraft (descrito a continuación) siempre usa `direction=debit`. ## Configuraciones del saldo *** El objeto `settings` en un saldo controla el comportamiento de overdraft: | Campo | Tipo | Descripción | | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ | | `allowOverdraft` | boolean | Habilita overdraft en este saldo | | `overdraftLimitEnabled` | boolean | Define si se impone un límite | | `overdraftLimit` | string (decimal) | Monto máximo de overdraft. Requerido cuando `overdraftLimitEnabled` es `true`. Debe ser mayor que `0`. | El objeto `settings` también lleva un campo `balanceScope` **gestionado por el sistema**. Separa los saldos internos (como el companion de overdraft) de los saldos transaccionales. No configuras este campo directamente. ## Modos de configuración *** ### Sin overdraft (por defecto) El comportamiento estándar. Midaz rechaza cualquier débito que exceda el saldo disponible. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": false } } ``` ### Overdraft ilimitado El saldo puede quedar negativo sin tope. Usa esto para cuentas de liquidación o pool, donde las posiciones negativas son normales y las concilias externamente. ```json JSON theme={null} { "key": "settlement", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Overdraft limitado El saldo puede quedar negativo hasta un límite definido. El modo más común para productos de crédito al consumidor. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "5000.00" } } ``` Cuando `overdraftLimitEnabled` es `true`, debes establecer `overdraftLimit` como una cadena decimal positiva. Si lo omites o lo estableces en `"0"`, Midaz devuelve el error `0172 - ErrInvalidBalanceSettings`. ## Cómo funciona el overdraft *** ### Split de operación Cuando una transacción de débito excede los fondos disponibles, Midaz divide automáticamente la operación: 1. El débito consume todo el Available restante y lo fija en **0**. 2. Midaz acumula el excedente como **OverdraftUsed** en el saldo primario. 3. Midaz crea una operación companion en el saldo interno `"overdraft"` (descrito a continuación). Esta operación registra el pasivo como un débito de partida doble. **Ejemplo:** Saldo con Available = 300. Llega un débito de 500. | Paso | Available | OverdraftUsed | Descripción | | ------- | --------- | ------------- | ----------------------------------------------------------- | | Antes | 300 | 0 | Estado normal | | Después | 0 | 200 | 300 consumidos del Available, 200 acumulados como overdraft | La transacción se procesa como una única operación atómica. El llamador no necesita manejar el split — Midaz lo hace automáticamente. Si configuras un límite, Midaz compara el OverdraftUsed resultante con el `overdraftLimit` **antes** de procesar la transacción. Si el resultado excede el límite, Midaz rechaza la transacción con el error `0167 - ErrOverdraftLimitExceeded`. ### Reembolso automático (refund split) Cuando llega un crédito y `OverdraftUsed > 0`, Midaz prioriza el reembolso: 1. Midaz aplica el crédito primero al **OverdraftUsed** y reduce la deuda. 2. Cualquier monto remanente después de que OverdraftUsed llegue a 0 va al **Available**. 3. Una operación companion en el saldo `"overdraft"` registra el reembolso. **Ejemplo:** OverdraftUsed = 200, Available = 0. Llega un crédito de 350. | Paso | Available | OverdraftUsed | Descripción | | ------- | --------- | ------------- | -------------------------------------- | | Antes | 0 | 200 | Overdraft activo | | Después | 150 | 0 | 200 reembolsados, 150 van al Available | El reembolso es automático. No puedes omitirlo. Midaz reduce las posiciones de overdraft lo antes posible, lo que mantiene el saldo saludable. ### Cancelación de transacción pendiente con overdraft Cuando cancelas una transacción `PENDING` que consumió overdraft, Midaz mantiene el saldo companion sincronizado con el saldo primario: 1. La cancelación revierte el hold original y cualquier overdraft consumido durante la ventana pending. `OverdraftUsed` regresa a su valor previo al hold. 2. Una operación `CREDIT` companion en el saldo `"overdraft"` reduce el pasivo por el monto exacto consumido. 3. Midaz aplica la cancelación primaria y el crédito companion en el **mismo batch atómico**. Los dos saldos nunca se desincronizan. Midaz mantiene el saldo companion sincronizado con el saldo primario. Esto se aplica a las fases de hold, commit y cancel de cualquier transacción pending que toque el overdraft. ## Position *** Toda respuesta de saldo incluye un bloque computado `position`. Ofrece una vista en tiempo real del estado del saldo: | Campo | Descripción | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `available` | `Balance.Available` menos `OverdraftUsed`. Puede ser negativo cuando el overdraft está activo. | | `onHold` | Refleja `Balance.OnHold` — fondos reservados por operaciones pendientes. | | `overdraftLimitAvailable` | Margen de overdraft restante. `"0"` cuando el overdraft está deshabilitado. Omitido cuando es ilimitado. Decimal positivo cuando un límite está configurado. | No almacenes en caché el bloque `position` con fines contables. Midaz nunca lo persiste — computa el bloque en el momento de la consulta a partir del estado actual del saldo. ## Saldo companion *** Cuando actualizas un saldo para establecer `allowOverdraft` en `true` por primera vez, Midaz auto-aprovisiona un **saldo companion** bajo la misma cuenta. El saldo companion registra el lado del pasivo en la partida doble. Midaz lo crea una sola vez por cuenta y lo reutiliza en cada draw y reembolso de overdraft. | Propiedad | Valor | Por qué | | ---------------- | ------------- | --------------------------------------------------------------------------------- | | `key` | `"overdraft"` | Clave reservada del sistema | | `direction` | `debit` | El companion rastrea un pasivo — los débitos lo aumentan, los créditos lo reducen | | `scope` | `internal` | Bloquea operaciones directas de usuarios | | `allowSending` | `true` | Necesario para operaciones DEBIT en el companion (consumo de overdraft) | | `allowReceiving` | `true` | Necesario para operaciones CREDIT en el companion (reembolsos de overdraft) | Este saldo es **completamente gestionado por el sistema**: * No puedes crearlo, modificarlo ni eliminarlo a través de la API pública. * Midaz **reserva** la clave `"overdraft"`. Una solicitud que crea un saldo con esta clave devuelve el error `0170 - ErrReservedBalanceKey`. * Refleja el pasivo como un registro de partida doble, de modo que el ledger se mantiene equilibrado. El valor `scope: "internal"` bloquea las operaciones directas de usuarios, sin importar las flags de permiso anteriores. Midaz rechaza cualquier operación directa sobre este saldo con el error `0168 - ErrDirectOperationOnInternalBalance`. El companion solo se mueve a través del enrichment de overdraft conducido por el sistema. ## Estado de overdraft en las operaciones *** Toda operación expone el estado de overdraft en los bloques `balance` y `balanceAfter`. El campo `overdraftUsed` registra el overdraft consumido antes y después de la operación. Esto ofrece un rastro de auditoría completo sin una consulta separada al saldo. Para operaciones que no tocan el overdraft, ambos valores son `"0"`. Las operaciones companion gestionadas por el sistema en el saldo `"overdraft"` usan `type: "OVERDRAFT"` (en mayúsculas). El campo `direction` lleva el ciclo de vida: `"debit"` para un draw, `"credit"` para un reembolso. ```json Débito primario consumiendo overdraft theme={null} { "type": "DEBIT", "direction": "debit", "amount": { "value": "500" }, "accountAlias": "@user123", "balanceKey": "checking", "balance": { "available": "300", "onHold": "0", "version": 1, "overdraftUsed": "0" }, "balanceAfter": { "available": "0", "onHold": "0", "version": 2, "overdraftUsed": "200" } } ``` ```json Companion de draw de overdraft theme={null} { "type": "OVERDRAFT", "direction": "debit", "amount": { "value": "200" }, "balanceKey": "overdraft", "balance": { "available": "0", "onHold": "0", "version": 1, "overdraftUsed": "0" }, "balanceAfter": { "available": "200", "onHold": "0", "version": 2, "overdraftUsed": "200" } } ``` Tanto la operación primaria como la companion comparten el mismo par `overdraftUsed` antes/después. Ambas reflejan la transición de overdraft del saldo primario, por lo que el ciclo de vida es visible desde cualquiera de las filas. La columna interna `snapshot` (JSONB) en la tabla `operations` almacena los mismos valores para indexación y reconstrucción histórica. Esta columna no forma parte del JSON público. En su lugar, los valores aparecen en `balance.overdraftUsed` y `balanceAfter.overdraftUsed`. Midaz puede agregar contexto futuro generado por el sistema al snapshot sin romper el contrato público. Las operaciones companion heredan el `routeId` de la operación primaria. Midaz resuelve su `routeCode` y `routeDescription` de forma independiente a partir de la rúbrica `overdraft` de la route. Si la route no tiene un asiento de overdraft, ambos quedan vacíos. ## Eventos de overdraft *** Midaz publica eventos de ciclo de vida en RabbitMQ cuando el estado de overdraft cambia. La publicación está **habilitada por defecto**. Establece la flag en `"false"` para deshabilitar. ```bash Entorno theme={null} # Deshabilita la publicación de eventos de overdraft (por defecto: habilitado). RABBITMQ_OVERDRAFT_EVENTS_ENABLED=false # Opcional: enruta los eventos de overdraft hacia una exchange dedicada. # Cuando no está definido, se usa la exchange por defecto del broker. RABBITMQ_OVERDRAFT_EVENTS_EXCHANGE=transaction.overdraft_events.exchange ``` ### Tipos de evento | Evento | Descripción | | ------------------- | ----------------------------------------------------------------------------------- | | `overdraft.drawn` | Se consumió overdraft — OverdraftUsed aumentó | | `overdraft.repaid` | Se reembolsó parcialmente el overdraft — OverdraftUsed disminuyó pero permanece > 0 | | `overdraft.cleared` | Se liquidó totalmente el overdraft — OverdraftUsed llegó a 0 | ### Ejemplo de payload del evento ```json JSON expandable theme={null} { "source": "midaz", "eventType": "balance", "action": "overdraft.drawn", "timestamp": "2026-04-28T14:30:00.000000Z", "version": "v3.0.0", "organizationId": "0198575d-f9fd-702b-bb15-fa4c980b32c7", "ledgerId": "0198575d-fa0b-7ac7-8b7d-9d3ab7dccafc", "payload": { "accountId": "0198575f-a8f9-7924-a6d7-8122f2c77ddd", "transactionId": "019b2c3d-4e5f-6789-0123-456789abcdef", "amount": "200", "overdraftBalance": "200", "overdraftLimit": "5000.00", "timestamp": "2026-04-28T14:30:00.000000Z" } } ``` Usa los eventos de overdraft para activar flujos de trabajo downstream — acumulación de intereses, notificaciones al cliente, alertas de riesgo o procesos de cobro automático. ## Casos de uso *** ### Sobregiro de cuenta corriente (cheque especial) Crédito clásico al consumidor. El saldo de la cuenta corriente puede quedar negativo hasta un límite preaprobado. Los intereses se acumulan sobre el monto pendiente. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "2000.00" } } ``` ### Buy Now, Pay Later (BNPL) Un proveedor de BNPL emite un crédito de compra contra el saldo del cliente. Esto crea una posición de overdraft inmediata que el cliente paga en cuotas. ```json JSON theme={null} { "key": "bnpl", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000.00" } } ``` ### Anticipo salarial (Earned Wage Access) Los empleados retiran contra ingresos futuros. Los créditos de nómina liquidan la posición de overdraft cuando llegan. ```json JSON theme={null} { "key": "salary-advance", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "3000.00" } } ``` ### Anticipo de cuentas por cobrar de marketplace Los vendedores reciben un anticipo sobre cuentas por cobrar futuras. Midaz paga el overdraft automáticamente conforme llegan las liquidaciones de ventas. ```json JSON theme={null} { "key": "receivables", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "50000.00" } } ``` ### Cuentas de liquidación / Pool (modo ilimitado) Las cuentas de liquidación y pool rutinariamente quedan negativas durante el procesamiento intradía. El overdraft ilimitado evita rechazos artificiales mientras concilias la posición al final del día. ```json JSON theme={null} { "key": "settlement-pool", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Líneas de crédito revolvente (B2B) Las empresas retiran y pagan de una facilidad de crédito revolvente. El límite de overdraft representa la línea de crédito total. ```json JSON theme={null} { "key": "credit-line", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "500000.00" } } ``` ### Prefinanciamiento de seguros Las aseguradoras prefinancian siniestros antes del cierre de los ciclos de cobro de primas. El overdraft cubre la brecha entre el pago y la cobranza. ```json JSON theme={null} { "key": "claims-prefin", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "100000.00" } } ``` ### Programas de fidelización (puntos anticipados) Los clientes canjean puntos antes de acumularlos. El overdraft rastrea el déficit de puntos y se liquida conforme los clientes acumulan nuevos puntos. ```json JSON theme={null} { "key": "loyalty-points", "assetCode": "POINTS", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000" } } ``` ## Reglas de protección *** El overdraft introduce varias restricciones de inmutabilidad y acceso para mantener la integridad del ledger: * **La dirección es inmutable.** Una vez que defines la `direction` de un saldo en la creación, no puedes cambiarla. * **Los saldos internos bloquean escrituras.** No puedes crear, eliminar ni actualizar el saldo companion `"overdraft"` a través de la API pública — un PATCH devuelve el error `0175`. * **Claves reservadas.** Midaz reserva la clave `"overdraft"` para el saldo companion gestionado por el sistema. * **Deshabilitar overdraft preserva la deuda pendiente.** Puedes establecer `allowOverdraft: false` mientras `OverdraftUsed > 0` para bloquear nuevos retiros, mientras que los créditos entrantes siguen pagando la deuda existente. * **El límite no puede bajar del uso.** Si `OverdraftUsed = 200`, Midaz rechaza `overdraftLimit: "100"` con el error `0173`, así que paga por debajo del nuevo techo primero o establece un límite mayor. * **Concurrencia optimista.** Las actualizaciones de saldo usan control de concurrencia basado en versión, y Midaz rechaza una escritura obsoleta con el error `0174` — reintenta con la versión más reciente. Para el catálogo completo de los códigos de error relacionados con overdraft (0167–0175), consulta la [Lista de errores de Midaz](/es/reference/midaz/error-list). ## Próximos pasos *** * Conoce los [Saldos](/es/midaz/balances) — la base sobre la que se construye el overdraft. * Entiende las [Operaciones](/es/midaz/operations) para rastrear cómo los splits de overdraft aparecen en el ledger. * Configura el [Event Publisher](/es/midaz/event-publisher) para consumir eventos del ciclo de vida del overdraft. * Explora las [Transacciones](/es/midaz/transactions) para la visión completa de la contabilidad de partida doble en Midaz.