> ## 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. # Midaz com Rotas de Transação Pix > Modele fluxos Pix validados e reutilizáveis com Transaction e Operation Routes, de pagamentos entre pessoas a cobrança de tarifas. Toda transação Pix segue um padrão: debitar o remetente, creditar o destinatário, talvez cobrar uma taxa. Quando esse padrão existe apenas no código da aplicação, cada equipe que toca o Pix precisa reimplementar a mesma lógica de validação — e cada implementação é uma chance de inconsistência. As Transaction Routes movem esse padrão para o próprio ledger. Você define as regras uma vez, e o Midaz as aplica em cada transação automaticamente. O resultado são menos erros de integração, uma trilha de auditoria clara e uma única fonte de verdade sobre como o dinheiro Pix flui pelo seu sistema. Esta página percorre dois cenários do mundo real — uma transferência simples entre pares e uma transferência com cobrança de taxa — mostrando como configurar rotas e o que sua equipe ganha ao usá-las. ## 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 | Para uma visão mais aprofundada de como as Transaction Routes e Operation Routes funcionam, consulte [Rotas Contábeis](/pt/midaz/transaction-routing-entities). ## 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 `checking` antes de processar * Tornar esse padrão reutilizável para cada transferência Pix entre contas correntes ### Configurando as rotas Esta rota define o lado de débito da transferência. A regra `account_type` significa que qualquer conta do tipo `checking` é válida como origem — a rota não codifica um remetente específico. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes { "title": "PIX - Debit Sender", "description": "Debits the sender's checking account in a Pix transfer", "code": "PIX-SEND-SRC", "operationType": "source", "account": { "ruleType": "account_type", "validIf": ["checking"] }, "metadata": { "payment_method": "pix", "direction": "outbound" } } ``` Salve o `id` retornado — você precisará dele ao construir a Transaction Route. Esta rota define o lado de crédito. Mesmo tipo de regra: qualquer conta `checking` se qualifica como destinatário válido. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes { "title": "PIX - Credit Receiver", "description": "Credits the receiver's checking account in a Pix transfer", "code": "PIX-SEND-DST", "operationType": "destination", "account": { "ruleType": "account_type", "validIf": ["checking"] }, "metadata": { "payment_method": "pix", "direction": "inbound" } } ``` Agrupe ambas as Operation Routes em uma única Transaction Route. Este é o padrão que representa "Transferência Pix" no seu sistema. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes { "title": "PIX Transfer", "description": "Standard Pix transfer between two checking accounts", "operationRoutes": [ "", "" ], "metadata": { "payment_rail": "pix", "spi_message_type": "pacs.008", "regulation": "BCB_PIX" } } ``` Substitua os IDs de exemplo pelos IDs reais das Operation Routes retornados nos passos anteriores. ### 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. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json { "chartOfAccountsGroupName": "PIX", "description": "Pix transfer from Alice to Bob", "code": "PIX-20260306-001", "route": "", "send": { "asset": "BRL", "value": 15000, "source": { "from": [ { "accountAlias": "@alice_checking", "amount": { "asset": "BRL", "value": 15000 }, "description": "Pix sent to Bob", "route": "" } ] }, "distribute": { "to": [ { "accountAlias": "@bob_checking", "amount": { "asset": "BRL", "value": 15000 }, "description": "Pix received from Alice", "route": "" } ] } }, "metadata": { "pix_end_to_end_id": "E123456782026030614300000000001", "pix_key_type": "cpf", "pix_key": "123.456.789-00" } } ``` ### O que acontece internamente A requisição inclui o ID da Transaction Route no campo `route`. O Midaz carrega a configuração da rota. 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. 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. Ambas as validações passam, então o Midaz cria a transação atomicamente: debita `@alice_checking` em R\$ 150,00 e credita `@bob_checking` em R\$ 150,00. Se Alice tentasse enviar de uma conta `savings`, o Midaz rejeitaria a transação — a rota só aceita contas `checking` como origem. Nenhuma validação do lado da aplicação é necessária. ## 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 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. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes { "title": "PIX - Fee Collection", "description": "Credits the bank's revenue account with the Pix transfer fee", "code": "PIX-FEE-DST", "operationType": "destination", "account": { "ruleType": "alias", "validIf": "@revenue_pix_fees" }, "metadata": { "fee_type": "pix_transfer_fee" } } ``` Esta rota agrupa as rotas de origem e destino originais com a nova rota de taxa. É uma Transaction Route separada da transferência simples — seu sistema pode oferecer ambas as variantes. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes { "title": "PIX Transfer with Fee", "description": "Pix transfer between checking accounts with fee collection", "operationRoutes": [ "", "", "" ], "metadata": { "payment_rail": "pix", "includes_fee": true } } ``` ### 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. ```json theme={null} POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json { "chartOfAccountsGroupName": "PIX", "description": "Pix transfer from Alice to Bob (with fee)", "code": "PIX-20260306-002", "route": "", "send": { "asset": "BRL", "value": 15150, "source": { "from": [ { "accountAlias": "@alice_checking", "amount": { "asset": "BRL", "value": 15150 }, "description": "Pix sent to Bob + transfer fee", "route": "" } ] }, "distribute": { "to": [ { "accountAlias": "@bob_checking", "amount": { "asset": "BRL", "value": 15000 }, "description": "Pix received from Alice", "route": "" }, { "accountAlias": "@revenue_pix_fees", "amount": { "asset": "BRL", "value": 150 }, "description": "Pix transfer fee", "route": "" } ] } }, "metadata": { "pix_end_to_end_id": "E123456782026030614300000000002", "fee_amount": 150 } } ``` **Resultado:** Alice é debitada em R\$ 151,50. Bob recebe R\$ 150,00. O banco coleta R\$ 1,50 em taxas. Tudo em uma única transação atômica — totalmente balanceada, totalmente auditável. ### 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 | Você pode combinar ambos os tipos de regra dentro de uma única Transaction Route. O Cenário 2 faz exatamente isso: `account_type` para o remetente e destinatário dinâmicos, `alias` para a conta de taxas fixa. ## 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** | Habilite a validação de rotas via API de Configurações do Ledger: `PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings` com `{"validateRoutes": true}` | | **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 Rotas Contábeis](/pt/midaz/transaction-routing-entities#trabalhando-com-rotas-contábeis) para os passos de configuração. ## Próximos passos *** Entenda como as Operation Routes e Transaction Routes funcionam em um nível mais profundo. Aprenda sobre o modelo de transações de dupla entrada do Midaz e as capacidades N:N. Combine o Plugin Pix com o Fees Engine para gestão automatizada de taxas. Explore a arquitetura completa do Plugin Pix e os modelos de conexão.