Pular para o conteúdo principal
Seja aplicando taxas por transação ou calculando cobranças periódicas de billing, o Fees Engine oferece controle total e flexibilidade. Este guia acompanha você por ambos os fluxos de trabalho: pacotes de taxas (por transação) e pacotes de billing (por período).
Não sabe qual usar? Pacotes de taxas aplicam cobranças no momento da transação. Pacotes de billing calculam cobranças ao longo de um período (diário ou mensal) para seu orquestrador executar. Você pode usar ambos simultaneamente.

​
Pacotes de taxas: fluxo de trabalho por transação

Veja como o processo funciona, desde a configuração das taxas até a visualização dos resultados.

​
Passo 1 - Crie seus pacotes de taxas

Comece configurando pacotes de taxas que definem como as taxas são aplicadas. Para isso, use o endpoint Criar um Pacote. Cada pacote contém um conjunto de regras de taxas e critérios de correspondência. Você pode personalizar pacotes para diferentes segmentos ou ledgers usando:
  • transactionRoute – Identifica a natureza da transação.
  • segmentId – Agrupa clientes ou tipos de produto.
  • ledgerId – Define qual ledger registra a transação.
  • Valor mínimo e máximo – Limites opcionais para aplicação de taxas.
  • routeFrom / routeTo – Definem como cada taxa se move nos fluxos contábeis.
Essa flexibilidade permite aplicar taxas distintas por cenário, desde configurações baseadas em conta até baseadas em valor. Gerenciando Pacotes Os seguintes endpoints também estão disponíveis para você gerenciar os pacotes:

​
(opcional) Passo 2 - Execute uma estimativa

Se você deseja visualizar como um pacote de taxas se comportaria antes de confirmar uma transação real, use o endpoint Estimar Taxas de Transação. Essa estimativa ajuda a validar:
  • Quais regras de taxas serão acionadas.
  • Como o pacote se comportará com os valores informados.
  • Se alguma isenção se aplica.

​
Passo 3 - Crie uma transação

Uma vez que os pacotes estejam configurados, acione a transação real usando o endpoint criar uma transação. Inclua o transactionRoute, segmentId e ledgerId apropriados para que o motor possa avaliar o pacote correspondente.

​
Passo 4 - O Fees Engine entra em ação

O Fees Engine automaticamente envia uma chamada para o endpoint Calcular Taxas para um Pacote e avalia se um pacote se aplica com base em:
  • transactionRoute
  • segmentId
  • ledgerId
  • Valor mínimo e máximo
  • waivedAccounts (para isenções de taxas)
Apenas um pacote é selecionado por transação.

​
Passo 5 - Verificar isenções

O sistema verifica:
  • Se o valor da transação está fora da faixa permitida.
  • Se a conta de origem é isenta.
Se qualquer uma das condições for atendida, nenhuma taxa é aplicada e a transação prossegue normalmente.

​
Passo 6 - Cálculo e aplicação de taxas

Se um pacote for aplicado, o Fees Engine:
  • Calcula os valores das taxas com base na applicationRule selecionada.
  • Aplica taxas proporcionalmente entre contas, se necessário.
  • Usa isDeductibleFrom para definir se a taxa é adicionada ou deduzida.
  • Roteia as taxas para a creditAccount correta usando os routeFrom e routeTo configurados.
  • Retorna o resultado completo da transação junto com o packageAppliedID nos metadados.

​
Passo 7 - Atualizações no ledger

Após o cálculo das taxas, o componente de Transações assume. Ele processa:
  • Débitos das contas de origem
  • Créditos para os destinos das taxas
  • Detalhamento das taxas por rota e conta
Cada movimentação é armazenada no ledger para rastreabilidade e auditabilidade completas.

​
Passo 8 - Revisar e confirmar

Após a execução, você pode:
  • Inspecionar a transação final e os valores por conta.
  • Confirmar o pacote de taxas que foi aplicado.
  • Verificar todas as movimentações de taxas via metadados e registros do ledger.

​
Por que estimar uma transação?

Estimativas permitem visualizar como um pacote de taxas específico se comporta, sem executar uma transação real ou gravar no ledger. Use estimativas quando:
  • Você quiser testar um pacote específico.
  • Estiver depurando regras de taxas ou limites.
  • Quiser validar isenções, faixas de valor ou divisões proporcionais.
  • Precisar de uma prévia antes de criar uma transação real.
  • Estiver construindo uma interface e quiser mostrar taxas estimadas.
O Fees Engine fornece o endpoint Estimar Taxas de Transação para esse propósito. Você só precisa passar um packageId e o endpoint retorna o que aconteceria se aquele pacote exato fosse aplicado.

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

  • Uma estimativa completa das regras de taxas.
  • Quais contas seriam cobradas.
  • Como a taxa seria dividida.
  • Sem impacto no ledger.
Use estimativas quando você não estiver pronto para confirmar a transação, ou quiser dar aos seus usuários uma prévia clara das taxas.

​
Erros comuns

O Fees Engine valida cada requisição para garantir consistência e lógica correta de taxas. Abaixo estão os problemas mais frequentes que você pode encontrar ao criar pacotes ou processar transações.
CódigoTítuloMensagem
FEE-0002Missing fields in requestYour request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
FEE-0012Entity not foundNo entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.
FEE-0013Invalid fee priorityThe priority field in fees is invalid. Field can not be repeated.
FEE-0015minimumAmount greater than maximumAmountminimumAmount value is greater than maximumAmount.
FEE-0022Failed to calculate feeError to make the calculation of a fee about a transaction.
FEE-0024originalAmount is required when priority is oneFor Priority equals to one, referenceAmount must be ‘originalAmount’ for fee.
FEE-0025Failed to apply rule: flatFee or percentualapplicationRule flatFee or percentual must have exactly 1 calculation for Fee.
FEE-0035Package amount range overlapThe maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.
Quer a lista completa de códigos de erro? Você encontra na página Lista de erros do Fees Engine na Referência da API.

​
Pacotes de billing: fluxo de trabalho por período

Os pacotes de billing calculam cobranças com base no volume acumulado de transações ou na manutenção por conta ao longo de um período de billing. Diferentemente dos pacotes de taxas, o billing é acionado pelo chamador — seu orquestrador decide quando calcular e executa as cobranças resultantes.

​
Passo 1 — Crie pacotes de billing

Configure pacotes de billing que definem suas regras de cobrança periódica. Cada pacote é do tipo volume ou manutenção. Exemplo de pacote de volume — cobrança por Pix enviado com preços escalonados: 
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Pix Send Monthly Billing",
  "description": "Monthly volume billing for Pix transactions",
  "ledgerId": "ldg_01HZ...",
  "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": "perAccount",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-revenue"
}
Exemplo de pacote de manutenção — taxa mensal por conta PF ativa: 
POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active PF accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}

​
Passo 2 — Acione o cálculo de billing

Chame POST /v1/billing/calculate com o ID do ledger e o período de billing. O motor avalia todos os pacotes de billing ativos que correspondem aos critérios. 
POST /v1/billing/calculate

Body:
{
  "ledgerId": "ldg_01HZ...",
  "period": "2026-03",
  "type": "volume"
}
O campo period suporta três formatos: YYYY-MM (mensal), YYYY-Www (semanal, ex.: 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 ambos os tipos em uma única chamada.

​
Passo 3 — Receba os resultados do cálculo

O motor retorna um array de resultados, cada um contendo um transactionPayload pronto para ser enviado ao Midaz. Cada resultado inclui:
  • O pacote de billing que o gerou.
  • Os valores calculados com detalhamento completo (faixas aplicadas, descontos, cota gratuita subtraída).
  • Um payload de transação com source.from (entradas de débito) e distribute.to (entradas de crédito).
  • Metadados de auditoria estruturados para rastreabilidade.

​
Passo 4 — Execute as cobranças

Envie cada transactionPayload ao Midaz via POST /transactions/json para criar as transações de billing reais. Essa etapa é responsabilidade do seu orquestrador — Flowker, um cron job ou qualquer outro sistema.
O motor de billing calcula e retorna os resultados. Ele não cria transações no Midaz. Seu orquestrador controla quando e como as cobranças são executadas.

​
Passo 5 — Revise e concilie

Após executar as cobranças:
  • Verifique se as transações criadas no Midaz correspondem aos resultados do cálculo de billing.
  • Use os metadados de auditoria de cada resultado para conciliação.
  • O cálculo de billing é stateless — você pode re-executá-lo para o mesmo período para verificar os resultados.

​
Gerenciando pacotes de billing

Use estes endpoints para gerenciar pacotes de billing existentes:
  • GET /v1/billing-packages — Listar todos os pacotes de billing.
  • GET /v1/billing-packages/:id — Recuperar um pacote de billing específico.
  • PATCH /v1/billing-packages/:id — Atualizar um pacote de billing (apenas label, description, enable).
  • DELETE /v1/billing-packages/:id — Soft-delete de um pacote de billing.
O cálculo de billing segue uma política tudo-ou-nada. Se qualquer pacote falhar durante o cálculo, toda a operação falha e nenhum resultado parcial é retornado. Corrija o pacote com falha e re-execute.