Exemplos de pacotes de faturamento do Fees Engine

Esta página tem foco de negócio. Ela mostra o que cada modelo de faturamento resolve e como configurá-lo. Para detalhes de cada campo, veja a visão geral de Pacotes de Faturamento e a referência da API.

Faturamento por volume: emissão de boleto com precificação em camadas

A necessidade de negócio

Uma fintech oferece emissão de boleto para seus clientes empresariais. A precificação é baseada em volume: quanto mais boletos um cliente emite por mês, menor o custo unitário. Os primeiros 50 boletos de cada mês são gratuitos. Clientes que emitem 1.000 boletos ou mais recebem um desconto adicional de 5%. A partir de 3.000 boletos, o desconto sobe para 10%.

Estrutura de precificação

Faixa	Preço unitário
1–500	R$ 1,20
501–2.000	R$ 0,80
2.001+	R$ 0,45

Configuração do pacote

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Boleto Issuance — Tiered",
  "description": "Monthly volume billing for boleto issuance with progressive tiers",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "boleto-issuance",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 500, "unitPrice": "1.20" },
    { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.80" },
    { "minQuantity": 2001, "maxQuantity": null, "unitPrice": "0.45" }
  ],
  "freeQuota": 50,
  "discountTiers": [
    { "minQuantity": 1000, "discountPercentage": "5.00" },
    { "minQuantity": 3000, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-operating",
  "creditAccountAlias": "fees-boleto-revenue"
}

Como o cálculo funciona

No fim do mês, o orquestrador chama POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate com o período de faturamento. O engine conta as transações de boleto aprovadas na rota, subtrai a cota gratuita, aplica a precificação em camadas e aplica o desconto correspondente. A precificação em camadas é precificação por volume: o engine identifica a única camada em que a quantidade faturável se encaixa e cobra cada unidade faturável pelo preço dessa camada. Ele não cobra a fatia de cada camada separadamente. Resultado de exemplo para um cliente que emitiu 1.800 boletos em março:

Etapa	Detalhe	Valor
Total emitido	1.800 boletos	—
Cota gratuita	50 isentos	—
Faturável	1.750 boletos	—
Camada correspondente	501–2.000 → R$ 0,80	—
Bruto	1.750 × R$ 0,80	R$ 1.400,00
Desconto	5% (contagem total ≥ 1.000)	−R$ 70,00
Total líquido	—	R$ 1.330,00

O engine retorna um payload de transação que debita R$ 1.330,00 de client-operating e credita fees-boleto-revenue.

Faturamento de manutenção: tarifa mensal de conta (PF)

A necessidade de negócio

Um banco digital cobra uma tarifa fixa de manutenção mensal para contas pessoa física (PF) ativas. A tarifa é de R$ 9,90 por conta. O engine mantém apenas as contas cujo código de status é active e exclui qualquer outro status. Você não filtra essas contas manualmente. O Midaz organiza contas por segmento. O segmento seg_pf agrupa todas as contas pessoa física.

Configuração do pacote

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active personal accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}

Como o cálculo funciona

O engine resolve todas as contas no segmento PF e filtra pelo status ativo. Ele gera uma transação N:1: debita R$ 9,90 de cada conta ativa e envia o total completo para fees-maintenance-pf. Resultado de exemplo para 12.000 contas PF ativas:

Detalhe	Valor
Contas ativas	12.000
Tarifa por conta	R$ 9,90
Lançamentos da transação (origem)	12.000 lançamentos de débito
Lançamentos da transação (destino)	1 lançamento de crédito
Receita total	R$ 118.800,00

Faturamento por volume: Pix com preço fixo e isenção por segmento

A necessidade de negócio

Uma fintech cobra R$ 0,10 por Pix enviado (tarifa fixa, sem camadas). Clientes do nível premium não pagam tarifa. Em vez de listar cada conta premium, você configura a isenção no nível do segmento.

Configuração do pacote

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Pix Send — Standard",
  "description": "Flat-rate billing per Pix sent",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "fixed",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": null, "unitPrice": "0.10" }
  ],
  "freeQuota": 0,
  "discountTiers": [],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}

Isenção por segmento

Para isentar contas premium, configure o pacote de tarifas para a rota pix-send. Adicione uma referência de segmento a waivedAccounts:

{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}

Todas as contas no segmento premium ficam isentas automaticamente. Quando as contas entram ou saem do segmento no Midaz, a mudança passa a valer no próximo cálculo. Você não atualiza o pacote.

Como o cálculo funciona

Resultado de exemplo para 5.000 transações Pix de contas padrão:

Detalhe	Valor
Total de Pix enviados	5.000
Preço unitário	R$ 0,10
Total	R$ 500,00

Contas premium aparecem com cobrança zero nos resultados de faturamento.

Faturamento de manutenção: portfólios PJ com taxas diferentes

A necessidade de negócio

Uma instituição financeira gerencia múltiplos portfólios de contas empresariais (PJ): PME (pequenas e médias empresas) e Corporate. Cada portfólio tem uma tarifa de manutenção mensal diferente. A instituição quer calcular os dois em uma única execução de faturamento.

Configuração do pacote

Portfólio PME (R$ 29,90/mês):

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PJ Maintenance — PME",
  "description": "Monthly maintenance for PME business accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "29.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_pme_01HZ..."
  }
}

Portfólio Corporate (R$ 89,90/mês):

POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PJ Maintenance — Corporate",
  "description": "Monthly maintenance for Corporate business accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "89.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_corp_01HZ..."
  }
}

Como o cálculo funciona

Uma única chamada a POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate com "type": "maintenance" processa os dois pacotes. A resposta inclui um resultado por pacote e um resumo consolidado. Resultado de exemplo para 500 contas PME + 50 contas Corporate:

Portfólio	Contas ativas	Tarifa	Total
PME	500	R$ 29,90	R$ 14.950,00
Corporate	50	R$ 89,90	R$ 4.495,00
Consolidado	550	—	R$ 19.445,00

Os dois resultados creditam a mesma conta fees-maintenance-pj, mantendo a receita consolidada. O orquestrador envia cada payload de transação ao Midaz de forma independente.

Próximos passos

Criar um pacote de faturamento

Referência da API para criar pacotes de faturamento de volume e manutenção.

Calcular faturamento

Dispare cálculos de faturamento para um período e recupere payloads de transação.

Cálculos de faturamento

Mecânica detalhada da precificação em camadas, cotas gratuitas e faturamento de manutenção.

Boas práticas

Orientação operacional para pacotes de faturamento em produção.

Midaz Core

CRM

Fees

Exemplos de pacotes de faturamento do Fees Engine

Faturamento por volume: emissão de boleto com precificação em camadas

A necessidade de negócio

Estrutura de precificação

Configuração do pacote

Como o cálculo funciona

Faturamento de manutenção: tarifa mensal de conta (PF)

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Faturamento por volume: Pix com preço fixo e isenção por segmento

A necessidade de negócio

Configuração do pacote

Isenção por segmento

Como o cálculo funciona

Faturamento de manutenção: portfólios PJ com taxas diferentes

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Próximos passos

Criar um pacote de faturamento

Calcular faturamento

Cálculos de faturamento

Boas práticas

​Faturamento por volume: emissão de boleto com precificação em camadas

​A necessidade de negócio

​Estrutura de precificação

​Configuração do pacote

​Como o cálculo funciona

​Faturamento de manutenção: tarifa mensal de conta (PF)

​A necessidade de negócio

​Configuração do pacote

​Como o cálculo funciona

​Faturamento por volume: Pix com preço fixo e isenção por segmento

​A necessidade de negócio

​Configuração do pacote

​Isenção por segmento

​Como o cálculo funciona

​Faturamento de manutenção: portfólios PJ com taxas diferentes

​A necessidade de negócio

​Configuração do pacote

​Como o cálculo funciona

​Próximos passos

Criar um pacote de faturamento

Calcular faturamento

Cálculos de faturamento

Boas práticas

Faturamento por volume: emissão de boleto com precificação em camadas

A necessidade de negócio

Estrutura de precificação

Configuração do pacote

Como o cálculo funciona

Faturamento de manutenção: tarifa mensal de conta (PF)

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Faturamento por volume: Pix com preço fixo e isenção por segmento

A necessidade de negócio

Configuração do pacote

Isenção por segmento

Como o cálculo funciona

Faturamento de manutenção: portfólios PJ com taxas diferentes

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Próximos passos