Saltar al contenido principal

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.

El Balance Overdraft permite que un saldo sea debitado más allá de sus fondos disponibles sin dejar que el saldo primario quede negativo. El déficit se rastrea como OverdraftUsed, y Midaz maneja automáticamente el split de la operación entre el saldo primario y un saldo companion interno. Cuando llegan créditos, el reembolso se prioriza — el overdraft se paga primero, y cualquier excedente va al Available. Este mecanismo soporta líneas de crédito, BNPL, cuentas de liquidación, anticipo salarial y cualquier escenario donde se requieren 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ónComportamientoUso típico
credit (por defecto)Débito disminuye, crédito aumentaSaldos tipo activo — cuentas corrientes, billeteras, reservas
debitDébito aumenta, crédito disminuyeSaldos tipo pasivo — préstamos, seguimiento de overdraft, cuentas por pagar
La dirección se define en el momento de la creación y 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:
CampoTipoDescripción
allowOverdraftbooleanHabilita overdraft en este saldo
overdraftLimitEnabledbooleanDefine si se impone un límite
overdraftLimitstring (decimal)Monto máximo de overdraft. Requerido cuando overdraftLimitEnabled es true. Debe ser mayor que 0.
Un campo balanceScope también existe dentro de settings, pero es gestionado por el sistema — distingue 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. Cualquier débito que exceda el saldo disponible es rechazado. 
{
  "key": "checking",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": false
  }
}

​
Overdraft ilimitado

El saldo puede quedar negativo sin tope. Útil para cuentas de liquidación o pool donde las posiciones negativas son normales y se concilian 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, overdraftLimit es obligatorio y debe ser una cadena decimal positiva. Omitirlo o establecerlo en "0" 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, fijándolo en 0.
  2. El excedente se acumula como OverdraftUsed en el saldo primario.
  3. Se crea una operación companion en el saldo interno "overdraft" (descrito a continuación), registrando el pasivo como un débito de partida doble.
Ejemplo: Saldo con Available = 300. Llega un débito de 500.
PasoAvailableOverdraftUsedDescripción
Antes3000Estado normal
Después0200300 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 un límite está configurado, Midaz valida que el OverdraftUsed resultante no exceda el overdraftLimit antes de procesar. Si lo excede, la transacción es rechazada con el error 0167 - ErrOverdraftLimitExceeded.

​
Reembolso automático (refund split)

Cuando llega un crédito y OverdraftUsed > 0, Midaz prioriza el reembolso:
  1. El crédito se aplica al OverdraftUsed primero, reduciendo 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.
PasoAvailableOverdraftUsedDescripción
Antes0200Overdraft activo
Después1500200 reembolsados, 150 van al Available
El reembolso es automático y no puede ser omitido. Esto asegura que las posiciones de overdraft siempre se reduzcan lo antes posible, manteniendo el saldo saludable.

​
Cancelación de transacción pendiente con overdraft

Cuando una transacción PENDING que consumió overdraft es cancelada, Midaz mantiene el saldo companion sincronizado con el primario:
  1. La cancelación revierte el hold original y cualquier overdraft consumido durante la ventana pending — OverdraftUsed regresa al valor previo a la transacción pending.
  2. Una operación CREDIT companion en el saldo "overdraft" reduce el pasivo por el monto exacto que fue consumido, reembolsándolo.
  3. Tanto la cancelación primaria como el crédito companion se aplican en el mismo batch atómico, por lo que el saldo primario y el companion nunca se desincronizan — incluso si la cancelación llega en una ráfaga de alta concurrencia.
El motor llama a esta garantía de movimiento sincronizado companion parity. Se aplica simétricamente 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 que proporciona una vista en tiempo real del estado del saldo:
CampoDescripción
availableBalance.Available menos OverdraftUsed. Puede ser negativo cuando el overdraft está activo.
onHoldRefleja Balance.OnHold — fondos reservados por operaciones pendientes.
overdraftLimitAvailableMargen de overdraft restante. "0" cuando el overdraft está deshabilitado. Omitido cuando es ilimitado. Decimal positivo cuando un límite está configurado.
El bloque position nunca se persiste — siempre se computa en el momento de la consulta a partir del estado actual del saldo. No lo almacene en caché con fines contables.

​
Saldo companion

La primera vez en que allowOverdraft pasa a true en un saldo — sea en la creación o vía update — Midaz auto-aprovisiona un saldo companion bajo la misma cuenta para registrar el lado del pasivo en la partida doble. Se crea una sola vez por cuenta y se reutiliza en cada draw y reembolso de overdraft.
PropiedadValorPor qué
key"overdraft"Clave reservada del sistema
directiondebitEl companion rastrea un pasivo — los débitos lo aumentan, los créditos lo reducen
scopeinternalBloquea operaciones directas de usuarios
allowSendingtrueNecesario para operaciones DEBIT en el companion (consumo de overdraft)
allowReceivingtrueNecesario para operaciones CREDIT en el companion (reembolsos de overdraft)
Este saldo es completamente gestionado por el sistema:
  • No puede ser creado, modificado o eliminado a través de la API pública.
  • La clave "overdraft" está reservada — intentar crear un saldo con esta clave devuelve el error 0170 - ErrReservedBalanceKey.
  • Refleja el pasivo como un registro de partida doble, asegurando que el ledger se mantenga equilibrado.
El valor scope: "internal" controla el acceso directo de usuarios independientemente de las flags de permiso anteriores — cualquier intento de operar directamente sobre este saldo es rechazado 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 directamente en los bloques balance y balanceAfter. El campo overdraftUsed captura cuánto overdraft fue consumido antes y después de la operación — proporcionando un rastro de auditoría completo sin necesidad de 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" se exponen con type: "OVERDRAFT" (en mayúsculas). El campo direction lleva la semántica del 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"
  }
}
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, haciendo el ciclo de vida visible desde cualquiera de los lados. La columna interna snapshot (JSONB) en la tabla operations almacena los mismos valores para indexación y reconstrucción histórica; no forma parte del JSON público y aparece en balance.overdraftUsed y balanceAfter.overdraftUsed. Contexto adicional generado por el sistema puede agregarse al snapshot sin romper el contrato público.
Las operaciones companion heredan routeId, routeCode y routeDescription de la operación primaria que las generó. Esto mantiene ambas piernas de la partida doble bajo la misma rúbrica contable — las clasificaciones del plan de cuentas fluyen desde la primaria al companion automáticamente, así reportes filtrados por route muestran ambos lados del overdraft.

​
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 — establezca 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

EventoDescripción
overdraft.drawnSe consumió overdraft — OverdraftUsed aumentó
overdraft.repaidSe reembolsó parcialmente el overdraft — OverdraftUsed disminuyó pero permanece > 0
overdraft.clearedSe 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"
  }
}
Utilice 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

Crédito clásico al consumidor. El saldo de la cuenta corriente puede quedar negativo hasta un límite preaprobado, con intereses acumulados 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, creando una posición de overdraft inmediata que se 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. La posición de overdraft se liquida cuando llegan los créditos de nómina. 
{
  "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. El overdraft se paga 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 la posición se concilia 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, pagado conforme se 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 definida en la creación, la direction de un saldo no puede cambiarse.
  • Los saldos internos son de solo lectura. El saldo companion "overdraft" no puede ser creado, eliminado ni actualizado a través de la API pública. Las solicitudes PATCH sobre saldos internos son rechazadas con el error 0175.
  • Claves reservadas. La clave "overdraft" está reservada para el saldo companion gestionado por el sistema.
  • Deshabilitar overdraft preserva la deuda pendiente. Establecer allowOverdraft: false mientras OverdraftUsed > 0 está permitido — la flag bloquea nuevos retiros vía overdraft, mientras que los créditos entrantes siguen pagando la deuda existente hasta llegar a cero.
  • El límite no puede bajar del uso. Si OverdraftUsed = 200, establecer overdraftLimit: "100" es rechazado (error 0173) — pague el overdraft por debajo del nuevo techo primero, o establezca un límite mayor.
  • Concurrencia optimista. Las actualizaciones de saldo usan control de concurrencia basado en versión. Las escrituras obsoletas son rechazadas con el error 0174 — reintente con la versión más reciente.
Para el catálogo completo de los códigos de error relacionados con overdraft (0167–0175), consulte la Lista de errores de Midaz.

​
Próximos pasos

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