Overdraft de Saldo

O Balance Overdraft permite debitar um saldo além dos fundos disponíveis. O saldo primário nunca fica negativo. O Midaz rastreia o déficit como OverdraftUsed e divide a operação entre o saldo primário e um saldo companion interno. Quando créditos chegam, o Midaz quita o overdraft primeiro. Qualquer excedente vai para o Available. Esse mecanismo suporta linhas de crédito, BNPL, contas de liquidação, antecipação salarial e qualquer produto que precise de posições negativas controladas.

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	Contas correntes, carteiras, reservas
`debit`	Débito aumenta, crédito diminui	Empréstimos, rastreamento de overdraft, contas a pagar

Você define a direção no momento da criação. Ela é 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`.

O objeto settings também carrega um campo balanceScope gerenciado pelo sistema. Ele separa 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. O Midaz rejeita qualquer débito que exceda o saldo disponível.

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

Overdraft ilimitado

O saldo pode ficar negativo sem teto. Use isso para contas de liquidação ou pool, onde posições negativas são normais e você as reconcilia 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, você deve definir overdraftLimit como uma string decimal positiva. Se você omiti-lo ou defini-lo como "0", o Midaz 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 e o fixa em 0.
O Midaz acumula o excedente como OverdraftUsed no saldo primário.
O Midaz cria uma operação companion no saldo interno "overdraft" (descrito abaixo). Essa operação registra 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 você configurar um limite, o Midaz compara o OverdraftUsed resultante com o overdraftLimit antes de processar a transação. Se o resultado exceder o limite, o Midaz rejeita a transação com o erro 0167 - ErrOverdraftLimitExceeded.

Reembolso automático (refund split)

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

O Midaz aplica o crédito primeiro ao OverdraftUsed e reduz 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. Você não pode contorná-lo. O Midaz reduz as posições de overdraft o mais cedo possível, o que mantém o saldo saudável.

Cancelamento de transação pendente com overdraft

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

O cancelamento reverte o hold original e qualquer overdraft consumido durante a janela pending. OverdraftUsed retorna ao seu valor anterior ao hold.
Uma operação CREDIT companion no saldo "overdraft" reduz o passivo no valor exato consumido.
O Midaz aplica o cancelamento primário e o crédito companion no mesmo batch atômico. Os dois saldos nunca saem de sincronia.

O Midaz mantém o saldo companion sincronizado com o saldo primário. Isso vale para as 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. Ele 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.

Não faça cache do bloco position para fins contábeis. O Midaz nunca o persiste — ele computa o bloco no momento da consulta a partir do estado atual do saldo.

Saldo companion

Quando você atualiza um saldo para definir allowOverdraft como true pela primeira vez, o Midaz auto-provisiona um saldo companion sob a mesma conta. O saldo companion registra o lado do passivo na partida dobrada. O Midaz o cria uma única vez por conta e o reutiliza 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:

Você não pode criá-lo, modificá-lo ou excluí-lo pela API pública.
O Midaz reserva a chave "overdraft". Uma requisição que cria um saldo com esta chave retorna o erro 0170 - ErrReservedBalanceKey.
Ele espelha o passivo como um registro de partida dobrada, de modo que o ledger permanece equilibrado.

O valor scope: "internal" bloqueia as operações diretas de usuários, independentemente das flags de permissão acima. O Midaz rejeita qualquer operação direta neste saldo 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 nos blocos balance e balanceAfter. O campo overdraftUsed registra o overdraft consumido antes e depois da operação. Isso fornece uma trilha de auditoria completa sem 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" usam type: "OVERDRAFT" (em maiúsculas). O campo direction carrega o 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"
  }
}

{
  "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 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, então o ciclo de vida fica visível a partir de qualquer uma das linhas. A coluna interna snapshot (JSONB) na tabela operations armazena os mesmos valores para indexação e reconstrução histórica. Essa coluna não faz parte do JSON público. Em vez disso, os valores aparecem em balance.overdraftUsed e balanceAfter.overdraftUsed. O Midaz pode adicionar contexto futuro gerado pelo sistema ao snapshot sem quebrar o contrato público.

Operações companion herdam o routeId da operação primária. O Midaz resolve seu routeCode e routeDescription de forma independente a partir da rubrica overdraft da route. Se a route não tiver um lançamento de overdraft, ambos ficam vazios.

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. Os juros são 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. Isso cria uma posição de overdraft imediata que o cliente quita 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. Os créditos de folha de pagamento liquidam a posição de overdraft quando 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 Midaz quita o overdraft 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. O overdraft ilimitado evita rejeições artificiais enquanto você reconcilia a posição 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 e é quitado conforme os clientes acumulam novos pontos.

{
  "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. Depois de definir a direction de um saldo na criação, você não pode alterá-la.
Saldos internos bloqueiam escritas. Você não pode criar, excluir ou atualizar o saldo companion "overdraft" pela API pública — um PATCH retorna o erro 0175.
Chaves reservadas. O Midaz reserva a chave "overdraft" para o saldo companion gerenciado pelo sistema.
Desabilitar overdraft preserva a dívida pendente. Você pode definir allowOverdraft: false enquanto OverdraftUsed > 0 para bloquear novas saídas, enquanto os créditos recebidos continuam quitando a dívida existente.
Limite não pode cair abaixo do uso. Se OverdraftUsed = 200, o Midaz rejeita overdraftLimit: "100" com o erro 0173, então quite 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, e o Midaz rejeita uma escrita obsoleta 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.

Midaz Core

CRM

Fees

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

​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