> ## 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. # Balance Overdraft > Habilite o Balance Overdraft controlado no Midaz com divisão automática de operações, prioridade de pagamento do crédito e limites para BNPL ou contas de liquidação. O Balance Overdraft permite debitar um saldo além dos fundos disponíveis. O saldo principal nunca fica negativo. O Midaz registra o déficit em **OverdraftUsed** e divide a operação entre o saldo principal e um saldo companheiro interno. Quando chegam créditos, o Midaz paga primeiro o overdraft. O que sobra vai para Available. Esse mecanismo atende 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 têm um campo `direction` que define como débitos e créditos afetam o saldo: | Direção | Comportamento | Uso típico | | -------- | ----------------------------- | -------------------------------------------------- | | `credit` | Débito reduz, crédito aumenta | Contas correntes, carteiras, reservas | | `debit` | Débito aumenta, crédito reduz | Empréstimos, controle de overdraft, contas a pagar | Na criação, o Midaz usa um `direction` explícito quando ele é informado e, depois, o `defaultDirection` do tipo de conta. Se nenhum dos dois estiver definido, as contas externas usam `debit`. Todas as outras contas usam `credit`. Você define a direção no momento da criação. Ela é **imutável**. O saldo companheiro de overdraft (descrito abaixo) sempre usa `direction=debit`. ## Configurações do saldo *** O objeto `settings` de um saldo controla o comportamento do overdraft: | Campo | Tipo | Descrição | | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- | | `allowOverdraft` | boolean | Habilita o overdraft neste saldo | | `overdraftLimitEnabled` | boolean | Controla se um limite é aplicado | | `overdraftLimit` | string (decimal) | Valor máximo de overdraft. Obrigatório quando `overdraftLimitEnabled` é `true`. Deve ser maior que `0`. | O objeto `settings` também carrega `balanceScope`. Ele identifica um saldo transacional (o padrão) ou um saldo interno gerenciado pelo sistema, como o companheiro de overdraft. Você pode definir `balanceScope: "transactional"` ao criar ou atualizar um saldo público. Você não pode definir `balanceScope: "internal"` pela API pública. ## Modos de configuração *** ### Sem overdraft (padrão) O comportamento padrão. O Midaz rejeita qualquer débito que exceda o saldo disponível. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": false } } ``` ### Overdraft ilimitado A posição derivada pode ficar negativa sem teto. O saldo `Available` persistido permanece em `0`, enquanto o Midaz registra o déficit em `OverdraftUsed`. Use isso em contas de liquidação ou contas pool, onde posições negativas são normais e você as concilia por fora. ```json JSON theme={null} { "key": "settlement", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Overdraft limitado A posição derivada pode ficar negativa até um limite definido. O saldo `Available` persistido permanece em `0`, enquanto o Midaz registra o déficit em `OverdraftUsed`. Esse é o modo mais comum para produtos de crédito ao consumidor. ```json JSON theme={null} { "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ê omitir o campo ou defini-lo como `"0"`, o Midaz retorna o erro `0172 - ErrInvalidBalanceSettings`. ## Como o overdraft funciona *** ### Divisão da operação Quando uma transação de débito excede os fundos disponíveis, o Midaz divide a operação automaticamente: 1. O débito consome todo o Available restante e o limita em **0**. 2. O Midaz acumula o excedente como **OverdraftUsed** no saldo principal. 3. Se o Midaz encontrar o saldo interno `"overdraft"` (descrito abaixo), ele cria uma operação companheira. Essa operação registra o passivo como um débito em partidas dobradas. Se não encontrar esse saldo, o Midaz pula a operação companheira. O saldo principal ainda acumula **OverdraftUsed**. **Exemplo:** o saldo tem Available = 300. Chega um débito de 500. | Etapa | Available | OverdraftUsed | Descrição | | ------ | --------- | ------------- | ---------------------------------------------------------- | | Antes | 300 | 0 | Estado normal | | Depois | 0 | 200 | 300 consumidos de Available, 200 acumulados como overdraft | A transação é concluída como uma única operação atômica. Quem chama não precisa tratar a divisão. O Midaz faz isso automaticamente. Se você configurar um limite, o Midaz compara o OverdraftUsed resultante com `overdraftLimit` **antes** de processar a transação. Se o resultado exceder o limite, o Midaz rejeita a transação com o erro `0167 - ErrOverdraftLimitExceeded`. ### Pagamento automático (divisão de reembolso) Quando chega um crédito e `OverdraftUsed > 0`, o Midaz prioriza o pagamento: 1. O Midaz aplica o crédito primeiro em **OverdraftUsed** e reduz a dívida. 2. Qualquer valor que sobrar depois que OverdraftUsed chega a 0 vai para **Available**. 3. Se o Midaz encontrar o saldo interno `"overdraft"`, uma operação companheira nele registra o pagamento. Se não encontrar esse saldo, o Midaz pula a operação companheira. O crédito ainda paga **OverdraftUsed** no saldo principal. **Exemplo:** OverdraftUsed = 200, Available = 0. Chega um crédito de 350. | Etapa | Available | OverdraftUsed | Descrição | | ------ | --------- | ------------- | --------------------------------- | | Antes | 0 | 200 | Overdraft ativo | | Depois | 150 | 0 | 200 pagos, 150 vão para Available | O pagamento é 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. ### Transações pendentes e overdraft Uma transação `PENDING` cria uma retenção. Ela não saca overdraft. Se uma retenção fosse exceder Available, o Midaz rejeita a transação com o erro `0018 - Insufficient Funds Error`. A retenção rejeitada não altera Available, OnHold nem `OverdraftUsed`. Quando você cancela uma transação pendente, o Midaz libera a retenção dela. Uma transação pendente criada por uma versão anterior do Midaz pode já carregar overdraft. O Midaz ainda desfaz esse estado legado corretamente durante o cancelamento. ## Posição *** Toda resposta de saldo inclui um bloco `position` calculado. Ele dá uma visão em tempo real do estado do saldo: | Campo | Descrição | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | O `position.available` derivado. Pode ficar negativo quando o saldo persistido tem `Available = 0` e `OverdraftUsed > 0`. | | `onHold` | Espelha `Balance.OnHold` — fundos reservados por operações pendentes. | | `overdraftLimitAvailable` | Margem de overdraft restante, nunca negativa. É `"0"` quando um limite configurado está totalmente usado e é omitido quando o overdraft é ilimitado. | Não guarde o bloco `position` em cache para fins contábeis. O Midaz nunca o persiste. Ele calcula o bloco no momento da consulta, a partir do estado atual do saldo. ## Saldo companheiro *** Quando você atualiza um saldo para definir `allowOverdraft` como `true` pela primeira vez, o Midaz provisiona automaticamente um **saldo companheiro** na mesma conta. O saldo companheiro registra o lado do passivo das partidas dobradas. O Midaz o cria uma vez por conta e o reutiliza em cada saque e pagamento de overdraft. | Propriedade | Valor | Por quê | | ---------------- | ------------- | -------------------------------------------------------------------------- | | `key` | `"overdraft"` | Chave reservada do sistema | | `direction` | `debit` | O companheiro registra um passivo — débitos o aumentam, créditos o reduzem | | `scope` | `internal` | Bloqueia operações diretas do usuário | | `allowSending` | `true` | Obrigatório para operações DEBIT no companheiro (saques de overdraft) | | `allowReceiving` | `true` | Obrigatório para operações CREDIT no companheiro (pagamentos de overdraft) | Esse saldo é **totalmente gerenciado pelo sistema**: * Você não pode criá-lo, modificá-lo nem excluí-lo pela API pública. * O Midaz **reserva** a chave `"overdraft"`. Uma requisição que cria um saldo com essa chave retorna o erro `0170 - ErrReservedBalanceKey`. * Ele espelha o passivo como um registro correto de partidas dobradas, então o ledger continua equilibrado. O valor `scope: "internal"` bloqueia operações diretas do usuário, seja qual for o valor das flags de permissão acima. O Midaz rejeita qualquer operação direta nesse saldo com o erro `0168 - ErrDirectOperationOnInternalBalance`. O companheiro se move apenas pelo enriquecimento de overdraft conduzido pelo sistema. ## Estado do overdraft nas operações *** Cada operação expõe o estado do overdraft nos blocos `balance` e `balanceAfter`. O campo `overdraftUsed` registra o overdraft consumido antes e depois da operação. Isso dá uma trilha de auditoria completa sem uma consulta de saldo separada. Para operações que não tocam o overdraft, os dois valores são `"0"`. As operações companheiras gerenciadas pelo sistema no saldo `"overdraft"` usam `type: "OVERDRAFT"` (em maiúsculas). O campo `direction` carrega o ciclo de vida: `"debit"` para um saque, `"credit"` para um pagamento. ```json Primary debit drawing overdraft theme={null} { "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" } } ``` ```json Companion overdraft draw theme={null} { "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" } } ``` A operação principal e a companheira compartilham o mesmo par antes/depois de `overdraftUsed`. Elas espelham a transição de overdraft do saldo principal, então o ciclo de vida fica visível por qualquer uma das linhas. A coluna interna `snapshot`, do tipo JSONB, na tabela `operations` guarda 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 acrescentar ao snapshot contexto futuro gerado pelo sistema sem quebrar o contrato público. As operações companheiras herdam o `routeId` da operação principal. Para cada rota habilitada para overdraft, configure as rubricas `debit` e `credit` da entrada `overdraft`. O Midaz exige as duas. O Midaz resolve `routeCode` e `routeDescription` pela rubrica que corresponde à direção do companheiro. ## Eventos de overdraft *** Em tempo de execução, o Midaz habilita a publicação de eventos de overdraft, a menos que `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` seja explicitamente `false`. O ambiente de exemplo que acompanha o produto define a flag como `false`. Um deploy que parte desse exemplo não publica nenhum evento de overdraft até você defini-la como `true`. ```bash Environment theme={null} # 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 | Descrição | | ------------------- | ---------------------------------------------------------------------------- | | `overdraft.drawn` | O overdraft foi consumido — OverdraftUsed aumentou | | `overdraft.repaid` | O overdraft foi parcialmente pago — OverdraftUsed diminuiu, mas continua > 0 | | `overdraft.cleared` | O overdraft foi totalmente pago — OverdraftUsed chegou a 0 | ### Exemplo de payload do evento ```json JSON expandable theme={null} { "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" } } ``` Use os eventos de overdraft para disparar workflows downstream: acúmulo de juros, notificações ao cliente, alertas de risco ou processos automáticos de cobrança. ## Casos de uso *** ### Overdraft em conta corrente (cheque especial) Crédito clássico ao consumidor. A posição derivada da conta corrente pode ficar negativa até um limite pré-aprovado. O saldo `Available` persistido permanece em `0` e o valor em aberto é registrado em `OverdraftUsed`. ```json JSON theme={null} { "key": "checking", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "2000.00" } } ``` ### Buy Now, Pay Later (BNPL) Um provedor de BNPL concede um crédito de compra contra o saldo do cliente. Isso cria uma posição de overdraft imediata que o cliente paga em parcelas. ```json JSON theme={null} { "key": "bnpl", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000.00" } } ``` ### Earned Wage Access / Antecipação salarial Os funcionários sacam contra ganhos futuros. Os créditos da folha de pagamento zeram a posição de overdraft quando chegam. ```json JSON theme={null} { "key": "salary-advance", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "3000.00" } } ``` ### Antecipação de recebíveis de marketplace Os vendedores recebem uma antecipação sobre recebíveis futuros. O Midaz paga o overdraft automaticamente conforme chegam as liquidações das vendas. ```json JSON theme={null} { "key": "receivables", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "50000.00" } } ``` ### Contas de liquidação / contas pool (modo ilimitado) Contas de liquidação e contas pool ficam negativas com frequência durante o processamento intradiário. O overdraft ilimitado evita rejeições artificiais enquanto você concilia a posição até o fim do dia. ```json JSON theme={null} { "key": "settlement-pool", "assetCode": "USD", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": false } } ``` ### Linhas de crédito rotativo (B2B) As empresas sacam e pagam a partir de uma linha de crédito rotativo. O limite de overdraft representa a linha de crédito total. ```json JSON theme={null} { "key": "credit-line", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "500000.00" } } ``` ### Pré-financiamento de seguros As seguradoras pré-financiam sinistros antes de os ciclos de cobrança de prêmios fecharem. O overdraft cobre a lacuna entre o pagamento e a cobrança. ```json JSON theme={null} { "key": "claims-prefin", "assetCode": "BRL", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "100000.00" } } ``` ### Programas de fidelidade (pontos antecipados) Os clientes resgatam pontos antes de acumulá-los. O overdraft registra o déficit de pontos e zera conforme os clientes acumulam novos pontos. ```json JSON theme={null} { "key": "loyalty-points", "assetCode": "POINTS", "settings": { "allowOverdraft": true, "overdraftLimitEnabled": true, "overdraftLimit": "10000" } } ``` ## Regras de proteção *** O overdraft traz algumas restrições de imutabilidade e de acesso para manter a integridade do ledger: * **A direção é imutável.** Depois que você define o `direction` de um saldo na criação, não pode mais alterá-lo. * **Saldos internos bloqueiam escritas.** Você não pode criar, excluir nem atualizar o saldo companheiro `"overdraft"` pela API pública. Um PATCH retorna o erro `0175`. * **Chaves reservadas.** O Midaz reserva a chave `"overdraft"` para o saldo companheiro gerenciado pelo sistema. * **Desabilitar o overdraft preserva a dívida em aberto.** Você pode definir `allowOverdraft: false` enquanto `OverdraftUsed > 0` para bloquear saques futuros, e os créditos recebidos continuam pagando a dívida existente. * **O limite não pode ficar abaixo do uso.** Se `OverdraftUsed = 200`, o Midaz rejeita `overdraftLimit: "100"` com o erro `0173`, então pague até ficar abaixo do novo teto antes ou defina um limite maior. * **Concorrência otimista.** As atualizações de saldo usam controle de concorrência por versão, e o Midaz rejeita uma escrita desatualizada com o erro `0174`. Tente de novo com a versão mais recente. Para o catálogo completo dos códigos de erro de overdraft (0167–0175), veja a [lista de erros do Midaz](/pt/reference/products/midaz/error-list). ## Próximos passos *** * Conheça os [Saldos](/pt/products/midaz/balances), a base sobre a qual o overdraft é construído. * Entenda as [Operações](/pt/products/midaz/operations) para rastrear como as divisões de overdraft aparecem no ledger. * Configure o [Event Publisher](/pt/products/midaz/event-publisher) para consumir os eventos do ciclo de vida do overdraft. * Explore as [Transações](/pt/products/midaz/transactions) para ver o quadro completo das partidas dobradas no Midaz.