Transações - Lerian

Uma Transação no Midaz registra um evento financeiro completo. Uma transação frequentemente usa múltiplas contas e saldos. O Midaz funciona sobre um sistema de contabilidade por partidas dobradas que mantém cada movimentação financeira balanceada. Com o recurso de múltiplos saldos, cada operação especifica a conta e a chave de saldo a ser usada. Você pode então debitar ou creditar diferentes saldos lógicos da mesma conta (por exemplo, credit, operational ou collateral).

Se você não fornecer um balanceKey, a transação usa o saldo padrão.

Contabilidade por partidas dobradas

O sistema de partidas dobradas segue um princípio. Cada transação tem dois lançamentos: um débito e um crédito. Essa estrutura registra toda a atividade financeira e mantém suas contas balanceadas. Cada transação afeta duas contas e as mantém balanceadas:

Débitos mostram o valor recebido ou os recursos consumidos.
Créditos mostram o valor fornecido ou os recursos entregues.

O Midaz rastreia e balanceia cada débito e crédito automaticamente.

Exemplo

Neste exemplo, você transfere R$1.000 de uma conta para outra. A transação tem duas operações:

Uma operação para debitar R$1.000,00 da conta de origem.
Uma operação para creditar R$1.000,00 na conta de destino.

O Midaz captura os dois lançamentos automaticamente. Você pode visualizar e analisar essas movimentações pela API ou pelo Lerian Console.

Transações N:N (Muitos-para-Muitos)

Os sistemas financeiros tradicionais limitam transações a relacionamentos um-para-um ou um-para-muitos. O Midaz suporta transações N:N. Uma única transação pode usar múltiplas contas de origem e destino.

Exemplos

Pagamento em marketplace: uma única conta escrow paga múltiplos vendedores, e cada vendedor paga uma taxa da plataforma.
Peer-to-peer com taxas: uma transação debita o pagador e credita tanto o beneficiário quanto uma conta de taxas.

O Midaz processa cada caso como uma única transação atômica. Ele debita e credita todas as partes em conjunto.

Atomicidade e integridade

Transações são atômicas. Ou todas as operações são bem-sucedidas, ou nenhuma é. Eventos financeiros parciais não ocorrem. Se qualquer parte de uma transação falhar na validação — por exemplo, uma conta tem fundos insuficientes — o Midaz não aplica a transação. O ledger permanece consistente.

Origem da transação

Uma transação no Midaz pode começar a partir de uma única origem ou de múltiplas origens.

A soma dos valores em source deve ser igual ao valor após o send. Ela também deve ser igual à soma dos valores em distribute.

Origem única

Em uma transação de origem única, o Midaz retira o valor de uma conta de origem. Você também pode indicar um saldo específico.

Exemplo

Neste exemplo (Figura 1):

O Midaz retira BRL 30,00 de @account1 (saldo credit).
Ele envia 100% para @destinationAccount1 (saldo operational)

Transação de origem única movendo BRL 30,00 de uma conta de origem para uma única conta de destino — Figura 1. Exemplo de transação com origem única.

Exemplos de código

{
  "description": "single source transaction",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "credit", // optional
          "amount": {
            "asset": "BRL",
            "value": "30.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "balanceKey": "operational", // optional
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Múltiplas origens

Em uma transação com múltiplas origens, o Midaz retira fundos de múltiplas contas ou saldos.

Exemplo

Neste exemplo (Figura 2):

O Midaz envia BRL 30,00 para a conta de destino (@destinationAccount1).
- BRL 15,00 de @account1 (saldo default).
- BRL 15,00 de @account2 (saldo investment).
A conta de destino recebe 100% do valor.

Transação de origem múltipla em que BRL 30,00 são retirados de duas contas de origem e enviados a uma única conta de destino — Figura 2. Exemplo de transação com múltiplas origens.

Exemplos de código

{
  "description": "multi-source transaction",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "default",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        },
        {
          "accountAlias": "@account2",
          "balanceKey": "investment",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Destino da transação

Assim como as origens, os destinos podem ser únicos ou múltiplos.

Destino único

Em uma transação de destino único, o Midaz envia o valor para apenas uma conta de destino.

Exemplo

Neste exemplo (Figura 3):

O Midaz retira BRL 30,00 de uma conta externa (@external/BRL).
Ele envia 100% para a conta de destino (@destinationAccount1).

Transação de destino único movendo BRL 30,00 de uma conta externa para uma conta de destino — Figura 3. Exemplo de transação com destino único.

Exemplos de código

{
   "description":"single destination transaction",
   "send":{
      "asset":"BRL",
      "value":"30.00",
      "source":{
         "from":[
            {
               "accountAlias":"@external/BRL",
               "amount":{
                  "asset":"BRL",
                  "value":"30.00"
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@destinationAccount1",
               "share":{
                  "percentage":100
               }
            }
         ]
      }
   }
}

Múltiplos destinos

Em uma transação com múltiplos destinos, o Midaz divide o valor entre múltiplas contas de destino. Você pode distribuir os valores por percentuais, valores fixos ou o saldo remanescente.

Exemplo

Neste exemplo (Figura 4):

O Midaz retira BRL 100 da conta de origem (@account1).
38% do valor vai para a conta 2 (@account2).
50% vai para a conta 3 (@account3).
Um valor fixo de BRL 2,00 vai para a conta 4 (@account4).
O valor remanescente vai para a conta 5 (@account5).

Transação de destino múltiplo que distribui BRL 100,00 de uma conta de origem entre cinco contas de destino por percentuais e valores fixos — Figura 4. Exemplo de transação com múltiplos destinos.

Exemplo de código

{
   "description":"multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"100.00",
      "source":{
         "from":[
            {
               "accountAlias":"@account1",
               "amount":{
                  "asset":"BRL",
                  "value":"100.00"
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@account2",
               "share":{
                  "percentage":38
               }
            },
            {
               "accountAlias":"@account3",
               "share":{
                  "percentage":50
               }
            },
            {
               "accountAlias":"@account4",
               "amount":{
                  "asset":"BRL",
                  "value":"2.00"
               }
            },
            {
               "accountAlias":"@account5",
               "remaining":"remaining"
            }
         ]
      }
   }
}

Múltiplas origens e múltiplos destinos

Essas transações usam múltiplas origens e múltiplos destinos. Elas são úteis para casos como uma campanha de financiamento coletivo. O Midaz reúne as contribuições e as distribui entre múltiplos beneficiários.

Exemplo

Neste exemplo (Figura 5):

A doação é de BRL 4.000,00. O Midaz a retira de quatro contas diferentes.
- 25% vem da conta 1 (@account1).
- 25% vem da conta 2 (@account2).
- 40% vem da conta 3 (@account3)
- 10% vem da conta 4 (@account4).
O Midaz distribui as doações para quatro contas separadas. Cada conta recebe 25% do total.

Transação de origem e destino múltiplos que retira BRL 4.000,00 de quatro contas e a distribui igualmente entre quatro contas de destino — Figura 5. Exemplo de transação com múltiplas origens e múltiplos destinos.

Exemplos de código

{
   "description":"multi-source and multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"4000.00",
      "source":{
         "from":[
            {
               "accountAlias":"@account1",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@account2",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@account3",
               "share":{
                  "percentage":40
               }
            },
            {
               "accountAlias":"@account4",
               "share":{
                  "percentage":10
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@donation1",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation2",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation3",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation4",
               "share":{
                  "percentage":25
               }
            }
         ]
      }
   }
}

Status da transação

Toda transação no Midaz tem um status. O status reflete sua etapa atual no ciclo de vida. Você precisa desses status para projetar fluxos de transação, configurar consumidores de eventos e ler os dados do ledger.

Status	O que significa	Afeta saldos?	Como é criado
`CREATED`	Uma transação de reversão foi iniciada e está sendo processada. Esse é um status transitório que progride automaticamente para `APPROVED` assim que a reversão é concluída.	Sim	Reverter uma Transação
`APPROVED`	A transação foi concluída com sucesso. Os fundos foram movidos entre as contas.	Sim	Transação direta (sem flag `pending`), commit de uma transação `PENDING`, ou progressão automática a partir de `CREATED`
`PENDING`	Uma transação em duas fases está aguardando confirmação. Os fundos estão reservados em `on_hold` mas ainda não foram transferidos.	Sim (reserva)	Criar uma Transação com `"pending": true`
`CANCELED`	Uma transação em duas fases foi cancelada. Os fundos reservados são liberados de volta para `available`.	Sim (liberação)	Cancelar uma Transação Pendente
`NOTED`	Uma transação de anotação registrada no ledger sem afetar os saldos. As operações preservam a estrutura de partida dobrada, mas todos os campos de saldo ficam zerados.	Não	Criar uma Anotação de Transação

Use o status NOTED para importar transações legadas, registrar trilhas de auditoria e registrar eventos de conformidade. Ele serve para qualquer caso em que a transação precise existir no ledger mas os saldos já foram liquidados em outro lugar.

Transições de status

As transações seguem caminhos previsíveis através desses status:

Fluxo padrão: → APPROVED (etapa única)
Fluxo em duas fases: → PENDING → APPROVED (commit) ou CANCELED (cancelamento)
Fluxo de reversão: → CREATED → APPROVED (automático)
Fluxo de anotação: → NOTED (terminal, sem transições)

Uma vez que uma transação atinge NOTED ou CANCELED, ela não pode mais transicionar. Ambos são status terminais.

Fluxo da transação

Quando uma transação é iniciada, o Midaz valida:

As contas envolvidas.
Os saldos especificados (balanceKey, ou default se não fornecido).
Permissões (allowSending, allowReceiving).
Fundos disponíveis suficientes no saldo selecionado.

Se a validação passar e a transação não for pendente (fluxo de Transação em Duas Fases), o Midaz transfere o valor imediatamente. Ele move o valor da conta de origem para a conta de destino, a partir do saldo disponível. Esse processo é síncrono. Em caso de sucesso, o status da transação passa a APPROVED.

Inicie esse tipo de transação apenas se você pretende confirmá-la no ledger imediatamente.

Para transações que precisam de validação ou aprovação antes, use a flag pending para criar uma Transação em Duas Fases.

Transação em Duas Fases

Nesse fluxo, o Midaz cria a transação com status PENDING. O Midaz não move os fundos de imediato. Em vez disso, ele reserva o valor no saldo correto (balanceKey, ou default se você não fornecer um).

O Midaz move os fundos reservados de available para on_hold.
O Midaz registra uma operação, do tipo ON_HOLD, no saldo de origem. O saldo de destino não é tocado: nenhum débito ou crédito é lançado ainda.
Você deve explicitamente fazer commit para executar a transferência, ou cancel para liberar os fundos.

O recurso de Transação em Duas Fases dá suporte ao Flowker. Você reserva fundos no início de um fluxo de trabalho e executa validações depois. O Midaz garante a execução se o fluxo de trabalho aprovar a transação.

Na Figura 6, você pode ver um exemplo de transação em duas fases com antifraude.

Transação em duas fases em um fluxo antifraude, que primeiro reserva os fundos e depois os confirma ou cancela após a validação — Figura 6. Exemplo de fluxo de trabalho antifraude

Fluxo da Transação em Duas Fases

1. Criar uma Transação em Duas Fases

Use o endpoint Criar uma Transação usando JSON com "pending": true.

O Midaz valida as contas, os saldos especificados (balanceKey), permissões (allowSending, allowReceiving) e fundos disponíveis. Se válido:

O Midaz reserva os fundos no saldo correto.
O Midaz define o status da transação como PENDING.
O Midaz armazena os metadados e lança a operação ON_HOLD de origem; nenhum débito ou crédito chega ao destino ainda.

2. Confirmar ou cancelar a transação pendente

Confirmar: finaliza a transação. Os fundos são movidos de on_hold para o saldo de destino, e o Midaz acrescenta as operações DEBIT e CREDIT — então uma transação em duas fases confirmada carrega três operações no total (ON_HOLD, DEBIT, CREDIT).
- Use o endpoint Confirmar uma Transação Pendente.
- Status: APPROVED.
Cancelar: libera os fundos reservados de volta para available no mesmo saldo.
- Use o endpoint Cancelar uma Transação Pendente.
- Status: CANCELED.

Transações Passadas

O Midaz também suporta transações passadas. As instituições podem importar eventos financeiros legados e manter a precisão histórica.

Use o campo opcional transactionDate para definir a data original da transação.
Transações com impacto financeiro recalculam o estado histórico dos saldos como se o Midaz as tivesse processado naquela data.
Transações criadas pelo endpoint Criar uma Anotação de Transação validam a estrutura, mas não afetam saldos. Elas servem para auditorias, conformidade e importações onde os saldos devem permanecer inalterados.

Exemplo

{
  "description": "past transaction example",
  "transactionDate": "2025-01-01T13:38:31.064Z", // optional
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    }
  }
}

Envie todas as transações passadas antes de iniciar as operações em tempo real. O Midaz então recalcula os saldos de forma consistente em todo o ledger.

Transações sem impacto financeiro

O Midaz pode criar transações que ele registra no ledger, mas que não afetam os saldos das contas. Essas transações mantêm a integridade estrutural e deixam os saldos inalterados. Esse recurso é útil quando você precisa:

Importar transações legadas mas manter os saldos inalterados.
Registrar eventos de auditoria ou conformidade.
Adicionar operações de negócio que o ledger deve rastrear, mas que não movem fundos.

Como funciona?

Quando você cria uma transação sem impacto financeiro:

O Midaz armazena os campos balance e balanceAfter como 0 para preservar a validação de partidas dobradas.
Cada operação tem um campo balanceAffected (booleano):
- true → a operação afeta o saldo da conta.
- false → o Midaz registra a operação no ledger mas não altera saldos.

Mesmo quando o Midaz não atualiza saldos, ele aplica as regras de partidas dobradas. Isso mantém a consistência em todas as transações no ledger.

Exemplo

{
  "description": "annotation example",
  "transactionDate": "2025-01-01T13:38:31.064Z",
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          },
          "balanceAffected": false
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          },
          "balanceAffected": false
        }
      ]
    }
  }
}

Endpoint relacionado

Criar uma Anotação de Transação — Registre uma transação sem impacto financeiro no ledger.

Publicação de eventos em tempo real

O Midaz suporta publicação de eventos em tempo real via RabbitMQ. Você pode acompanhar o status das suas transações conforme elas acontecem. Depois de habilitá-lo, cada transação gera um evento: APPROVED, PENDING, CANCELED, CREATED ou NOTED. Sistemas externos assinam esses eventos por roteamento baseado em tópicos. Para mais informações sobre como publicar e consumir eventos de transação, veja a página do Publicador de eventos.

Entradas, saídas e contas externas

O Midaz usa um ledger por partidas dobradas. Todo valor que entra ou sai do sistema deve passar por uma conta especial: a Conta Externa. O Midaz representa essa conta como @external/{{assetCode}}. Ela atua como a ponte entre o Midaz e o mundo financeiro externo (bancos, PSPs, trilhos de pagamento, etc.).

Por que isso importa?

Quando você inicializa o ledger pela primeira vez, todas as contas — incluindo @external — começam com saldo zero. Para refletir saldos do mundo real, como fundos institucionais mantidos fora do Midaz, você deve iniciar uma transação que injeta fundos nas contas do Midaz e debita a conta externa. Essa é a única forma de trazer fundos para dentro do Midaz.

Entradas – Adicionando valor ao Ledger

Para creditar uma conta interna de fora do ledger:

Origem: @external/{{assetCode}} (ex.: @external/BRL).
Destino: Uma ou mais contas internas (ex.: @organization.main).

Exemplo: Primeiro depósito no Ledger Sua instituição possui R$10.000 em um banco do mundo real e quer trazer para o Midaz. Você cria uma transação:

Origem	Destino	Valor
@external/BRL	@accountA	BRL 10.000

Isso debita a conta externa e credita sua conta interna. A conta externa agora mostra um saldo negativo. Isso é esperado: representa o valor total que sua organização trouxe para o ledger.

Saídas – Movendo valor para fora do Ledger

Para mover valor do ledger para um destino externo:

Origem: Uma ou mais contas do Midaz.
Destino: @external/{{assetCode}}.

Exemplo: Uma transferência PIX do Ledger para um banco externo

Origem	Destino	Valor
@accountA	@external/BRL	BRL 1.000

Isso debita @accountA e credita a conta externa. Seu sistema então transfere os fundos para o destinatário via SPI ou outra integração.

Comportamento e regras de saldo

@external/{{assetCode}} pode ter saldo zero ou negativo, mas nunca positivo.
Seu saldo é sempre o inverso do saldo combinado de todas as contas do Midaz que mantêm aquele ativo.
Cada entrada aumenta a liquidez interna e reduz o saldo da conta externa (ou seja, simula um depósito).
Cada saída faz o inverso.

Todo valor que se move entre o mundo externo e o ledger do Midaz deve passar pela conta externa.Nada entra ou sai do sistema sem uma transação formal. Isso dá a você total rastreabilidade, integridade de saldos e conformidade com os princípios de partidas dobradas.

Definindo uma data personalizada para a transação

O campo transactionDate permite que você defina uma data personalizada para uma transação, independente de quando você a envia para a API.

Opcional. Se você o omitir, o Midaz usa o timestamp atual.
Formatos aceitos:
- ISO 8601 com fuso horário: 2026-01-15T10:30:00Z
- ISO 8601 sem fuso horário: 2026-01-15T10:30:00
- Somente data: 2026-01-15
Restrição: você não pode usar uma data futura. Uma data futura retorna o erro 0121.
Restrição: você não pode usá-lo em transações PENDING. Um transactionDate com "pending": true retorna o erro 0122.

Casos de uso

Registrar transações que ocorreram no passado (por exemplo, correções do mesmo dia)
Importar dados financeiros históricos para um novo ledger
Reconciliar com sistemas externos que utilizam uma data de lançamento diferente

Rotas de Transação

A API de Rotas de Transação permite o processamento estruturado e validado de transações no Midaz.

O Lerian Console e a documentação do produto chamam este conceito de Rotas Contábeis (Accounting Routes). O recurso e os endpoints da API mantêm o nome transactionRoute / Rotas de Transação. Ambos se referem à mesma rota em nível de transação.

A API de Transações executa eventos financeiros: débitos e créditos entre contas. As Rotas de Transação definem templates para como estruturar e validar esses eventos. Isso os mantém consistentes e corretos. Pense nisso como a camada de validação. Ela faz as transações de negócio seguirem padrões predefinidos e manterem uma estrutura financeira adequada. Por exemplo, uma taxa, um depósito ou um pagamento pode precisar de diferentes tipos de conta, regras de validação e estruturas. Você não lida com a validação separadamente para cada transação. Em vez disso, você configura regras predefinidas. Essas regras dizem ao Midaz: “Quando o usuário enviar esse tipo de transação, valide-a contra esses requisitos de conta e padrões de estrutura.” Cada Rota de Transação combina múltiplas Rotas de Operação. Uma Rota de Operação define um componente de uma transação. Ela define os requisitos de conta, a direção (origem ou destino) e as regras de validação para cada “perna” do evento financeiro.

Não use o campo route nas entradas FromTo — use routeId no lugar. O campo routeId aceita um UUID que referencia uma Rota de Operação criada pela API de Rotas de Operação. O Midaz mantém o campo route por compatibilidade retroativa, mas removerá o campo em uma versão futura.

Por que isso importa?

Com Rotas de Transação, você:

Mantém uma estrutura consistente de transações em toda a sua aplicação.
Torna seu ledger mais fácil de manter, previsível e confiável.
Valida eventos financeiros contra padrões predefinidos.
Configura templates de transação sem alterações de código.
Mantém a integridade dos dados através de validação estruturada.

Iniciando uma transação

Quando você cria transações via API, sempre implemente idempotência para evitar processamento duplicado. O Midaz oferece suporte integrado de idempotência através do header X-Idempotency. Valide o header de resposta X-Idempotency-Replayed para distinguir transações novas de replays em cache. Consulte Retentativas e idempotência para mais detalhes.

Use a API JSON de transações para iniciar uma transação.

Estrutura da requisição JSON na v2

Cada lado da transação usa uma representação: from ou sources e, de forma independente, to ou destinations. Não envie as duas representações para o mesmo lado nem um null explícito para um campo escalar não usado. Cada item de sources ou destinations exige account e exatamente uma expressão de valor: amount ou share. A expressão remaining não é aceita na v2. Cada array aceita no máximo 500 itens. share.percentage deve estar entre 1 e 100; share.percentageOfPercentage, entre 0 e 100, em que 0 não aplica redução. Requisições de criação v2 têm limite de corpo de 1 MiB.

Usando o endpoint JSON

Endpoints JSON fornecem um padrão flexível e amigável para desenvolvedores para intercâmbio de dados. Eles dão a você controle preciso sobre as estruturas de requisição para fluxos de trabalho customizados e casos de uso específicos. Eles funcionam com muitas linguagens de programação, o que facilita a integração e a depuração.

Para criar uma transação com JSON, use o endpoint Criar uma Transação usando JSON.

Se você precisa reservar fundos antes de concluir a transferência, defina o campo pending como true (fluxo de Transação em Duas Fases).

Revertendo uma transação

O Midaz suporta reversão de transações. Você pode desfazer uma transação aprovada. O Midaz cria uma transação espelho que inverte os débitos e créditos originais. Esse mecanismo mantém trilhas de auditoria completas e cancela o impacto financeiro nos saldos das contas.

A reversão cria uma nova transação que compensa a original. A transação original permanece no histórico do ledger para rastreabilidade completa.

A reversão não envia uma chave de idempotência própria, então o Midaz deriva uma. Leia o cabeçalho de resposta X-Idempotency-Replayed: true significa que você recebeu uma reversão em cache, e não uma recém-criada. Trate um replay como sinal para verificar o estado da origem antes de tentar de novo.

Como funciona?

Quando você reverte uma transação, o Midaz automaticamente:

Inverte as operações:
- Operações de CREDIT se tornam operações de origem (from).
- Operações de DEBIT se tornam operações de destino (to).
Cria uma nova transação com:
- Mesmo valor e código de ativo.
- Mesma descrição e metadados.
- Operações invertidas (destinatários se tornam remetentes, remetentes se tornam destinatários).
- Status inicial: CREATED (não PENDING) → depois avança para APPROVED.
- parentTransactionID que referencia a transação original.
Processa a reversão pelo fluxo padrão de transação: validação, atualização de saldos e registro no histórico.

Exemplo

Considere este cenário: Transação original:

Conta A (débito -100) → Conta B (crédito +100)

Transação de reversão criada:

Conta B (débito -100) → Conta A (crédito +100)

Resultado:

Conta A retorna ao seu saldo anterior (recebe de volta os -100).
Conta B retorna ao seu saldo anterior (perde os +100).
Ambas as transações permanecem no histórico do ledger para fins de auditoria.
A transação de reversão inclui um parentTransactionID que aponta para a original.

Restrições de reversão

O Midaz aplica regras rígidas para manter a integridade do ledger. Uma reversão falha nestes casos:

1. A transação já possui uma reversão

O Midaz permite apenas uma reversão por transação.
Isso previne múltiplas reversões da mesma transação.

2. A transação já é uma reversão

Você não pode reverter uma transação que já é uma reversão.
Isso previne a criação de “reversões de reversões”.

3. O status da transação não é APPROVED

Você pode reverter apenas transações aprovadas.
Você não pode reverter uma transação com status PENDING, CREATED ou CANCELED.

4. A transação não pode ser revertida

Isso ocorre quando a transação não possui operações válidas para inverter.
Por exemplo, uma transação sem operações padrão de CREDIT ou DEBIT.

5. Uma rota de operação da transação não é bidirecional

Toda operação que carrega um routeId precisa referenciar uma Rota de operação cujo operationType seja bidirectional.
Uma rota source ou destination não pode ser revertida: o Midaz retorna o erro 0150 (Route Not Bidirectional).
Considere isso ao desenhar suas rotas — veja Rotas Contábeis.

O Midaz reverte as operações de CREDIT e DEBIT. Ele não reverte as operações ON_HOLD nem RELEASE.

Casos de uso

A reversão de transações ajuda em vários cenários operacionais:

1. Reversão de pagamento incorreto

Um cliente pagou BRL 500 para o fornecedor errado.

Reverta a transação.
Os fundos retornam à conta do cliente.
O cliente pode iniciar um novo pagamento para o fornecedor correto.

2. Cancelamento de compra

Uma loja processou uma venda de BRL 1.000, mas o cliente cancela a compra.

Reverta a transação da venda.
Os fundos retornam à conta do cliente.

3. Correção de erro operacional

Um operador criou uma transação com o valor errado.

Reverta a transação incorreta.
Crie uma nova transação com o valor correto.

4. Devolução de produto

Um cliente comprou e pagou BRL 200, mas devolveu o produto.

Reverta a transação de pagamento.
O cliente recebe o reembolso.

5. Compensação de falha de integração

Uma transação é aprovada, mas falha em um sistema externo.

Reverta para desfazer a operação contábil.
Os saldos retornam ao estado anterior.

Bloqueando e desbloqueando fundos

Alguns cenários exigem marcar fundos como bloqueados — uma retenção por conformidade, uma ordem judicial, uma investigação de fraude — e depois liberá-los. O Midaz oferece suporte a isso com dois endpoints dedicados. Esses endpoints criam transações cujas operações são do tipo BLOCK e UNBLOCK. Essas transações aceitam o mesmo corpo que o endpoint Criar uma Transação usando JSON, com duas diferenças principais:

Sempre postadas imediatamente. O Midaz ignora o campo pending do corpo da requisição e o sobrescreve para false. Transações de bloqueio e desbloqueio nunca são em duas fases. Elas vão direto para APPROVED.
As operações são do tipo BLOCK ou UNBLOCK. Essa classificação as distingue no ledger e nas consultas de operações. Você pode auditar as movimentações de fundos bloqueados sem olhar o metadata.

O Midaz é agnóstico quanto ao motivo de negócio para bloquear ou desbloquear fundos. Registre o motivo no campo metadata.

Uma transação de bloqueio registra uma movimentação no ledger com operações do tipo BLOCK. Isso difere dos controles em nível de saldo em Saldos: as permission flags (allowSending / allowReceiving) e os saldos de garantia. Esses controles restringem a movimentação mas não registram uma transação. Use um saldo de garantia para uma restrição operacional permanente. Use uma transação de bloqueio quando precisar de uma entrada auditável no ledger.

Use o endpoint Criar uma Transação de Bloqueio para bloquear fundos.
Use o endpoint Criar uma Transação de Desbloqueio para liberar fundos previamente bloqueados.

Gerenciando transações

Você pode gerenciar suas Transações pela API ou pelo Lerian Console.

Via API

Criar uma Transação usando JSON — Envie uma transação diretamente usando um payload JSON.
Confirmar uma transação pendente — Finalize uma transação reservada.
Cancelar uma transação pendente — Libere fundos reservados sem executar.
Reverter uma Transação — Crie uma transação de reversão para desfazer uma transação aprovada.
Criar uma Transação de Entrada — Registre fundos recebidos de fontes externas no Ledger.
Criar uma Transação de Saída — Mova fundos de contas internas para o mundo externo.
Criar uma Transação de Bloqueio — Marque fundos como bloqueados com operações do tipo BLOCK.
Criar uma Transação de Desbloqueio — Libere fundos previamente bloqueados com operações do tipo UNBLOCK.
Listar Transações — Visualize todas as Transações no seu workspace.
Recuperar uma Transação — Obtenha detalhes de uma Transação específica.
Atualizar uma Transação — Edite os metadados de uma Transação existente.
Criar uma Anotação de Transação — Registre uma transação sem impacto financeiro no ledger.

Via Lerian Console

Você pode fazer todas as ações de gerenciamento de Transações — visualizar, criar e cancelar — pelo Lerian Console. Saiba mais no guia de Gerenciamento de Transações.

​Contabilidade por partidas dobradas

​Exemplo

​Transações N:N (Muitos-para-Muitos)

​Exemplos

​Atomicidade e integridade

​Origem da transação

​Origem única

​Exemplo

​Múltiplas origens

​Exemplo

​Destino da transação

​Destino único

​Exemplo

​Múltiplos destinos

​Exemplo

​Múltiplas origens e múltiplos destinos

​Exemplo

​Status da transação

​Transições de status

​Fluxo da transação

​Transação em Duas Fases

​Fluxo da Transação em Duas Fases

​1. Criar uma Transação em Duas Fases

​2. Confirmar ou cancelar a transação pendente

​Transações Passadas

​Exemplo

​Transações sem impacto financeiro

​Como funciona?

​Exemplo

​Endpoint relacionado

​Publicação de eventos em tempo real

​Entradas, saídas e contas externas

​Por que isso importa?

​Entradas – Adicionando valor ao Ledger

​Saídas – Movendo valor para fora do Ledger

​Comportamento e regras de saldo

​Definindo uma data personalizada para a transação

​Casos de uso

​Rotas de Transação

​Por que isso importa?

​Iniciando uma transação

​Estrutura da requisição JSON na v2

​Usando o endpoint JSON

​Revertendo uma transação

​Como funciona?

​Exemplo

​Restrições de reversão

​1. A transação já possui uma reversão

​2. A transação já é uma reversão

​3. O status da transação não é APPROVED

​4. A transação não pode ser revertida

​5. Uma rota de operação da transação não é bidirecional

​Casos de uso

​1. Reversão de pagamento incorreto

​2. Cancelamento de compra

​3. Correção de erro operacional

​4. Devolução de produto

​5. Compensação de falha de integração

​Bloqueando e desbloqueando fundos

​Gerenciando transações

​Via API

​Via Lerian Console

Contabilidade por partidas dobradas

Exemplo

Transações N:N (Muitos-para-Muitos)

Exemplos

Atomicidade e integridade

Origem da transação

Origem única

Exemplo

Múltiplas origens

Exemplo

Destino da transação

Destino único

Exemplo

Múltiplos destinos

Exemplo

Múltiplas origens e múltiplos destinos

Exemplo

Status da transação

Transições de status

Fluxo da transação

Transação em Duas Fases

Fluxo da Transação em Duas Fases

1. Criar uma Transação em Duas Fases

2. Confirmar ou cancelar a transação pendente

Transações Passadas

Exemplo

Transações sem impacto financeiro

Como funciona?

Exemplo

Endpoint relacionado

Publicação de eventos em tempo real

Entradas, saídas e contas externas

Por que isso importa?

Entradas – Adicionando valor ao Ledger

Saídas – Movendo valor para fora do Ledger

Comportamento e regras de saldo

Definindo uma data personalizada para a transação

Casos de uso

Rotas de Transação

Por que isso importa?

Iniciando uma transação

Estrutura da requisição JSON na v2

Usando o endpoint JSON

Revertendo uma transação

Como funciona?

Exemplo

Restrições de reversão

1. A transação já possui uma reversão

2. A transação já é uma reversão

3. O status da transação não é APPROVED

4. A transação não pode ser revertida

5. Uma rota de operação da transação não é bidirecional

Casos de uso

1. Reversão de pagamento incorreto

2. Cancelamento de compra

3. Correção de erro operacional

4. Devolução de produto

5. Compensação de falha de integração

Bloqueando e desbloqueando fundos

Gerenciando transações

Via API

Via Lerian Console