Por que isso importa
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.
Para um olhar mais profundo sobre como as rotas de transação e as rotas de operação funcionam, veja Rotas contábeis.
Pré-requisitos
Os dois cenários supõem um ambiente Midaz com a estrutura a seguir já pronta:
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
checkingantes 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 Guarde o
account_type aceita qualquer conta do tipo checking como origem. A rota não fixa um remetente específico.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.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.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 camporouteId. O Midaz valida que as contas correspondem às regras da rota antes de processar a transação.
O que acontece nos bastidores
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.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.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.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.
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.O que isso destrava
- 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.
O que você precisa para começar
Você deve habilitar a validação de rota de transação para cada ledger. Veja Trabalhar com rotas contábeis para os passos de configuração.
Próximos passos
Rotas contábeis
Entenda como as rotas de operação e as rotas de transação funcionam em um nível mais profundo.
Transações
Conheça o modelo de transação por partidas dobradas do Midaz e os recursos N:N.
Pix com tarifas automatizadas
Combine o plugin Pix com o Fees Engine para gestão automatizada de tarifas.
Pix Lerian
Explore a interface unificada para pagamentos, chaves, cobranças e devoluções.