Usando o Fees Engine

O Fees Engine aplica tarifas por transação e calcula cobranças de faturamento periódicas. Este guia cobre os dois fluxos: pacotes de tarifas (por transação) e pacotes de faturamento (por período).

Os pacotes de tarifas aplicam cobranças no momento da transação. Os pacotes de faturamento calculam cobranças ao longo de um período (diário, semanal ou mensal) para o seu orquestrador executar. Você pode usar os dois simultaneamente.

Pacotes de tarifas: fluxo por transação

Os pacotes de tarifas aplicam cobranças de forma síncrona quando você cria uma transação v2. Esta seção mostra o processo, da configuração da tarifa até os resultados.

Passo 1 - Crie seus pacotes de tarifas

Primeiro, configure pacotes de tarifas que definem como o mecanismo aplica as tarifas. Use o endpoint Criar um Pacote. Cada pacote contém um conjunto de regras de tarifa e critérios de correspondência. Você pode adaptar os pacotes a diferentes ledgers, segmentos e rotas de transação com estes campos:

transactionRoute - O ID de uma rota de transação, quando você precisa de correspondência no nível da rota.
segmentId - O ID do segmento ao qual as contas de origem pertencem, quando você precisa de correspondência no nível do segmento.
metadataSelector - Pares de metadados que a transação precisa ter, quando você precisa de correspondência no nível de metadados.
Escopo do ledger - A URL da requisição identifica qual ledger registra a transação; não envie ledgerId no corpo do pacote.
Valor mínimo e máximo - Limites para a aplicação da tarifa.
routeFrom / routeTo - Definem como cada tarifa se move pelos fluxos contábeis.

Esses campos permitem aplicar tarifas distintas para cada cenário, de configurações baseadas em conta a configurações baseadas em valor. Gerenciando pacotes Os seguintes endpoints também estão disponíveis para você gerenciar os pacotes:

Listar Pacotes - Lista todos os pacotes criados.
Buscar um Pacote - Busca informações de um pacote específico.
Atualizar um Pacote - Atualiza as informações de um pacote específico.
Excluir um Pacote - Faz o soft delete de um pacote.

(opcional) Passo 2 - Execute uma estimativa

Para visualizar como um pacote de tarifas se comporta antes de confirmar uma transação real, use o endpoint Estimar Tarifas de Transação. Essa estimativa ajuda a validar:

Quais regras de tarifa se aplicam.
Como o pacote vai se comportar com os valores informados.
Se alguma isenção se aplica.

Passo 3 - Crie uma transação

Depois de configurar os pacotes, crie a transação pela API de transações v2, por exemplo com o endpoint criar uma transação no modelo direto v2. Apenas transações v2 aplicam tarifas, incluindo os itens diretos e de hold de um lote v2. Para corresponder a um pacote com escopo de rota, envie o ID da rota de transação em routeId. O Midaz lê o segmento das contas de origem.

Passo 4 - O Fees Engine avalia os pacotes

O Fees Engine é executado no mesmo processo quando o Midaz cria a transação. Ele avalia se um pacote se aplica, com base em:

transactionRoute, quando configurado
segmentId, quando configurado
metadataSelector, quando configurado
Escopo do ledger a partir da URL da requisição
Valor mínimo e máximo
waivedAccounts, quando configurado para isenções de tarifa

O Fees Engine seleciona no máximo um pacote por transação: a correspondência mais específica. Cada par de metadataSelector torna um pacote mais específico. Quando dois pacotes correspondem igualmente, o Midaz recusa a transação com o erro 0198.

Uma conta de origem com um plano de tarifas ativo paga as tarifas do plano dela, e o pacote não a cobra.

Passo 5 - Verifique as isenções

O sistema verifica:

Se nenhum pacote correspondente cobre o valor da transação.
Se todas as contas de origem são isentas.

Se qualquer uma das condições for verdadeira, o Fees Engine não aplica tarifas e a transação segue normalmente. Uma tarifa cujo cálculo totaliza zero não adiciona lançamento de tarifa, por exemplo uma tarifa definida como 0 em um pacote para uma faixa de valores. Quando uma tarifa definida como 0 deixa a transação sem lançamento de tarifa, os metadados da transação registram feeExemption com o motivo zero_fee_amount, e packageAppliedID indica o pacote. A conta externa (@external/<asset>) que o Midaz adiciona a uma transação entre ledgers nunca paga tarifa.

Passo 6 - Cálculo e aplicação da tarifa

Se um pacote se aplica, o Fees Engine:

Calcula os valores da tarifa com base no applicationRule selecionado.
Aplica as tarifas proporcionalmente entre as contas, se necessário.
Usa isDeductibleFrom para definir se adiciona ou deduz a tarifa.
Direciona as tarifas para o creditAccount correto com o routeFrom e o routeTo configurados.
Retorna o resultado completo da transação junto com o packageAppliedID nos metadados.

Passo 7 - Atualizações no ledger

Depois que o Fees Engine calcula as tarifas, o componente Transactions assume. Ele processa:

Débitos das contas de origem
Créditos para os destinos da tarifa
Detalhamento da tarifa por rota e conta

O ledger armazena cada movimento para rastreabilidade e auditabilidade completas.

Passo 8 - Revise e confirme

Depois da execução, você pode:

Inspecionar a transação final e os valores por conta.
Confirmar qual pacote de tarifas foi aplicado.
Verificar todos os movimentos de tarifa por meio dos metadados e dos registros do ledger.

Precifique um TED ou Pix por um contexto de tarifa

Um contexto de tarifa é um rótulo que você escolhe para uma transferência de saída, por exemplo ted_salario. Um pacote de tarifas que seleciona pelo rótulo precifica a transferência. Isso exige o Midaz 4.2.0 ou posterior, com o Bank Transfer 3.4.0 ou posterior para TED e o Pix JD 1.5.0 ou posterior para Pix. Versões anteriores dos dois plugins recusam o campo com 400. Envie o rótulo em feeContext, no nível mais alto do corpo da requisição de POST /v1/transfers/initiate para TED e P2P, ou de POST /v1/transactions para Pix. O rótulo é uma letra minúscula, seguida de até 49 letras minúsculas, dígitos ou sublinhados. Nunca coloque dados pessoais nele. Uma leitura da transferência retorna feeContext.

Crie o pacote do rótulo

Crie o pacote no ledger do pagador, com metadataSelector igual a {"feeContext": "<label>"}. A chave é exatamente feeContext. O Midaz aplica o pacote que atende ao maior número de condições. Dê ao pacote do rótulo cada condição do pacote que precifica a mesma transferência sem rótulo: o transactionRoute, o segmentId e os pares de metadataSelector dele. Depois adicione o par feeContext. Com menos condições, o pacote do rótulo pode perder para esse pacote ou empatar com ele, e o Midaz recusa um empate com o erro 0198. Na iniciação, o Bank Transfer responde 422 BTF-2005.

Quando o plugin recusa o rótulo

O Bank Transfer e o Pix JD conferem o rótulo uma vez, quando aceitam a transferência. Quando o recusam, nada fica retido.

Caso	TED	Pix
O rótulo está malformado.	`400 BTF-0001`	`400 PIX-0061`
O modo de tarifa do plugin, `MIDAZ_FEE_MODE`, não resolve para `native`.	`422 BTF-0008`	`422 PIX-0162`
Nenhum pacote do ledger do pagador, habilitado ou desabilitado, seleciona pelo rótulo.	`422 BTF-0008`	`422 PIX-0162`

O Pix JD também recusa um rótulo em uma ordem que traz indirectId, com 400 PIX-0061.

Depois que o plugin aceita o rótulo

O plugin grava o rótulo com a transferência, e cada tentativa de lançar a transferência o leva. Se você desabilitar ou apagar o pacote depois, o plugin não recusa uma transferência que ele já aceitou. Um lançamento feito depois disso é precificado pelos pacotes que continuam habilitados. O rótulo vale apenas para o que o pagador envia: o TED OUT, a transferência P2P e o Pix de saída. Ele nunca vale para um TED ou Pix recebido, uma devolução, MED ou Pix Automático. No Bank Transfer, uma transferência P2P entre dois ledgers leva o rótulo aos dois ledgers. Cada ledger precifica a própria parte com os próprios pacotes, e no ledger do destinatário apenas uma tarifa descontada do valor se aplica.

Por que estimar uma transação?

As estimativas permitem visualizar como um pacote de tarifas específico se comporta, sem executar uma transação real nem gravar no ledger. Use estimativas quando:

Você quer testar um pacote específico.
Você depura regras de tarifa ou limites.
Você quer validar isenções, intervalos de valor ou divisões proporcionais.
Você precisa de uma visualização antes de criar uma transação real.
Você constrói uma interface e quer mostrar tarifas estimadas.

O Fees Engine oferece o endpoint Estimar Tarifas de Transação para essa finalidade. Você informa um packageId, e o endpoint retorna o que aconteceria se esse pacote exato fosse aplicado. Uma estimativa não lê as atribuições de planos de tarifas.

O que você obtém com uma estimativa?

Uma estimativa completa das regras de tarifa.
Quais contas o mecanismo cobraria.
Como o mecanismo dividiria a tarifa.
Nenhum impacto no ledger.

Use estimativas quando você ainda não estiver pronto para confirmar a transação, ou quiser dar aos seus usuários uma visualização clara da tarifa.

Erros comuns

O Fees Engine valida cada requisição quanto à consistência e à lógica correta da tarifa. Abaixo estão os problemas mais frequentes que você pode ver ao criar pacotes ou processar transações.

Código	Título	Mensagem
0009	Campos ausentes na requisição	Sua requisição está sem um ou mais campos obrigatórios: `<fields>`. Consulte a documentação para garantir que todos os campos necessários estejam incluídos na sua requisição.
0007	Entidade não encontrada	Nenhuma entidade foi encontrada para o ID informado. Use o ID correto da entidade que você está tentando gerenciar.
0180	Prioridade de tarifa inválida	O campo de prioridade nas tarifas é inválido. O campo não pode ser repetido.
0182	minimumAmount maior que maximumAmount	O valor de minimumAmount é maior que maximumAmount.
0186	Falha ao calcular a tarifa	Falha ao calcular a tarifa da transação. Verifique a configuração da tarifa e tente novamente.
0188	originalAmount é obrigatório quando priority é um	Para Priority igual a um, referenceAmount deve ser ‘originalAmount’ para a tarifa `<fee>`.
0189	Falha ao aplicar a regra: flatFee ou percentual	O applicationRule flatFee ou percentual deve ter exatamente 1 cálculo para a tarifa `<fee>`.
0198	Erro na filtragem de pacotes	Mais de um pacote de tarifas corresponde a esta transação com a mesma especificidade, então nenhum deles pode ser aplicado. Redefina o escopo de um destes pacotes: `<package IDs>`.
0199	Sobreposição do intervalo de valor do pacote	O maximumAmount e o minimumAmount do novo pacote se sobrepõem ao intervalo de valor de um pacote existente.
0530	Tarifa dedutível não pode ser diferível	A tarifa `<fee>` é deduzida do pagamento (isDeductibleFrom true), então não pode ser diferível. Defina deferrable como false ou isDeductibleFrom como false.

Pacotes de faturamento: fluxo por período

Os pacotes de faturamento calculam cobranças com base no volume acumulado de transações ou na manutenção por conta ao longo de um período de faturamento. Diferente dos pacotes de tarifas, o seu orquestrador aciona o faturamento. Ele decide quando calcular e executa as cobranças resultantes.

Passo 1: Crie os pacotes de faturamento

Configure pacotes de faturamento que definem suas regras de cobrança periódica. Cada pacote é do tipo volume ou manutenção. Exemplo de pacote de volume, uma cobrança por Pix enviado com precificação em camadas:

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Pix Send Monthly Billing",
  "description": "Monthly volume billing for Pix transactions",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 100, "unitPrice": "0.50" },
    { "minQuantity": 101, "maxQuantity": 500, "unitPrice": "0.35" },
    { "minQuantity": 501, "maxQuantity": null, "unitPrice": "0.20" }
  ],
  "freeQuota": 10,
  "discountTiers": [
    { "minQuantity": 200, "discountPercentage": "5.00" },
    { "minQuantity": 400, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-revenue"
}

Exemplo de pacote de manutenção, uma tarifa mensal por conta PF ativa:

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active PF accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "0198e5f4-7b2a-7c3d-9e1f-2a3b4c5d6e7f"
  }
}

Passo 2: Acione o cálculo do faturamento

Chame POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate com o período de faturamento. A URL identifica o ledger. O mecanismo avalia cada pacote de faturamento habilitado no ledger, limitado ao type que você envia.

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate

Body:
{
  "period": "2026-03",
  "type": "volume"
}

O campo period aceita três formatos: YYYY-MM (mensal), YYYY-Www (semanal, por exemplo, 2026-W13), e YYYY-MM-DD (diário). O campo type é opcional. Use "volume" ou "maintenance" para restringir o cálculo a um tipo. Omita-o para calcular os dois tipos em uma única chamada.

Passo 3: Receba os resultados do cálculo

Cada resultado inclui:

O pacote de faturamento que o gerou.
Os valores calculados.

Passo 4: Execute as cobranças

Envie cada transactionPayload não vazio ao Midaz com Criar uma transação usando JSON (POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json) para criar as transações de faturamento. Um objeto vazio significa que não há cobrança a executar.

O mecanismo de faturamento calcula e retorna resultados. Ele não cria transações no Midaz. O seu orquestrador controla quando e como executa as cobranças.

Passo 5: Revise e concilie

Depois de executar as cobranças:

Verifique se as transações criadas no Midaz correspondem aos resultados do cálculo de faturamento.
Use os metadados de auditoria dos payloads de transação não vazios para a conciliação.
O cálculo de faturamento é stateless. Uma nova execução para o mesmo período reflete o ledger no momento dessa execução.

Gerenciando pacotes de faturamento

Use estes endpoints para gerenciar pacotes de faturamento existentes:

GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages: Lista todos os pacotes de faturamento.
GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: Busca um pacote de faturamento específico.
PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: Atualiza um pacote de faturamento (apenas label, description, enable).
DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{billing_package_id}: Faz o soft delete de um pacote de faturamento.

Se algum pacote falhar durante o cálculo, a operação inteira falha e não retorna resultados parciais. O cálculo de faturamento segue uma política tudo ou nada. Corrija o pacote com falha e execute novamente.

Midaz Core

CRM

Fees

Usando o Fees Engine

Pacotes de tarifas: fluxo por transação

Passo 1 - Crie seus pacotes de tarifas

(opcional) Passo 2 - Execute uma estimativa

Passo 3 - Crie uma transação

Passo 4 - O Fees Engine avalia os pacotes

Passo 5 - Verifique as isenções

Passo 6 - Cálculo e aplicação da tarifa

Passo 7 - Atualizações no ledger

Passo 8 - Revise e confirme

Precifique um TED ou Pix por um contexto de tarifa

Crie o pacote do rótulo

Quando o plugin recusa o rótulo

Depois que o plugin aceita o rótulo

Por que estimar uma transação?

O que você obtém com uma estimativa?

Erros comuns

Pacotes de faturamento: fluxo por período

Passo 1: Crie os pacotes de faturamento

Passo 2: Acione o cálculo do faturamento

Passo 3: Receba os resultados do cálculo

Passo 4: Execute as cobranças

Passo 5: Revise e concilie

Gerenciando pacotes de faturamento

​Pacotes de tarifas: fluxo por transação

​Passo 1 - Crie seus pacotes de tarifas

​(opcional) Passo 2 - Execute uma estimativa

​Passo 3 - Crie uma transação

​Passo 4 - O Fees Engine avalia os pacotes

​Passo 5 - Verifique as isenções

​Passo 6 - Cálculo e aplicação da tarifa

​Passo 7 - Atualizações no ledger

​Passo 8 - Revise e confirme

​Precifique um TED ou Pix por um contexto de tarifa

​Crie o pacote do rótulo

​Quando o plugin recusa o rótulo

​Depois que o plugin aceita o rótulo

​Por que estimar uma transação?

​O que você obtém com uma estimativa?

​Erros comuns

​Pacotes de faturamento: fluxo por período

​Passo 1: Crie os pacotes de faturamento

​Passo 2: Acione o cálculo do faturamento

​Passo 3: Receba os resultados do cálculo

​Passo 4: Execute as cobranças

​Passo 5: Revise e concilie

​Gerenciando pacotes de faturamento

Pacotes de tarifas: fluxo por transação

Passo 1 - Crie seus pacotes de tarifas

(opcional) Passo 2 - Execute uma estimativa

Passo 3 - Crie uma transação

Passo 4 - O Fees Engine avalia os pacotes

Passo 5 - Verifique as isenções

Passo 6 - Cálculo e aplicação da tarifa

Passo 7 - Atualizações no ledger

Passo 8 - Revise e confirme

Precifique um TED ou Pix por um contexto de tarifa

Crie o pacote do rótulo

Quando o plugin recusa o rótulo

Depois que o plugin aceita o rótulo

Por que estimar uma transação?

O que você obtém com uma estimativa?

Erros comuns

Pacotes de faturamento: fluxo por período

Passo 1: Crie os pacotes de faturamento

Passo 2: Acione o cálculo do faturamento

Passo 3: Receba os resultados do cálculo

Passo 4: Execute as cobranças

Passo 5: Revise e concilie

Gerenciando pacotes de faturamento