Sobregiro de Saldo

El Sobregiro de Saldo permite debitar un saldo más allá de sus fondos disponibles. El saldo principal nunca queda negativo. Midaz registra el déficit como OverdraftUsed y divide la operación entre el saldo principal y un saldo complementario interno. Cuando llegan créditos, Midaz paga primero el sobregiro. El resto va a Available. Este mecanismo admite líneas de crédito, BNPL, cuentas de liquidación, acceso al salario devengado 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 el saldo:

Dirección	Comportamiento	Uso típico
`credit`	El débito disminuye, el crédito aumenta	Cuentas corrientes, billeteras, reservas
`debit`	El débito aumenta, el crédito disminuye	Préstamos, seguimiento de sobregiro, cuentas por pagar

En la creación, Midaz usa un direction explícito cuando se proporciona, luego el defaultDirection del Tipo de Cuenta. Si ninguno está definido, las Cuentas externas usan debit. Todas las demás Cuentas usan credit.

Defines la dirección en el momento de la creación. Es inmutable. El saldo complementario de sobregiro (descrito abajo) siempre usa direction=debit.

Configuración del saldo

El objeto settings de un saldo controla el comportamiento del sobregiro:

Campo	Tipo	Descripción
`allowOverdraft`	boolean	Habilita el sobregiro en este saldo
`overdraftLimitEnabled`	boolean	Controla si se aplica un límite
`overdraftLimit`	string (decimal)	Monto máximo de sobregiro. Obligatorio cuando `overdraftLimitEnabled` es `true`. Debe ser mayor que `0`.

El objeto settings también lleva balanceScope. Identifica un saldo transaccional (el predeterminado) o un saldo interno gestionado por el sistema, como el complementario de sobregiro. Puedes definir balanceScope: "transactional" cuando creas o actualizas un saldo público. No puedes definir balanceScope: "internal" a través de la API pública.

Modos de configuración

Sin sobregiro (predeterminado)

El comportamiento estándar. Midaz rechaza cualquier débito que supere el saldo disponible.

{
  "key": "checking",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": false
  }
}

Sobregiro ilimitado

La posición derivada puede quedar negativa sin tope. El saldo Available persistido permanece en 0, mientras Midaz registra el déficit como OverdraftUsed. Usa esto para cuentas de liquidación o pool, donde las posiciones negativas son normales y las concilias de forma externa.

{
  "key": "settlement",
  "assetCode": "USD",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": false
  }
}

Sobregiro limitado

La posición derivada puede quedar negativa hasta un límite definido. El saldo Available persistido permanece en 0, mientras Midaz registra el déficit como OverdraftUsed. Este es el modo más común para productos de crédito al consumo.

{
  "key": "checking",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "5000.00"
  }
}

Cuando overdraftLimitEnabled es true, debes definir overdraftLimit como una cadena decimal positiva. Si lo omites o lo defines como "0", Midaz devuelve el error 0172 - ErrInvalidBalanceSettings.

Cómo funciona el sobregiro

División de la operación

Cuando una transacción de débito supera los fondos disponibles, Midaz divide la operación automáticamente:

El débito consume todo el Available restante y lo deja en 0.
Midaz acumula el exceso como OverdraftUsed en el saldo principal.
Si Midaz encuentra el saldo interno "overdraft" (descrito abajo), crea una operación complementaria. Esta operación registra el pasivo como un débito de partida doble. Si no encuentra ese saldo, Midaz omite la operación complementaria. El saldo principal igual acumula OverdraftUsed.

Ejemplo: el saldo tiene Available = 300. Llega un débito de 500.

Paso	Available	OverdraftUsed	Descripción
Antes	300	0	Estado normal
Después	0	200	300 consumidos de Available, 200 acumulados como sobregiro

La transacción se completa como una sola operación atómica. Quien llama no necesita manejar la división. Midaz lo hace automáticamente.

Si configuras un límite, Midaz compara el OverdraftUsed resultante con overdraftLimit antes de procesar la transacción. Si el resultado supera el límite, Midaz rechaza la transacción con el error 0167 - ErrOverdraftLimitExceeded.

Pago automático (división de devolución)

Cuando llega un crédito y OverdraftUsed > 0, Midaz prioriza el pago:

Midaz aplica el crédito primero a OverdraftUsed y reduce la deuda.
Cualquier monto restante después de que OverdraftUsed llega a 0 va a Available.
Si Midaz encuentra el saldo interno "overdraft", una operación complementaria en él registra el pago. Si no encuentra ese saldo, Midaz omite la operación complementaria. El crédito igual paga OverdraftUsed en el saldo principal.

Ejemplo: OverdraftUsed = 200, Available = 0. Llega un crédito de 350.

Paso	Available	OverdraftUsed	Descripción
Antes	0	200	Sobregiro activo
Después	150	0	200 pagados, 150 van a Available

El pago es automático. No puedes omitirlo. Midaz reduce las posiciones de sobregiro lo antes posible, lo que mantiene el saldo sano.

Transacciones pendientes y sobregiro

Una transacción PENDING crea una retención. No consume sobregiro. Si una retención superara Available, Midaz rechaza la transacción con el error 0018 - Insufficient Funds Error. La retención rechazada no cambia Available, OnHold ni OverdraftUsed. Cuando cancelas una transacción pendiente, Midaz libera su retención. Una transacción pendiente creada por una versión anterior de Midaz ya puede llevar sobregiro. Midaz igual revierte ese estado heredado de forma correcta durante la cancelación.

Posición

Cada respuesta de saldo incluye un bloque position calculado. Da una vista en tiempo real del estado del saldo:

Campo	Descripción
`available`	El `position.available` derivado. Puede ser negativo cuando el saldo persistido tiene `Available = 0` y `OverdraftUsed > 0`.
`onHold`	Refleja `Balance.OnHold` — fondos reservados por operaciones pendientes.
`overdraftLimitAvailable`	Margen de sobregiro restante, no negativo. Es `"0"` cuando un límite configurado se usa por completo y se omite cuando el sobregiro es ilimitado.

No guardes en caché el bloque position para fines contables. Midaz nunca lo persiste. Calcula el bloque en el momento de la consulta a partir del estado actual del saldo.

Saldo complementario

Cuando actualizas un saldo para definir allowOverdraft como true por primera vez, Midaz aprovisiona de forma automática un saldo complementario en la misma cuenta. El saldo complementario registra el lado del pasivo de la partida doble. Midaz lo crea una vez por cuenta y lo reutiliza en cada disposición y pago de sobregiro.

Propiedad	Valor	Por qué
`key`	`"overdraft"`	Clave reservada del sistema
`direction`	`debit`	El complementario registra un pasivo — los débitos lo aumentan, los créditos lo reducen
`scope`	`internal`	Bloquea operaciones directas de usuario
`allowSending`	`true`	Obligatorio para operaciones DEBIT en el complementario (disposiciones de sobregiro)
`allowReceiving`	`true`	Obligatorio para operaciones CREDIT en el complementario (pagos de sobregiro)

Este saldo está totalmente 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 correcto de partida doble, de modo que el ledger permanece balanceado.

El valor scope: "internal" bloquea las operaciones directas de usuario, sin importar los indicadores de permiso anteriores. Midaz rechaza cualquier operación directa en este saldo con el error 0168 - ErrDirectOperationOnInternalBalance. El complementario se mueve solo mediante el enriquecimiento de sobregiro que ejecuta el sistema.

Estado del sobregiro en las operaciones

Cada operación expone el estado del sobregiro en los bloques balance y balanceAfter. El campo overdraftUsed registra el sobregiro consumido antes y después de la operación. Esto da un registro de auditoría completo sin una consulta de saldo aparte. Para las operaciones que no tocan el sobregiro, ambos valores son "0". Las operaciones complementarias gestionadas por el sistema en el saldo "overdraft" usan type: "OVERDRAFT" (en mayúsculas). El campo direction lleva el ciclo de vida: "debit" para una disposición, "credit" para un pago.

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

{
  "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 principal como la complementaria comparten el mismo par overdraftUsed de antes y después. Reflejan la transición de sobregiro del saldo principal, de modo que el ciclo de vida es visible desde cualquiera de las dos filas. La columna interna snapshot de tipo JSONB en la tabla operations guarda los mismos valores para indexación y reconstrucción histórica. Esta columna no forma parte del formato JSON público. En su lugar, los valores aparecen en balance.overdraftUsed y balanceAfter.overdraftUsed. Midaz puede agregar al snapshot contexto futuro generado por el sistema sin romper el contrato público.

Las operaciones complementarias heredan el routeId de la operación principal. Para cada ruta con capacidad de sobregiro, configura las rúbricas debit y credit de la entrada overdraft. Midaz exige ambas. Midaz resuelve routeCode y routeDescription a partir de la rúbrica que coincide con la dirección del complementario.

Eventos de sobregiro

En tiempo de ejecución, Midaz habilita la publicación de eventos de sobregiro a menos que RABBITMQ_OVERDRAFT_EVENTS_ENABLED sea explícitamente false. El entorno de ejemplo incluido define el indicador como false. Un despliegue que parte de ese ejemplo no publica eventos de sobregiro hasta que lo definas como true.

# The bundled example disables overdraft-event publication. Runtime enables it unless the flag is explicitly false.
RABBITMQ_OVERDRAFT_EVENTS_ENABLED=false

# Optional: route overdraft events to a dedicated exchange.
# When unset, the broker's default exchange is used.
RABBITMQ_OVERDRAFT_EVENTS_EXCHANGE=transaction.overdraft_events.exchange

Tipos de evento

Evento	Descripción
`overdraft.drawn`	Se consumió el sobregiro — OverdraftUsed aumentó
`overdraft.repaid`	El sobregiro se pagó de forma parcial — OverdraftUsed disminuyó pero sigue > 0
`overdraft.cleared`	El sobregiro se pagó por completo — OverdraftUsed llegó a 0

Ejemplo de payload del evento

{
  "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",
    "timestamp": "2026-04-28T14:30:00.000000Z"
  }
}

Usa los eventos de sobregiro para disparar workflows downstream: acumulación de intereses, notificaciones a clientes, alertas de riesgo o procesos de cobro automáticos.

Casos de uso

Sobregiro en cuenta corriente (cheque especial)

Crédito al consumo clásico. La posición derivada de la cuenta corriente puede quedar negativa hasta un límite preaprobado. El saldo Available persistido permanece en 0 y el monto pendiente se registra como OverdraftUsed.

{
  "key": "checking",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "2000.00"
  }
}

Buy Now, Pay Later (BNPL)

Un proveedor BNPL emite un crédito de compra contra el saldo del cliente. Esto crea una posición de sobregiro inmediata que el cliente paga en cuotas.

{
  "key": "bnpl",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "10000.00"
  }
}

Acceso al salario devengado / Adelanto de salario

Los empleados disponen contra ingresos futuros. Los créditos de nómina dejan en cero la posición de sobregiro cuando llegan.

{
  "key": "salary-advance",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "3000.00"
  }
}

Adelanto de cuentas por cobrar de marketplace

Los vendedores reciben un adelanto sobre cuentas por cobrar futuras. Midaz paga el sobregiro de forma automática a medida que llegan las liquidaciones de ventas.

{
  "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 quedan negativas de forma rutinaria durante el procesamiento intradía. El sobregiro ilimitado evita rechazos artificiales mientras concilias la posición al cierre del día.

{
  "key": "settlement-pool",
  "assetCode": "USD",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": false
  }
}

Líneas de crédito revolvente (B2B)

Las empresas disponen y pagan desde una línea de crédito revolvente. El límite de sobregiro representa la línea de crédito total.

{
  "key": "credit-line",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "500000.00"
  }
}

Prefinanciamiento de seguros

Las aseguradoras prefinancian siniestros antes de que cierren los ciclos de cobro de primas. El sobregiro cubre la brecha entre el pago y el cobro.

{
  "key": "claims-prefin",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "100000.00"
  }
}

Programas de fidelidad (puntos adelantados)

Los clientes canjean puntos antes de ganarlos. El sobregiro registra el déficit de puntos y queda en cero a medida que los clientes acumulan nuevos puntos.

{
  "key": "loyalty-points",
  "assetCode": "POINTS",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "10000"
  }
}

Reglas de protección

El sobregiro introduce varias restricciones de inmutabilidad y de acceso para mantener la integridad del ledger:

La dirección es inmutable. Una vez que defines el direction de un saldo en la creación, no puedes cambiarlo.
Los saldos internos bloquean las escrituras. No puedes crear, eliminar ni actualizar el saldo complementario "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 complementario gestionado por el sistema.
Deshabilitar el sobregiro conserva la deuda pendiente. Puedes definir allowOverdraft: false mientras OverdraftUsed > 0 para bloquear disposiciones futuras, mientras los créditos entrantes igual pagan la deuda existente.
El límite no puede bajar del uso. Si OverdraftUsed = 200, Midaz rechaza overdraftLimit: "100" con el error 0173, así que primero paga hasta quedar por debajo del nuevo techo o define un límite más alto.
Concurrencia optimista. Las actualizaciones de saldo usan control de concurrencia por versión, y Midaz rechaza una escritura desactualizada con el error 0174. Reintenta con la versión más reciente.

Para el catálogo completo de códigos de error relacionados con el sobregiro (0167–0175), consulta la lista de errores de Midaz.

Próximos pasos

Conoce los Saldos, la base sobre la que se construye el sobregiro.
Entiende las Operaciones para rastrear cómo aparecen las divisiones de sobregiro en el ledger.
Configura el Event Publisher para consumir eventos del ciclo de vida del sobregiro.
Explora las Transacciones para el panorama completo de la contabilidad de partida doble en Midaz.

Midaz Core

CRM

Fees

Sobregiro de Saldo

Dirección del saldo

Configuración del saldo

Modos de configuración

Sin sobregiro (predeterminado)

Sobregiro ilimitado

Sobregiro limitado

Cómo funciona el sobregiro

División de la operación

Pago automático (división de devolución)

Transacciones pendientes y sobregiro

Posición

Saldo complementario

Estado del sobregiro en las operaciones

Eventos de sobregiro

Tipos de evento

Ejemplo de payload del evento

Casos de uso

Sobregiro en cuenta corriente (cheque especial)

Buy Now, Pay Later (BNPL)

Acceso al salario devengado / Adelanto de salario

Adelanto de cuentas por cobrar de marketplace

Cuentas de liquidación / pool (modo ilimitado)

Líneas de crédito revolvente (B2B)

Prefinanciamiento de seguros

Programas de fidelidad (puntos adelantados)

Reglas de protección

Próximos pasos

​Dirección del saldo

​Configuración del saldo

​Modos de configuración

​Sin sobregiro (predeterminado)

​Sobregiro ilimitado

​Sobregiro limitado

​Cómo funciona el sobregiro

​División de la operación

​Pago automático (división de devolución)

​Transacciones pendientes y sobregiro

​Posición

​Saldo complementario

​Estado del sobregiro en las operaciones

​Eventos de sobregiro

​Tipos de evento

​Ejemplo de payload del evento

​Casos de uso

​Sobregiro en cuenta corriente (cheque especial)

​Buy Now, Pay Later (BNPL)

​Acceso al salario devengado / Adelanto de salario

​Adelanto de cuentas por cobrar de marketplace

​Cuentas de liquidación / pool (modo ilimitado)

​Líneas de crédito revolvente (B2B)

​Prefinanciamiento de seguros

​Programas de fidelidad (puntos adelantados)

​Reglas de protección

​Próximos pasos

Dirección del saldo

Configuración del saldo

Modos de configuración

Sin sobregiro (predeterminado)

Sobregiro ilimitado

Sobregiro limitado

Cómo funciona el sobregiro

División de la operación

Pago automático (división de devolución)

Transacciones pendientes y sobregiro

Posición

Saldo complementario

Estado del sobregiro en las operaciones

Eventos de sobregiro

Tipos de evento

Ejemplo de payload del evento

Casos de uso

Sobregiro en cuenta corriente (cheque especial)

Buy Now, Pay Later (BNPL)

Acceso al salario devengado / Adelanto de salario

Adelanto de cuentas por cobrar de marketplace

Cuentas de liquidación / pool (modo ilimitado)

Líneas de crédito revolvente (B2B)

Prefinanciamiento de seguros

Programas de fidelidad (puntos adelantados)

Reglas de protección

Próximos pasos