Por que isso importa
Para equipes de produto e operações, as Transaction Routes significam fluxos Pix previsíveis e auditáveis sem depender da aplicação para cumprimento. Cada transação carrega uma referência à rota que seguiu, tornando revisões de conformidade e investigações de incidentes diretas. Para equipes de engenharia, as rotas eliminam código de validação repetitivo. Em vez de verificar tipos de conta e destinos de taxas em cada integração Pix, você configura as regras uma vez e deixa o Midaz cuidar da aplicação no nível do ledger.
| Sem Rotas | Com Rotas |
|---|---|
| Cada integração deve aplicar suas próprias regras de conta | Defina as regras uma vez, reutilize em todas as transações Pix |
| Sem validação automática — as restrições ficam no código da aplicação | O Midaz rejeita transações que não correspondem às regras da rota |
| Adicionar taxas requer mudanças em cada integração Pix | Adicione uma nova Operation Route, crie uma nova variante de Transaction Route |
| Difícil rastrear qual padrão uma transação deveria seguir | Cada transação armazena seu ID de rota — fácil de auditar |
Pré-requisitos
Ambos os cenários assumem um ambiente Midaz com a seguinte estrutura já estabelecida:
| Entidade | Alias | Tipo | Propósito |
|---|---|---|---|
| Conta da Alice | @alice_checking | checking | Remetente — conta corrente principal da Alice |
| Conta do Bob | @bob_checking | checking | Destinatário — conta corrente principal do Bob |
| Ativo BRL | — | — | Real brasileiro, registrado como o ativo operacional |
Os valores no Midaz são representados na menor unidade da moeda. Para BRL,
15000 significa R$ 150,00 (centavos).Cenário 1: Transferência Pix simples
Alice envia R$ 150,00 para Bob via Pix. O dinheiro se move de uma conta corrente para outra — sem taxas, sem divisões, apenas uma transferência limpa entre pares.
O objetivo
- Debitar a conta corrente da Alice em R$ 150,00
- Creditar a conta corrente do Bob em R$ 150,00
- Validar que ambas as contas são do tipo
checkingantes de processar - Tornar esse padrão reutilizável para cada transferência Pix entre contas correntes
Configurando as rotas
Criar a Operation Route de origem
Esta rota define o lado de débito da transferência. A regra Salve o
account_type significa que qualquer conta do tipo checking é válida como origem — a rota não codifica um remetente específico.id retornado — você precisará dele ao construir a Transaction Route.Criar a Operation Route de destino
Esta rota define o lado de crédito. Mesmo tipo de regra: qualquer conta
checking se qualifica como destinatário válido.Executando uma transferência Pix
Com a rota estabelecida, cada transferência Pix referencia o ID da Transaction Route. O Midaz valida que as contas correspondem às regras da rota antes de processar.O que acontece internamente
O Midaz recebe a transação
A requisição inclui o ID da Transaction Route no campo
route. O Midaz carrega a configuração da rota.Validação da origem
Para cada entrada
from, o Midaz verifica a conta contra as regras da Operation Route de origem. A conta da Alice é do tipo checking — corresponde à regra account_type. A validação passa.Validação do destino
Para cada entrada
to, o Midaz verifica a conta contra as regras da Operation Route de destino. A conta do Bob é do tipo checking — a validação passa.Cenário 2: Transferência Pix com cobrança de taxa
O mesmo fluxo do Cenário 1, mas agora o banco cobra uma taxa de R$ 1,50 em cada transferência Pix. Isso adiciona uma terceira Operation Route para o destino da taxa, e o débito total da Alice aumenta para R$ 151,50.
O que muda
Você já tem as Operation Routes de origem e destino do Cenário 1. Você precisa de uma Operation Route adicional para a taxa e uma nova Transaction Route que agrupe as três.| Entidade | Alias | Tipo | Propósito |
|---|---|---|---|
| Conta de receita de taxas | @revenue_pix_fees | revenue | Conta interna que coleta taxas de transferência Pix |
Configurando a rota de taxa
Criar a Operation Route de taxa
Diferente das rotas anteriores que usam
account_type, esta usa o tipo de regra alias. Isso significa que ela aponta para uma conta específica — @revenue_pix_fees — e nenhuma outra conta pode ser utilizada.Executando uma transferência Pix com taxa
Alice envia R$ 150,00 para Bob. O banco cobra R$ 1,50. O débito total da Alice é R$ 151,50.O que isso possibilita
- Cobrança de taxas transparente — a taxa é uma entrada de ledger de primeira classe, não metadados ocultos. As equipes de finanças e conformidade veem exatamente para onde foram os R$ 1,50.
- Blocos de construção reutilizáveis — as Operation Routes de origem e destino são compartilhadas entre as variantes simples e com taxa. Você só adiciona o que muda.
- Controle no nível da rota — seu sistema pode oferecer tanto “Transferência PIX” quanto “Transferência PIX com Taxa” como produtos distintos, cada um respaldado por sua própria Transaction Route.
- Evolução fácil — precisa de uma taxa baseada em porcentagem? Uma divisão entre múltiplas contas de receita? Adicione novas Operation Routes e componha uma nova Transaction Route. Os fluxos existentes permanecem intactos.
Entendendo os tipos de regra
Os dois tipos de regra servem propósitos diferentes. Escolher o correto depende de se a conta em uma rota deve ser dinâmica ou fixa.
| Tipo de regra | Formato validIf | Comportamento | Quando usar |
|---|---|---|---|
account_type | Array de strings — ex., ["checking"] ou ["checking", "savings"] | Aceita qualquer conta que corresponda a um dos tipos especificados | Participantes dinâmicos — o remetente ou destinatário pode ser qualquer conta daquele tipo |
alias | String — ex., "@revenue_pix_fees" | Deve apontar para uma conta específica pelo seu alias | Participantes fixos — a rota sempre aponta para a mesma conta, como uma conta de taxas ou liquidação |
O que você precisa para começar
| Requisito | Detalhes |
|---|---|
| Midaz (v3.x.x+) | Ledger core com validação de Transaction Route habilitada |
| Configuração de validação de rotas | Configure TRANSACTION_ROUTE_VALIDATION no .env do serviço Transaction para incluir seu organization_id:ledger_id |
| Contas e ativo | No mínimo: duas contas de cliente e um ativo BRL registrado no ledger |
| Operation Routes | Uma por trecho de operação (origem, destino, taxa) |
| Transaction Route | Agrupa as Operation Routes em um padrão reutilizável |
A validação de Transaction Route deve ser habilitada explicitamente por ledger. Consulte Trabalhando com Transaction Routing para os passos de configuração.
Próximos passos
Transaction Routing
Entenda como as Operation Routes e Transaction Routes funcionam em um nível mais profundo.
Transações
Aprenda sobre o modelo de transações de dupla entrada do Midaz e as capacidades N:N.
Pix com taxas automatizadas
Combine o Plugin Pix com o Fees Engine para gestão automatizada de taxas.
Pix Switch
Explore a arquitetura completa do Plugin Pix e os modelos de conexão.