Overdraft de Saldo

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.

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

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

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

El débito consume todo el Available restante y lo fija en 0.
Midaz acumula el excedente como OverdraftUsed en el saldo primario.
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:

Midaz aplica el crédito primero al OverdraftUsed y reduce la deuda.
Cualquier monto remanente después de que OverdraftUsed llegue a 0 va al Available.
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:

La cancelación revierte el hold original y cualquier overdraft consumido durante la ventana pending. OverdraftUsed regresa a su valor previo al hold.
Una operación CREDIT companion en el saldo "overdraft" reduce el pasivo por el monto exacto consumido.
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.

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

# 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

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

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

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

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

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

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

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

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

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

Próximos pasos

Conoce los Saldos — la base sobre la que se construye el overdraft.
Entiende las Operaciones para rastrear cómo los splits de overdraft aparecen en el ledger.
Configura el Event Publisher para consumir eventos del ciclo de vida del overdraft.
Explora las Transacciones para la visión completa de la contabilidad de partida doble en Midaz.

Midaz Core

CRM

Fees

Overdraft de Saldo

Dirección del saldo

Configuraciones del saldo

Modos de configuración

Sin overdraft (por defecto)

Overdraft ilimitado

Overdraft limitado

Cómo funciona el overdraft

Split de operación

Reembolso automático (refund split)

Cancelación de transacción pendiente con overdraft

Position

Saldo companion

Estado de overdraft en las operaciones

Eventos de overdraft

Tipos de evento

Ejemplo de payload del evento

Casos de uso

Sobregiro de cuenta corriente (cheque especial)

Buy Now, Pay Later (BNPL)

Anticipo salarial (Earned Wage Access)

Anticipo 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 fidelización (puntos anticipados)

Reglas de protección

Próximos pasos

​Dirección del saldo

​Configuraciones del saldo

​Modos de configuración

​Sin overdraft (por defecto)

​Overdraft ilimitado

​Overdraft limitado

​Cómo funciona el overdraft

​Split de operación

​Reembolso automático (refund split)

​Cancelación de transacción pendiente con overdraft

​Position

​Saldo companion

​Estado de overdraft en las operaciones

​Eventos de overdraft

​Tipos de evento

​Ejemplo de payload del evento

​Casos de uso

​Sobregiro de cuenta corriente (cheque especial)

​Buy Now, Pay Later (BNPL)

​Anticipo salarial (Earned Wage Access)

​Anticipo 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 fidelización (puntos anticipados)

​Reglas de protección

​Próximos pasos

Dirección del saldo

Configuraciones del saldo

Modos de configuración

Sin overdraft (por defecto)

Overdraft ilimitado

Overdraft limitado

Cómo funciona el overdraft

Split de operación

Reembolso automático (refund split)

Cancelación de transacción pendiente con overdraft

Position

Saldo companion

Estado de overdraft en las operaciones

Eventos de overdraft

Tipos de evento

Ejemplo de payload del evento

Casos de uso

Sobregiro de cuenta corriente (cheque especial)

Buy Now, Pay Later (BNPL)

Anticipo salarial (Earned Wage Access)

Anticipo 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 fidelización (puntos anticipados)

Reglas de protección

Próximos pasos