Overdraft de Saldo

O Balance Overdraft permite que um saldo seja debitado além dos fundos disponíveis sem deixar o saldo primário ficar negativo. O déficit é rastreado como OverdraftUsed, e o Midaz trata automaticamente o split da operação entre o saldo primário e um saldo companion interno. Quando créditos chegam, o reembolso é priorizado — o overdraft é quitado primeiro, e qualquer excedente vai para o Available. Esse mecanismo suporta linhas de crédito, BNPL, contas de liquidação, antecipação salarial e qualquer cenário onde posições negativas controladas são necessárias.

Direção do saldo

Os saldos possuem um campo direction que define como débitos e créditos afetam o saldo:

Direção	Comportamento	Uso típico
`credit` (padrão)	Débito diminui, crédito aumenta	Saldos tipo ativo — contas correntes, carteiras, reservas
`debit`	Débito aumenta, crédito diminui	Saldos tipo passivo — empréstimos, rastreamento de overdraft, contas a pagar

A direção é definida no momento da criação e é imutável. O saldo companion de overdraft (descrito abaixo) sempre usa direction=debit.

Configurações do saldo

O objeto settings no saldo controla o comportamento de overdraft:

Campo	Tipo	Descrição
`allowOverdraft`	boolean	Habilita overdraft neste saldo
`overdraftLimitEnabled`	boolean	Define se um limite é imposto
`overdraftLimit`	string (decimal)	Valor máximo de overdraft. Obrigatório quando `overdraftLimitEnabled` é `true`. Deve ser maior que `0`.

Um campo balanceScope também existe dentro de settings, mas é gerenciado pelo sistema — ele distingue saldos internos (como o companion de overdraft) de saldos transacionais. Você não define este campo diretamente.

Modos de configuração

Sem overdraft (padrão)

O comportamento padrão. Qualquer débito que exceda o saldo disponível é rejeitado.

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

Overdraft ilimitado

O saldo pode ficar negativo sem teto. Útil para contas de liquidação ou pool onde posições negativas são normais e reconciliadas externamente.

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

Overdraft limitado

O saldo pode ficar negativo até um limite definido. O modo mais comum para produtos de crédito ao consumidor.

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

Quando overdraftLimitEnabled é true, overdraftLimit é obrigatório e deve ser uma string decimal positiva. Omiti-lo ou definir como "0" retorna o erro 0172 - ErrInvalidBalanceSettings.

Como o overdraft funciona

Split de operação

Quando uma transação de débito excede os fundos disponíveis, o Midaz automaticamente divide a operação:

O débito consome todo o Available restante, fixando-o em 0.
O excedente é acumulado como OverdraftUsed no saldo primário.
Uma operação companion é criada no saldo interno "overdraft" (descrito abaixo), registrando o passivo como um débito de partida dobrada.

Exemplo: Saldo com Available = 300. Um débito de 500 chega.

Etapa	Available	OverdraftUsed	Descrição
Antes	300	0	Estado normal
Depois	0	200	300 consumidos do Available, 200 acumulados como overdraft

A transação é processada como uma única operação atômica. O chamador não precisa tratar o split — o Midaz faz automaticamente.

Se um limite está configurado, o Midaz valida que o OverdraftUsed resultante não excede o overdraftLimit antes de processar. Se exceder, a transação é rejeitada com o erro 0167 - ErrOverdraftLimitExceeded.

Reembolso automático (refund split)

Quando um crédito chega e OverdraftUsed > 0, o Midaz prioriza o reembolso:

O crédito é aplicado ao OverdraftUsed primeiro, reduzindo a dívida.
Qualquer valor remanescente após o OverdraftUsed atingir 0 vai para o Available.
Uma operação companion no saldo "overdraft" registra o reembolso.

Exemplo: OverdraftUsed = 200, Available = 0. Um crédito de 350 chega.

Etapa	Available	OverdraftUsed	Descrição
Antes	0	200	Overdraft ativo
Depois	150	0	200 quitados, 150 vão para o Available

O reembolso é automático e não pode ser contornado. Isso garante que posições de overdraft sejam sempre reduzidas o mais cedo possível, mantendo o saldo saudável.

Cancelamento de transação pendente com overdraft

Quando uma transação PENDING que consumiu overdraft é cancelada, o Midaz mantém o saldo companion sincronizado com o primário:

O cancelamento reverte o hold original e qualquer overdraft consumido durante a janela pending — OverdraftUsed retorna ao valor anterior à transação pending.
Uma operação CREDIT companion no saldo "overdraft" reduz o passivo no valor exato que foi consumido, quitando-o.
Tanto o cancelamento primário quanto o crédito companion são aplicados no mesmo batch atômico, então o saldo primário e o companion nunca saem de sincronia — mesmo que o cancelamento chegue em uma rajada de alta vazão.

O engine chama essa garantia de movimentação em sincronia de companion parity. Ela se aplica simetricamente às fases de hold, commit e cancel de qualquer transação pending que toque o overdraft.

Position

Toda resposta de saldo inclui um bloco computado position que fornece uma visão em tempo real do estado do saldo:

Campo	Descrição
`available`	`Balance.Available` menos `OverdraftUsed`. Pode ser negativo quando o overdraft está ativo.
`onHold`	Espelha `Balance.OnHold` — fundos reservados por operações pendentes.
`overdraftLimitAvailable`	Headroom restante de overdraft. `"0"` quando overdraft está desabilitado. Omitido quando ilimitado. Decimal positivo quando um limite está configurado.

O bloco position nunca é persistido — é sempre computado no momento da consulta a partir do estado atual do saldo. Não faça cache dele para fins contábeis.

Saldo companion

Na primeira vez em que allowOverdraft passa para true em um saldo — seja na criação, seja num update — o Midaz auto-provisiona um saldo companion sob a mesma conta para registrar o lado do passivo na partida dobrada. Ele é criado uma única vez por conta e reutilizado em cada draw e quitação de overdraft.

Propriedade	Valor	Por quê
`key`	`"overdraft"`	Chave reservada do sistema
`direction`	`debit`	O companion rastreia um passivo — débitos o aumentam, créditos o reduzem
`scope`	`internal`	Bloqueia operações diretas de usuários
`allowSending`	`true`	Necessário para operações DEBIT no companion (consumo de overdraft)
`allowReceiving`	`true`	Necessário para operações CREDIT no companion (quitação de overdraft)

Este saldo é totalmente gerenciado pelo sistema:

Não pode ser criado, modificado ou excluído pela API pública.
A chave "overdraft" é reservada — tentar criar um saldo com esta chave retorna o erro 0170 - ErrReservedBalanceKey.
Ele espelha o passivo como um registro de partida dobrada, garantindo que o ledger permaneça equilibrado.

O valor scope: "internal" controla o acesso direto de usuários independentemente das flags de permissão acima — qualquer tentativa de operar diretamente neste saldo é rejeitada com o erro 0168 - ErrDirectOperationOnInternalBalance. O companion só se movimenta via enrichment de overdraft conduzido pelo sistema.

Estado de overdraft nas operações

Toda operação expõe o estado de overdraft diretamente nos blocos balance e balanceAfter. O campo overdraftUsed captura quanto de overdraft foi consumido antes e depois da operação — fornecendo uma trilha de auditoria completa sem precisar de uma consulta separada ao saldo. Para operações que não tocam o overdraft, ambos os valores são "0". Operações companion gerenciadas pelo sistema no saldo "overdraft" são expostas com type: "OVERDRAFT" (em maiúsculas). O campo direction carrega a semântica do ciclo de vida: "debit" para um draw, "credit" para um 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 a operação primária quanto a companion compartilham o mesmo par overdraftUsed antes/depois — ambas espelham a transição de overdraft do saldo primário, tornando o ciclo de vida visível a partir de qualquer um dos lados. A coluna interna snapshot (JSONB) na tabela operations armazena os mesmos valores para indexação e reconstrução histórica; ela não faz parte do JSON público e aparece em balance.overdraftUsed e balanceAfter.overdraftUsed. Contexto adicional gerado pelo sistema pode ser adicionado ao snapshot sem quebrar o contrato público.

Operações companion herdam routeId, routeCode e routeDescription da operação primária que as gerou. Isso mantém ambas as pernas da partida dobrada sob a mesma rubrica contábil — as classificações do plano de contas fluem do primário para o companion automaticamente, então relatórios filtrados por route mostram os dois lados do overdraft.

Eventos de overdraft

O Midaz publica eventos de ciclo de vida no RabbitMQ quando o estado de overdraft muda. A publicação está habilitada por padrão — defina a flag como "false" para desabilitar.

# Desabilita a publicação de eventos de overdraft (padrão: habilitado).
RABBITMQ_OVERDRAFT_EVENTS_ENABLED=false

# Opcional: roteia os eventos de overdraft para uma exchange dedicada.
# Quando não definido, a exchange padrão do broker é usada.
RABBITMQ_OVERDRAFT_EVENTS_EXCHANGE=transaction.overdraft_events.exchange

Tipos de evento

Evento	Descrição
`overdraft.drawn`	Overdraft foi consumido — OverdraftUsed aumentou
`overdraft.repaid`	Overdraft foi parcialmente reembolsado — OverdraftUsed diminuiu mas permanece > 0
`overdraft.cleared`	Overdraft foi totalmente quitado — OverdraftUsed atingiu 0

Exemplo de payload do 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"
  }
}

Use os eventos de overdraft para acionar workflows downstream — acúmulo de juros, notificações ao cliente, alertas de risco ou processos de cobrança automática.

Casos de uso

Cheque especial (overdraft de conta corrente)

Crédito clássico ao consumidor. O saldo da conta corrente pode ficar negativo até um limite pré-aprovado, com juros acumulados sobre o valor em aberto.

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

Buy Now, Pay Later (BNPL)

Um provedor de BNPL emite um crédito de compra contra o saldo do cliente, criando uma posição de overdraft imediata que é quitada em parcelas.

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

Antecipação salarial (Earned Wage Access)

Funcionários sacam contra rendimentos futuros. A posição de overdraft é liquidada quando os créditos de folha de pagamento chegam.

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

Antecipação de recebíveis de marketplace

Vendedores recebem uma antecipação sobre recebíveis futuros. O overdraft é quitado automaticamente conforme as liquidações de vendas chegam.

{
  "key": "receivables",
  "assetCode": "BRL",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "50000.00"
  }
}

Contas de liquidação / Pool (modo ilimitado)

Contas de liquidação e pool rotineiramente ficam negativas durante o processamento intradiário. Overdraft ilimitado evita rejeições artificiais enquanto a posição é conciliada no fim do dia.

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

Linhas de crédito rotativo (B2B)

Empresas sacam e quitam de uma facilidade de crédito rotativo. O limite de overdraft representa a linha de crédito total.

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

Pré-financiamento de seguros

Seguradoras pré-financiam sinistros antes do fechamento dos ciclos de cobrança de prêmios. O overdraft cobre o gap entre pagamento e arrecadação.

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

Programas de fidelidade (pontos antecipados)

Clientes resgatam pontos antes de acumulá-los. O overdraft rastreia o déficit de pontos, quitado conforme novos pontos são acumulados.

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

Regras de proteção

O overdraft introduz diversas restrições de imutabilidade e acesso para manter a integridade do ledger:

Direção é imutável. Uma vez definida na criação, a direction de um saldo não pode ser alterada.
Saldos internos são somente leitura. O saldo companion "overdraft" não pode ser criado, excluído ou atualizado pela API pública. Solicitações PATCH em saldos internos são rejeitadas com o erro 0175.
Chaves reservadas. A chave "overdraft" é reservada para o saldo companion gerenciado pelo sistema.
Desabilitar overdraft preserva a dívida pendente. Definir allowOverdraft: false enquanto OverdraftUsed > 0 é permitido — a flag bloqueia novas saídas via overdraft, enquanto créditos recebidos continuam quitando a dívida existente até zerá-la.
Limite não pode cair abaixo do uso. Se OverdraftUsed = 200, definir overdraftLimit: "100" é rejeitado (erro 0173) — quite o overdraft abaixo do novo teto primeiro, ou defina um limite maior.
Concorrência otimista. Atualizações de saldo usam controle de concorrência baseado em versão. Escritas obsoletas são rejeitadas com o erro 0174 — tente novamente com a versão mais recente.

Para o catálogo completo dos códigos de erro relacionados a overdraft (0167–0175), consulte a Lista de erros do Midaz.

Próximos passos

Conheça os Saldos — a base sobre a qual o overdraft é construído.
Entenda as Operações para rastrear como os splits de overdraft aparecem no ledger.
Configure o Event Publisher para consumir eventos de ciclo de vida do overdraft.
Explore as Transações para a visão completa da contabilidade de partida dobrada no Midaz.

Primeiros passos

Entendendo o Midaz

Instalação e implantação

Trabalhando com o Midaz

Boas práticas

SDKs e bibliotecas

CRM

Ajuda e suporte

Overdraft de Saldo

Direção do saldo

Configurações do saldo

Modos de configuração

Sem overdraft (padrão)

Overdraft ilimitado

Overdraft limitado

Como o overdraft funciona

Split de operação

Reembolso automático (refund split)

Cancelamento de transação pendente com overdraft

Position

Saldo companion

Estado de overdraft nas operações

Eventos de overdraft

Tipos de evento

Exemplo de payload do evento

Casos de uso

Cheque especial (overdraft de conta corrente)

Buy Now, Pay Later (BNPL)

Antecipação salarial (Earned Wage Access)

Antecipação de recebíveis de marketplace

Contas de liquidação / Pool (modo ilimitado)

Linhas de crédito rotativo (B2B)

Pré-financiamento de seguros

Programas de fidelidade (pontos antecipados)

Regras de proteção

Próximos passos

Primeiros passos

Entendendo o Midaz

Instalação e implantação

Trabalhando com o Midaz

Boas práticas

SDKs e bibliotecas

CRM

Ajuda e suporte

Documentation Index

​Direção do saldo

​Configurações do saldo

​Modos de configuração

​Sem overdraft (padrão)

​Overdraft ilimitado

​Overdraft limitado

​Como o overdraft funciona

​Split de operação

​Reembolso automático (refund split)

​Cancelamento de transação pendente com overdraft

​Position

​Saldo companion

​Estado de overdraft nas operações

​Eventos de overdraft

​Tipos de evento

​Exemplo de payload do evento

​Casos de uso

​Cheque especial (overdraft de conta corrente)

​Buy Now, Pay Later (BNPL)

​Antecipação salarial (Earned Wage Access)

​Antecipação de recebíveis de marketplace

​Contas de liquidação / Pool (modo ilimitado)

​Linhas de crédito rotativo (B2B)

​Pré-financiamento de seguros

​Programas de fidelidade (pontos antecipados)

​Regras de proteção

​Próximos passos

Direção do saldo

Configurações do saldo

Modos de configuração

Sem overdraft (padrão)

Overdraft ilimitado

Overdraft limitado

Como o overdraft funciona

Split de operação

Reembolso automático (refund split)

Cancelamento de transação pendente com overdraft

Position

Saldo companion

Estado de overdraft nas operações

Eventos de overdraft

Tipos de evento

Exemplo de payload do evento

Casos de uso

Cheque especial (overdraft de conta corrente)

Buy Now, Pay Later (BNPL)

Antecipação salarial (Earned Wage Access)

Antecipação de recebíveis de marketplace

Contas de liquidação / Pool (modo ilimitado)

Linhas de crédito rotativo (B2B)

Pré-financiamento de seguros

Programas de fidelidade (pontos antecipados)

Regras de proteção

Próximos passos