Por que essa combinação importa
Cada componente resolve uma camada específica do problema:
| Componente | Papel |
|---|---|
| Midaz | Ledger central — registra cada débito, crédito e movimentação de taxa com precisão de partida dobrada |
| Plugin Pix | Conectividade Pix — orquestra transações, DICT, QR Codes e liquidação através do modelo de participação escolhido |
| Fees Engine | Automação de taxas — calcula, distribui e roteia taxas com base em pacotes configuráveis |
Escolhendo seu modelo de participação Pix
O Plugin Pix suporta ambos os modelos de participação definidos pelo BACEN. A integração de taxas e o fluxo do ledger descritos nesta página se aplicam igualmente a ambos — a diferença está em como sua instituição se conecta à infraestrutura do BACEN.
| Pix Indireto | Pix Direto | |
|---|---|---|
| Como conecta | Através de um Participante Direto (ex.: BTG) | Diretamente ao SPI/DICT via PSTI certificado (ex.: JD) |
| Ideal para | Fintechs e instituições de pagamento buscando onboarding rápido | Bancos e IFs reguladas com autonomia operacional total |
| Responsabilidade regulatória | Compartilhada com o Participante Direto | Totalmente da instituição |
| Time to market | Semanas | Mais longo, mas com controle máximo |
| Integração com Fees Engine | Nativa | Nativa |
| Integração com Midaz | Obrigatória | Obrigatória |
Cenário 1: Fintech lançando Pix com taxas automatizadas
Uma fintech está se preparando para oferecer Pix aos seus clientes. Ela precisa cobrar uma taxa fixa em cada Pix recebido (cash-in) para cobrir custos operacionais e gerar receita — sem adicionar complexidade à experiência do cliente. Seja operando como participante indireto (via BTG) ou como participante direto (via JD), a lógica de taxas e a estrutura do ledger permanecem as mesmas.
O objetivo de negócio
- Oferecer pagamentos Pix instantâneos aos clientes finais
- Cobrar uma taxa transparente e configurável em transferências recebidas
- Registrar cada taxa no ledger para compliance e relatórios financeiros
- Lançar rapidamente, sem construir lógica de taxas customizada ou pipelines de reconciliação
Configurando com o Midaz
A fintech começa estruturando seu ambiente Midaz:Criar a Organização
Registre a fintech como uma Organização no Midaz. Esta é a entidade de nível superior que possui todos os ledgers, contas e transações.
Configurar o Ledger
Crie um Ledger para rastrear todas as transações de clientes e movimentações de taxas. Este ledger é compartilhado pelo Plugin Pix e pelo Fees Engine.
Definir o Ativo
Registre BRL como o ativo operacional. Todas as transações Pix e cálculos de taxas usam este ativo.
Criar contas de clientes
Cada cliente recebe uma conta no ledger. Essas contas recebem créditos Pix e estão sujeitas às regras de taxas.
Criar contas de destino de taxas
Configure contas internas para receber créditos de taxas — por exemplo, uma conta “Receita de Taxas Pix”. Essas são referenciadas na configuração do pacote do Fees Engine.
Configurando o Fees Engine
Com a estrutura do ledger pronta, a fintech configura um pacote de taxas:- Tipo de taxa: Taxa fixa de R$ 1,50 por Pix recebido
- Escopo: Aplicada a todas as transações de cash-in no ledger principal
- Roteamento: Créditos de taxa são direcionados para a conta interna “Receita de Taxas Pix”
- Isenções: Contas do nível Premium são adicionadas à lista de contas isentas
Pacotes de taxas são configurados uma vez e aplicados automaticamente. Quando uma transação Pix corresponde aos critérios do pacote (ledger, segmento, faixa de valor), o Fees Engine calcula e roteia a taxa sem qualquer intervenção manual.
Como uma transação flui
Quando um cliente recebe uma transferência Pix, eis o que acontece nos bastidores:Pix chega
A instituição remetente inicia um Pix. Seu provedor de conectividade (BTG para indireto, JD para direto) recebe a transação e notifica o Plugin Pix.
Transação é validada
O plugin valida o destinatário: verifica se a conta existe, está ativa e pode receber fundos. Dados do CRM e validade da chave Pix também são verificados.
Liquidação começa
Uma vez confirmada a transação, o processo de liquidação inicia. O plugin busca os detalhes da conta de destino no Midaz.
Taxas são calculadas automaticamente
O Fees Engine avalia a transação contra os pacotes de taxas disponíveis. Encontra um pacote correspondente e calcula a taxa fixa de R$ 1,50.
Ledger registra o quadro completo
O Midaz registra a transação com a distribuição de taxas em uma única operação:
- A conta do cliente é creditada com o valor líquido (bruto menos taxa).
- A conta de destino de taxa é creditada com R$ 1,50.
- Cada movimentação é rastreável, com precisão de partida dobrada.
O que isso desbloqueia
- Sem lógica de taxas customizada — o Fees Engine cuida do cálculo, roteamento e isenções.
- Ledger preciso — cada taxa é um lançamento no ledger, não apenas metadado. Auditores veem os mesmos números que seu time financeiro.
- Segmentação de clientes — clientes Premium podem ser isentos automaticamente usando contas isentas.
- Flexibilidade de taxas — altere valores, adicione taxas percentuais ou introduza limites baseados em valor sem mudar seu pipeline de transações.
Cenário 2: Marketplace com Pix e taxas proporcionais
Um marketplace B2B conecta compradores e vendedores. Compradores pagam via Pix, e o marketplace cobra uma taxa de serviço em cada transação antes de distribuir o valor restante aos vendedores.
O objetivo de negócio
- Aceitar pagamentos Pix de compradores
- Cobrar uma taxa de serviço percentual em cada pagamento
- Distribuir o valor líquido proporcionalmente entre múltiplos vendedores quando um único pagamento cobre produtos de diferentes vendedores
- Manter uma trilha de auditoria clara para cada split e taxa
Configurando com o Midaz
O marketplace estrutura seu ambiente Midaz para refletir a natureza multi-parte de suas operações:Configurar o Ledger
Crie um único Ledger para gerenciar todos os fluxos de pagamento — pagamentos de compradores, créditos de vendedores e taxas do marketplace.
Criar contas de vendedores
Cada vendedor recebe uma conta no ledger. Quando um comprador paga via Pix, o valor líquido é distribuído entre as contas dos vendedores relevantes.
Criar a conta de taxa do marketplace
Uma conta interna (ex.: “Taxa de Serviço do Marketplace”) recebe a porção de taxa de cada transação.
Configurando o Fees Engine
O marketplace configura um pacote de taxas com distribuição proporcional:- Tipo de taxa: 3% do valor da transação
- Escopo: Aplicada a todos os pagamentos Pix recebidos no ledger do marketplace
- Distribuição: Taxas são divididas proporcionalmente entre as contas de origem quando múltiplos vendedores participam de uma única transação
- Roteamento: Créditos de taxa vão para a conta “Taxa de Serviço do Marketplace”
- Dedutível: A taxa é deduzida do valor recebido pelos vendedores (
isDeductibleFrom: true), então o comprador sempre envia o valor total
Como uma transação flui
Um comprador adquire R$ 1.000 em produtos de três vendedores:| Vendedor | Participação | Valor bruto |
|---|---|---|
| Vendedor A | 50% | R$ 500,00 |
| Vendedor B | 30% | R$ 300,00 |
| Vendedor C | 20% | R$ 200,00 |
Comprador envia Pix
O comprador escaneia um QR Code ou usa uma chave Pix para enviar R$ 1.000 ao marketplace.
Taxas são calculadas com split proporcional
O Fees Engine calcula uma taxa de 3% (R$ 30,00) e distribui proporcionalmente:
- Vendedor A: R 485,00 líquido)
- Vendedor B: R 291,00 líquido)
- Vendedor C: R 194,00 líquido)
Ledger registra cada movimentação
O Midaz cria a transação com distribuição completa:
- Conta do Vendedor A: creditada R$ 485,00
- Conta do Vendedor B: creditada R$ 291,00
- Conta do Vendedor C: creditada R$ 194,00
- Conta de taxa do marketplace: creditada R$ 30,00
- Total: R$ 1.000,00 — totalmente balanceado
O que isso desbloqueia
- Split de receita automatizado — o Fees Engine cuida da distribuição proporcional entre qualquer número de contas.
- Precificação transparente para vendedores — cada vendedor sabe exatamente qual taxa foi cobrada e por quê.
- Ledger balanceado — o valor bruto de entrada é igual à soma de todos os créditos de saída. Sem diferenças de arredondamento, sem ajustes manuais.
- Taxas configuráveis — altere o percentual, adicione mínimos fixos ou isente parceiros específicos — tudo pela configuração do pacote de taxas.
O que você precisa para começar
Para executar essa configuração, sua instituição precisa de:
| Requisito | Detalhes |
|---|---|
| Midaz (v3.x.x+) | Ledger central para gestão de contas e registro de transações |
| Plugin Pix | Conectividade Pix — escolha Indireto (via BTG) ou Direto (via JD) baseado no seu modelo de participação |
| Fees Engine | Cálculo e roteamento automatizado de taxas |
| Plugin CRM | Metadados de clientes e contas usados durante a validação Pix |
| Infraestrutura | Nuvem própria (BYOC) ou ambiente on-premise |
| Contrato de conectividade | Acordo com BTG (indireto) ou JD/PSTI (direto) dependendo do seu modelo |
O Plugin Pix e o Fees Engine requerem uma licença Lerian válida. Para detalhes de licença, veja a documentação de Licença.
Simulando antes de ir para produção
Antes de processar transações reais, use a funcionalidade de simulação do Fees Engine para validar sua configuração de taxas. Simulações permitem:
- Visualizar exatamente como as taxas serão calculadas para um dado valor de transação
- Verificar que isenções funcionam como esperado
- Confirmar que splits proporcionais produzem a distribuição correta
- Testar casos extremos como valores limítrofes e contas isentas
Próximos passos
Visão geral do Fees Engine
Entenda pacotes de taxas, regras de cálculo e opções de roteamento.
Usando o Fees Engine
Guia passo a passo para criar pacotes e processar taxas.
Pix Direto vs. Indireto
Compare modelos de participação e escolha o plugin certo.
Visão geral do Plugin Pix
Explore a arquitetura completa do Plugin Pix e modelos de conexão.

