> ## 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 de transferência Pix reutilizáveis no Midaz com rotas de transação e rotas de operação, e aplique regras de conta e de tarifa direto no ledger. Cada transação Pix segue um padrão: debitar o remetente, creditar o recebedor e, às vezes, cobrar uma tarifa. Quando esse padrão vive apenas no código da aplicação, cada time que mexe em Pix reimplementa a mesma lógica de validação. Cada implementação é mais uma chance de inconsistência. As rotas de transação movem esse padrão para dentro do ledger. Você define as regras uma vez, e o Midaz as aplica em cada transação. O resultado é uma fonte única de verdade para como o dinheiro do Pix flui pelo seu sistema. Esta página percorre dois cenários: uma transferência peer-to-peer simples e uma transferência com tarifa. Cada cenário mostra como configurar as rotas e o que o seu time ganha com elas. ## O que as rotas de transação dão aos seus times *** Para **times de produto e de operações**, as rotas de transação dão fluxos Pix auditáveis sem regras impostas no nível da aplicação. Cada transação carrega uma referência à rota que seguiu, então as revisões de conformidade e as investigações de incidente permanecem simples. Para **times de engenharia**, as rotas removem código de validação repetitivo. Você configura as regras de conta e de tarifa uma vez. O Midaz então as aplica no nível do ledger em cada integração Pix. | Sem rotas | Com rotas | | - | - | | Cada integração deve aplicar as próprias regras de conta | Defina as regras uma vez e reutilize em todas as transações Pix | | Sem validação automática. As restrições vivem no código da aplicação | O Midaz rejeita as transações que não correspondem às regras da rota | | Acrescentar tarifas exige mudanças em cada integração Pix | Acrescente uma nova rota de operação e crie uma nova variante de rota de transação | | Difícil rastrear qual padrão uma transação deveria seguir | Cada transação guarda o ID da rota dela, então as auditorias são simples | Para um olhar mais profundo sobre como as rotas de transação e as rotas de operação funcionam, veja [Rotas contábeis](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md). ## Pré-requisitos *** Os dois cenários supõem um ambiente Midaz com a estrutura a seguir já pronta: | Entidade | Alias | Tipo | Finalidade | | - | - | - | - | | Conta da Alice | `@alice_checking` | `checking` | Remetente: conta corrente principal da Alice | | Conta do Bob | `@bob_checking` | `checking` | Recebedor: conta corrente principal do Bob | | Ativo BRL | — | — | Real brasileiro, registrado como o ativo operacional | > [!NOTE] > > Os valores no Midaz são montantes decimais. Para BRL, `150.00` significa R\$ 150,00. ## Cenário 1: transferência Pix simples *** A Alice envia R\$ 150,00 para o Bob via Pix. O dinheiro vai de uma conta corrente para outra, sem tarifas e sem splits. ### O objetivo * Debitar R\$ 150,00 da conta corrente da Alice * Creditar R\$ 150,00 na conta corrente do Bob * Validar que as duas contas são do tipo `checking` antes de processar * Tornar esse padrão reutilizável para cada transferência Pix entre contas correntes ### Configurar as rotas **1. Criar a rota de operação de origem** Esta rota define o lado de débito da transferência. A regra `account_type` aceita qualquer conta do tipo `checking` como origem. A rota não fixa 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" } } ``` Guarde o `id` retornado. Você precisa dele quando montar a rota de transação. **2. Criar a rota de operação de destino** Esta rota define o lado de crédito. Ela usa o mesmo tipo de regra: qualquer conta `checking` se qualifica como recebedor 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" } } ``` **3. Criar a rota de transação** Agrupe as duas rotas de operação em uma única rota de transação. Esta rota representa "Pix Transfer" 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 placeholder pelos IDs reais das rotas de operação dos passos anteriores. ### Executar uma transferência Pix Com a rota no lugar, cada transferência Pix referencia o ID da rota de transação no campo `routeId`. O Midaz valida que as contas correspondem às regras da rota antes de processar a transação. ```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", "routeId": "", "send": { "asset": "BRL", "value": "150.00", "source": { "from": [ { "accountAlias": "@alice_checking", "amount": { "asset": "BRL", "value": "150.00" }, "description": "Pix sent to Bob", "routeId": "" } ] }, "distribute": { "to": [ { "accountAlias": "@bob_checking", "amount": { "asset": "BRL", "value": "150.00" }, "description": "Pix received from Alice", "routeId": "" } ] } }, "metadata": { "pix_end_to_end_id": "E123456782026030614300000000001", "pix_key_type": "cpf", "pix_key": "123.456.789-00" } } ``` ### Como o Midaz valida a transação **1. O Midaz recebe a transação** A requisição carrega o ID da rota de transação 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 em relação às regras da rota de operação de origem. A conta da Alice é do tipo `checking`, então ela corresponde à regra `account_type`. A validação passa. **3. Validação do destino** Para cada entrada `to`, o Midaz verifica a conta em relação às regras da rota de operação de destino. A conta do Bob é do tipo `checking`, então a validação passa. **4. O Midaz processa a transação** As duas validações passam, então o Midaz cria a transação de forma atômica. Ele debita R\$ 150,00 de `@alice_checking` e credita R\$ 150,00 em `@bob_checking`. > [!TIP] > > Se a Alice enviar de uma conta `savings`, o Midaz rejeita a transação. A rota aceita apenas contas `checking` como origem, e você não escreve nenhuma validação no lado da aplicação. ## Cenário 2: transferência Pix com cobrança de tarifa *** Este fluxo é igual ao do Cenário 1, mas agora o banco cobra uma tarifa de R\$ 1,50 em cada transferência Pix. O fluxo acrescenta uma terceira rota de operação para o destino da tarifa, e o débito total da Alice sobe para R\$ 151,50. ### O que muda Você já tem as rotas de operação de origem e de destino do Cenário 1. Você acrescenta uma rota de operação para a tarifa e uma nova rota de transação que agrupa todas as três. | Entidade | Alias | Tipo | Finalidade | | - | - | - | - | | Conta de receita de tarifas | `@revenue_pix_fees` | `revenue` | Conta interna que recolhe as tarifas de transferência Pix | ### Configurar a rota da tarifa **1. Criar a rota de operação da tarifa** As rotas anteriores usam `account_type`. Esta usa o tipo de regra `alias`. Ela mira uma conta específica, `@revenue_pix_fees`, e nenhuma outra conta se qualifica. ```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" } } ``` **2. Criar a rota de transação com tarifa** Esta rota agrupa as rotas originais de origem e de destino com a nova rota de tarifa. Ela é uma rota de transação separada da transferência simples, então o seu sistema pode oferecer as duas 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 } } ``` ### Executar uma transferência Pix com tarifa A Alice envia R\$ 150,00 para o Bob. O banco recolhe 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", "routeId": "", "send": { "asset": "BRL", "value": "151.50", "source": { "from": [ { "accountAlias": "@alice_checking", "amount": { "asset": "BRL", "value": "151.50" }, "description": "Pix sent to Bob + transfer fee", "routeId": "" } ] }, "distribute": { "to": [ { "accountAlias": "@bob_checking", "amount": { "asset": "BRL", "value": "150.00" }, "description": "Pix received from Alice", "routeId": "" }, { "accountAlias": "@revenue_pix_fees", "amount": { "asset": "BRL", "value": "1.50" }, "description": "Pix transfer fee", "routeId": "" } ] } }, "metadata": { "pix_end_to_end_id": "E123456782026030614300000000002", "fee_amount": "1.50" } } ``` **Resultado:** o Midaz debita R\$ 151,50 da Alice. O Bob recebe R\$ 150,00. O banco recolhe R\$ 1,50. Tudo isso acontece em uma transação atômica, balanceada e auditável. ### O que você ganha com a rota da tarifa * **Cobrança de tarifa transparente**: a tarifa é um lançamento de primeira classe no ledger, não um metadado escondido. Os times de finanças e de conformidade veem exatamente para onde foi R\$ 1,50. * **Blocos reutilizáveis**: as variantes simples e com tarifa compartilham as rotas de operação de origem e de destino. Você acrescenta apenas o que muda. * **Controle no nível da rota**: o seu sistema pode oferecer "Pix Transfer" e "Pix Transfer with Fee" como produtos distintos, cada um apoiado na própria rota de transação. * **Evolução fácil**: para acrescentar uma tarifa percentual ou um split entre contas de receita, crie novas rotas de operação e componha uma nova rota de transação. Os fluxos existentes ficam intocados. ## Entender os tipos de regra *** Os dois tipos de regra servem a finalidades diferentes. A escolha certa depende de a conta em uma rota ser dinâmica ou fixa. | Tipo de regra | Formato de `validIf` | Comportamento | Quando usar | | - | - | - | - | | `account_type` | **Array de strings** (por exemplo, `["checking"]` ou `["checking", "savings"]`) | Aceita qualquer conta que corresponda a um dos tipos indicados | Participantes dinâmicos: o remetente ou o recebedor pode ser qualquer conta desse tipo | | `alias` | **String** (por exemplo, `"@revenue_pix_fees"`) | Deve mirar uma conta específica pelo alias dela | Participantes fixos: a rota sempre atinge a mesma conta, como uma conta de tarifa ou de liquidação | > [!TIP] > > Você pode combinar os dois tipos de regra dentro de uma única rota de transação. O Cenário 2 usa `account_type` para o remetente e o recebedor dinâmicos e `alias` para a conta fixa de tarifa. ## O que você precisa para começar *** | Requisito | Detalhes | | - | - | | **Midaz** (v3.x.x+) | Ledger central com a validação de rota de transação habilitada | | **Configuração de validação de rota** | Habilite a validação de rota pela API de Ledger Settings: `PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings` com `{"accounting": {"validateRoutes": true}}` | | **Contas e ativo** | No mínimo: duas contas de cliente e um ativo BRL registrado no ledger | | **Rotas de operação** | Uma por perna de operação (origem, destino, tarifa) | | **Rota de transação** | Agrupa as rotas de operação em um padrão reutilizável | > [!NOTE] > > Você deve habilitar a validação de rota de transação para cada ledger. Veja [Trabalhar com rotas contábeis](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md#working-with-accounting-routes) para os passos de configuração. ## Próximos passos *** > [card] [Rotas contábeis](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md) > > Entenda como as rotas de operação e as rotas de transação funcionam em um nível mais profundo. > [card] [Transações](https://docs.lerian.studio/pt/products/midaz/transactions.md) > > Conheça o modelo de transação por partidas dobradas do Midaz e os recursos N:N. > [card] [Pix com tarifas automatizadas](https://docs.lerian.studio/pt/interfaces/pix/midaz-for-pix-with-fees.md) > > Combine o plugin Pix com o Fees Engine para gestão automatizada de tarifas. > [card] [Pix Lerian](https://docs.lerian.studio/pt/interfaces/pix-lerian.md) > > Explore a interface unificada para pagamentos, chaves, cobranças e devoluções. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.