Exemplos de pacotes de billing do Fees Engine

Esta página é orientada ao negócio — ela foca no que cada modelo de billing resolve e como configurá-lo. Para detalhes a nível de campo, consulte a visão geral dos Pacotes de Billing e a referência da API.

Billing por volume: emissão de boletos com preços escalonados

A necessidade de negócio

Uma fintech oferece emissão de boletos para seus clientes empresariais. O preço é baseado em volume: quanto mais boletos um cliente emite a cada 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%. Com 3.000 boletos ou mais, o desconto aumenta para 10%.

Estrutura de preços

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 /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Boleto Issuance — Tiered",
  "description": "Monthly volume billing for boleto issuance with progressive tiers",
  "ledgerId": "ldg_01HZ...",
  "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 final do mês, o orquestrador chama POST /v1/billing/calculate com o período de billing. O motor conta as transações de boleto aprovadas na rota, subtrai a cota gratuita, aplica os preços escalonados e aplica o desconto correspondente. O preço escalonado é preço por volume: o motor escolhe a única faixa em que a contagem faturável cai e cobra cada unidade faturável pelo preço dessa faixa. Ele não fatura separadamente a fatia de cada faixa. Exemplo de resultado — um cliente que emitiu 1.800 boletos em março:

Etapa	Detalhe	Valor
Total emitido	1.800 boletos	—
Cota gratuita	50 isentos	—
Faturáveis	1.750 boletos	—
Faixa aplicada	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 motor retorna um payload de transação que debita client-operating em R$ 1.330,00 e credita fees-boleto-revenue.

Billing de manutenção: taxa mensal de conta (PF)

A necessidade de negócio

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

Configuração do pacote

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

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

Como o cálculo funciona

O motor 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. Exemplo de resultado — 12.000 contas PF ativas:

Detalhe	Valor
Contas ativas	12.000
Taxa por conta	R$ 9,90
Entradas de transação (origem)	12.000 entradas de débito
Entradas de transação (destino)	1 entrada de crédito
Receita total	R$ 118.800,00

Billing 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 — taxa fixa, sem escalonamento. Clientes do nível premium não pagam nenhuma taxa. Em vez de listar cada conta premium, você configura a isenção no nível do segmento.

Configuração do pacote

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Pix Send — Standard",
  "description": "Flat-rate billing per Pix sent",
  "ledgerId": "ldg_01HZ...",
  "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 taxas para a rota pix-send. Adicione uma referência de segmento a waivedAccounts:

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

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

Como o cálculo funciona

Exemplo de resultado — 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 apresentam cobrança zero nos resultados de billing.

Billing de manutenção: portfólios PJ com taxas diferenciadas

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 Corporativo. Cada portfólio tem uma taxa de manutenção mensal diferente. A instituição deseja calcular ambos em uma única execução de billing.

Configuração do pacote

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

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PJ Maintenance — PME",
  "description": "Monthly maintenance for PME business accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "29.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "port_pme_01HZ..."
  }
}

Portfólio Corporativo — R$ 89,90/mês:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PJ Maintenance — Corporate",
  "description": "Monthly maintenance for Corporate business accounts",
  "ledgerId": "ldg_01HZ...",
  "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 /v1/billing/calculate com "type": "maintenance" processa ambos os pacotes. A resposta inclui um resultado por pacote e um resumo consolidado. Exemplo de resultado — 500 contas PME + 50 contas Corporativas:

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

Ambos os 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 billing

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

Calcular billing

Acione cálculos de billing para um período e recupere os payloads de transação.

Cálculos de billing

Mecânica detalhada de preços escalonados, cotas gratuitas e billing de manutenção.

Boas práticas

Orientações operacionais para pacotes de billing em produção.

Midaz Core

CRM

Fees

Exemplos de pacotes de billing do Fees Engine

Billing por volume: emissão de boletos com preços escalonados

A necessidade de negócio

Estrutura de preços

Configuração do pacote

Como o cálculo funciona

Billing de manutenção: taxa mensal de conta (PF)

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Billing 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

Billing de manutenção: portfólios PJ com taxas diferenciadas

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Próximos passos

Criar um pacote de billing

Calcular billing

Cálculos de billing

Boas práticas

​Billing por volume: emissão de boletos com preços escalonados

​A necessidade de negócio

​Estrutura de preços

​Configuração do pacote

​Como o cálculo funciona

​Billing de manutenção: taxa mensal de conta (PF)

​A necessidade de negócio

​Configuração do pacote

​Como o cálculo funciona

​Billing 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

​Billing de manutenção: portfólios PJ com taxas diferenciadas

​A necessidade de negócio

​Configuração do pacote

​Como o cálculo funciona

​Próximos passos

Criar um pacote de billing

Calcular billing

Cálculos de billing

Boas práticas

Billing por volume: emissão de boletos com preços escalonados

A necessidade de negócio

Estrutura de preços

Configuração do pacote

Como o cálculo funciona

Billing de manutenção: taxa mensal de conta (PF)

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Billing 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

Billing de manutenção: portfólios PJ com taxas diferenciadas

A necessidade de negócio

Configuração do pacote

Como o cálculo funciona

Próximos passos