Transações - Lerian

Uma Transação no Midaz registra um evento financeiro completo. Uma transação costuma usar múltiplas contas e saldos. O Midaz roda em um sistema de contabilidade de partidas dobradas que mantém toda 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 informar uma balanceKey, a transação usa o saldo padrão.

Contabilidade de partidas dobradas

O sistema de partidas dobradas segue um princípio. Toda 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 em equilíbrio:

Débitos mostram o valor recebido ou os recursos consumidos.
Créditos mostram o valor dado ou os recursos fornecidos.

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

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)

Sistemas financeiros tradicionais limitam as transações a relações um-para-um ou um-para-muitos. O Midaz oferece suporte a transações N:N. Uma única transação pode usar múltiplas contas de origem e destino.

Exemplos

Repasse de marketplace: uma única conta escrow paga vários vendedores, e cada vendedor paga uma tarifa da plataforma.
Peer-to-peer com tarifas: uma transação debita o pagador e credita tanto o recebedor quanto uma conta de tarifa.

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

Atomicidade e integridade

As 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 partir de uma única origem ou de múltiplas origens.

A soma dos valores em source deve ser igual ao valor em 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 especificar 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 uma transação de 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 de 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 múltiplas origens em que BRL 30,00 são retirados de duas contas de origem e enviados para uma única conta de destino — Figura 2. Exemplo de uma transação de 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 uma transação de 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 de 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 restante.

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 restante vai para a conta 5 (@account5).

Transação com múltiplos destinos dividindo BRL 100,00 de uma conta de origem entre cinco contas de destino por percentual e valores fixos — Figura 4. Exemplo de uma 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 destinatários.

Exemplo

Neste exemplo (Figura 5):

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

Transação com múltiplas origens e múltiplos destinos retirando BRL 4.000,00 de quatro contas e distribuindo-as igualmente entre quatro contas de destino — Figura 5. Exemplo de uma 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 das transações

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

Status	O que significa	Afeta saldos?	Como é criada
`CREATED`	Uma transação de reversão foi iniciada e está sendo processada. Este é um status transitório que avança automaticamente para `APPROVED` quando 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 a 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 ficam reservados em `on_hold`, mas ainda não são 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 saldos. As operações preservam a estrutura de partidas dobradas, mas todos os campos de saldo são 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 compliance. Ele serve para qualquer caso em que a transação precise existir no ledger, mas os saldos já tenham sido liquidados em outro lugar.

Transições de status

As transações seguem caminhos previsíveis por esses status:

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

Quando uma transação chega a NOTED ou CANCELED, ela não pode fazer mais transições. Ambos são status terminais.

Fluxo da transação

Quando uma transação começa, o Midaz valida:

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

Se a validação passa e a transação não é 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 registrá-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 informar 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 permanece intocado: nenhum débito ou crédito é lançado ainda.
Você deve fazer commit explicitamente para executar a transferência, ou cancel para liberar os fundos.

O recurso de Transação em Duas Fases oferece suporte ao Flowker. Você reserva os fundos no início de um workflow e roda as validações depois. O Midaz garante a execução se o workflow aprovar a transação.

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

Transação em duas fases em um workflow antifraude, reservando os fundos primeiro e confirmando ou cancelando-os após a validação — Figura 6. Exemplo de workflow 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), as permissões (allowSending, allowReceiving) e os fundos disponíveis. Se válida:

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 na origem. Nenhum débito ou crédito chega ao destino ainda.

2. Confirmar ou cancelar a transação pendente

Commit: finaliza a transação. Os fundos passam de on_hold para o saldo de destino, e o Midaz adiciona as operações DEBIT e CREDIT. Uma transação em duas fases com commit carrega três operações no total (ON_HOLD, DEBIT, CREDIT).
- Use o endpoint Confirmar uma transação pendente.
- Status: APPROVED.
Cancel: 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 oferece suporte a 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 do saldo 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, compliance e importações em que 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 produção. Assim, o Midaz recalcula os saldos de forma consistente em todo o ledger.

Transações sem impacto financeiro

O Midaz pode criar transações que 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 mantendo os saldos inalterados.
Registrar eventos de auditoria ou compliance.
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 os saldos.

Mesmo quando o Midaz não atualiza nenhum saldo, ele aplica as regras de partidas dobradas. Isso mantém a consistência em todas as transações do 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 oferece suporte à publicação de eventos em tempo real por meio do RabbitMQ. Você pode acompanhar o status das suas transações à medida que elas acontecem. Depois de habilitar esse recurso, cada transação gera um evento: APPROVED, PENDING, CANCELED, CREATED ou NOTED. Sistemas externos se inscrevem nesses eventos por meio de roteamento baseado em tópicos. Para saber mais sobre como publicar e consumir eventos de transação, veja a página Publicador de eventos.

Entradas, saídas e contas externas

O Midaz usa um ledger de 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 funciona como a ponte entre o Midaz e o mundo financeiro externo (bancos, PSPs, trilhos de pagamento e assim por diante).

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 injete fundos nas contas do Midaz e debite a conta externa. Essa é a única forma de trazer fundos para o Midaz.

Entradas – adicionando valor ao Ledger

Para creditar uma conta interna de fora do ledger:

Origem: @external/{{assetCode}} (por exemplo, @external/BRL).
Destino: uma ou mais contas internas (por exemplo, @organization.main).

Exemplo: primeiro depósito no Ledger Sua instituição mantém R$ 10.000 em um banco do mundo real e quer trazê-los 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. Em seguida, seu sistema transfere os fundos para o destinatário por meio do SPI ou de outra integração.

Comportamento e regras de saldo

@external/{{assetCode}} pode ter um saldo zero ou negativo, mas nunca positivo.
O saldo dela é sempre o inverso do saldo combinado de todas as contas do Midaz que mantêm esse ativo.
Toda entrada aumenta a liquidez interna e reduz o saldo da conta externa (ou seja, simula um depósito).
Toda 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.

Definindo uma data personalizada para a transação

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

Opcional. Se você omiti-lo, 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
- Apenas a 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 no mesmo dia)
Importar dados financeiros históricos para um novo ledger
Conciliar com sistemas externos que usam 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 esse conceito de Rotas Contábeis. O recurso e os endpoints da API mantêm o nome transactionRoute / Rotas de Transação. Ambos se referem à mesma rota no nível da 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 tarifa, um depósito ou um repasse podem precisar de diferentes tipos de conta, regras de validação e estruturas. Você não trata 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 de acordo com estes 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 em vez disso. 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 vai remover o campo em uma versão futura.

Por que isso importa?

Com as Rotas de Transação, você:

Mantém uma estrutura de transação consistente em toda a sua aplicação.
Valida eventos financeiros de acordo com padrões predefinidos.
Configura templates de transação sem alterações de código.
Mantém a integridade dos dados por meio de validação estruturada.

Iniciando uma transação

Ao criar transações pela API, sempre implemente idempotência para evitar o processamento duplicado. O Midaz oferece suporte nativo a idempotência por meio do header X-Idempotency. Valide o header de resposta X-Idempotency-Replayed para diferenciar novas transações de replays em cache. Veja Novas tentativas e idempotência para mais detalhes.

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

Formato da requisição JSON na v2

Cada lado da transação usa uma representação: from ou sources, e independentemente to ou destinations. Não envie as duas representações para o mesmo lado, e não envie um null explícito para um campo escalar não utilizado. 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 vai de 1 a 100; share.percentageOfPercentage vai de 0 a 100, em que 0 significa nenhum estreitamento. As requisições de criação da v2 têm um limite de corpo de 1 MiB.

Usando o endpoint JSON

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

Se você precisar 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 oferece suporte à 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 header 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 um sinal para verificar o estado da origem antes de tentar novamente.

Como funciona?

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

Inverte as operações:
- As operações CREDIT se tornam operações de origem (from).
- As operações DEBIT se tornam operações de destino (to).
Cria uma nova transação com:
- O mesmo valor e código de ativo.
- A mesma descrição e os mesmos metadados.
- Operações invertidas (quem recebe passa a enviar, quem envia passa a receber).
- 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

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:

A Conta A volta ao saldo anterior (recebe de volta o -100).
A Conta B volta ao saldo anterior (perde o +100).
As duas 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á tem uma reversão

O Midaz permite apenas uma reversão por transação.
Isso evita 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 evita “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 acontece quando a transação não tem 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 na transação não é bidirecional

Toda operação que carrega um routeId deve 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).
Planeje isso ao projetar rotas. Veja Rotas Contábeis.

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

Casos de uso

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

1. Reversão de pagamento incorreto

Um cliente pagou BRL 500 ao fornecedor errado.

Reverta a transação.
Os fundos voltam para a conta do cliente.
O cliente pode iniciar um novo pagamento ao 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 de venda.
Os fundos voltam para a 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 uma devolução.

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 voltam ao estado anterior.

Bloqueio e desbloqueio de fundos

Alguns cenários exigem que você sinalize fundos como bloqueados (uma retenção de compliance, uma ordem judicial, uma investigação de fraude) e depois os libere. 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 do endpoint Criar uma transação usando JSON, com duas diferenças importantes:

Sempre lançadas imediatamente. O Midaz ignora o campo pending no corpo da requisição e o substitui por 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 movimentações de fundos bloqueados sem consultar os metadados.

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 no nível do saldo em Saldos: flags de permissão (allowSending / allowReceiving) e saldos de garantia. Esses controles restringem a movimentação, mas não registram nenhuma transação. Use um saldo de garantia para uma restrição operacional permanente. Use uma transação de Bloqueio quando precisar de um lançamento 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 bloqueados anteriormente.

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 a transação.
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: sinalize fundos como bloqueados com operações do tipo BLOCK.
Criar uma transação de desbloqueio: libere fundos bloqueados anteriormente com operações do tipo UNBLOCK.
Listar transações: veja todas as Transações do seu workspace.
Recuperar uma transação: obtenha os 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 Gerenciando Transações.

​Contabilidade de 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 das transações

​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

​Formato 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á tem 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 na 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

​Bloqueio e desbloqueio de fundos

​Gerenciando transações

​Via API

​Via Lerian Console

Contabilidade de 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 das transações

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

Formato 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á tem 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 na 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

Bloqueio e desbloqueio de fundos

Gerenciando transações

Via API

Via Lerian Console