Por que isso importa
Para equipes de produto e operações, as Transaction Routes dão a você fluxos Pix auditáveis sem cumprimento no nível da aplicação. Cada transação carrega uma referência à rota que seguiu, então revisões de conformidade e investigações de incidentes permanecem simples. Para equipes de engenharia, as rotas removem código de validação repetitivo. Você configura as regras de conta e de tarifa uma vez. Depois o Midaz as aplica no nível do ledger em cada integração Pix.
Para uma visão mais aprofundada de como as Transaction Routes e Operation Routes funcionam, consulte Rotas Contábeis.
Pré-requisitos
Ambos os cenários assumem um ambiente Midaz com a seguinte estrutura já estabelecida:
Os valores no Midaz são montantes decimais. Para BRL,
150.00 significa R$ 150,00.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
Configurar as rotas
1
Criar a Operation Route de origem
Esta rota define o lado de débito da transferência. A regra Salve o
account_type aceita qualquer conta do tipo checking como origem. A rota não codifica um remetente específico.id retornado — você precisa dele ao construir a Transaction Route.2
Criar a Operation Route de destino
Esta rota define o lado de crédito. Usa o mesmo tipo de regra: qualquer conta
checking se qualifica como destinatário válido.3
Criar a Transaction Route
Agrupe ambas as Operation Routes em uma única Transaction Route. Esta rota representa “Transferência Pix” no seu sistema.Substitua os IDs de exemplo pelos IDs reais das Operation Routes dos passos anteriores.
Executar uma transferência Pix
Com a rota estabelecida, cada transferência Pix referencia o ID da Transaction Route no camporouteId. O Midaz valida que as contas correspondem às regras da rota antes de processar a transação.
O que acontece internamente
1
O Midaz recebe a transação
A requisição carrega o ID da Transaction Route no campo
routeId. O Midaz carrega a configuração da rota.2
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, então corresponde à regra account_type. A validação passa.3
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, então a validação passa.4
O Midaz processa a transação
Ambas as validações passam, então o Midaz cria a transação atomicamente. Ele debita
@alice_checking em R$ 150,00 e credita @bob_checking em R$ 150,00.Cenário 2: Transferência Pix com cobrança de tarifa
Este fluxo corresponde ao Cenário 1, mas agora o banco cobra uma tarifa de R$ 1,50 em cada transferência Pix. O fluxo adiciona uma terceira Operation Route para o destino da tarifa, e o débito total da Alice sobe para R$ 151,50.
O que muda
Você já tem as Operation Routes de origem e destino do Cenário 1. Você adiciona uma Operation Route para a tarifa e uma nova Transaction Route que agrupa as três.Configurar a rota da tarifa
1
Criar a Operation Route de tarifa
As rotas anteriores usam
account_type. Esta usa o tipo de regra alias em vez disso. Ela aponta para uma conta específica — @revenue_pix_fees — e nenhuma outra conta se qualifica.2
Criar a Transaction Route com tarifa
Esta rota agrupa as rotas de origem e destino originais com a nova rota de tarifa. É uma Transaction Route separada da transferência simples, então seu sistema pode oferecer ambas as variantes.
Executar uma transferência Pix com tarifa
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 tarifas transparente — a tarifa é 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 variantes simples e com tarifa compartilham as Operation Routes de origem e destino. Você adiciona apenas o que muda.
- Controle no nível da rota — seu sistema pode oferecer tanto “Transferência Pix” quanto “Transferência Pix com Tarifa” como produtos distintos, cada um respaldado por sua própria Transaction Route.
- Evolução fácil — para adicionar uma tarifa baseada em porcentagem ou uma divisão entre contas de receita, crie novas Operation Routes e componha uma nova Transaction Route. Os fluxos existentes permanecem intactos.
Entender os tipos de regra
Os dois tipos de regra servem propósitos diferentes. A escolha correta depende de se a conta em uma rota é dinâmica ou fixa.
O que você precisa para começar
Você deve habilitar a validação de Transaction Route para cada ledger. Consulte Trabalhando com Rotas Contábeis para os passos de configuração.
Próximos passos
Rotas Contábeis
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 tarifas automatizadas
Combine o Plugin Pix com o Fees Engine para gestão automatizada de tarifas.
Pix Switch
Explore a arquitetura completa do Plugin Pix e os modelos de conexão.