Pular para o conteúdo principal
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 por mês, menor o custo unitário. Os primeiros 50 boletos de cada mês são gratuitos. Clientes que emitem mais de 1.000 boletos recebem um desconto adicional de 5%; acima de 3.000, o desconto aumenta para 10%.

​
Estrutura de preços

FaixaPreço unitário
1–500R$ 1,20
501–2.000R$ 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": "perAccount",
  "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 por conta, subtrai a cota gratuita, aplica os preços escalonados e aplica o desconto correspondente. Exemplo de resultado — um cliente que emitiu 1.800 boletos em março:
EtapaDetalheValor
Total emitido1.800 boletos—
Cota gratuita50 isentos—
Faturáveis1.750 boletos—
Faixa 1500 × R$ 1,20R$ 600,00
Faixa 21.250 × R$ 0,80R$ 1.000,00
Subtotal—R$ 1.600,00
Desconto5% (> 1.000 boletos)−R$ 80,00
Total—R$ 1.520,00
O motor retorna um payload de transação que debita client-operating em R$ 1.520,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. Contas inativas, encerradas ou suspensas são excluídas automaticamente — nenhuma filtragem manual é necessária. As contas são organizadas por segmento no Midaz. 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, filtra pelo status ativo e gera uma única transação N:1: cada conta ativa é debitada em R$ 9,90, e o total completo vai para fees-maintenance-pf. Exemplo de resultado — 12.000 contas PF ativas:
DetalheValor
Contas ativas12.000
Taxa por contaR$ 9,90
Entradas de transação (origem)12.000 entradas de débito
Entradas de transação (destino)1 entrada de crédito
Receita totalR$ 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 são totalmente isentos dessa taxa. Em vez de listar cada conta premium individualmente, a isenção é configurada 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": "perAccount",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}

​
Isenção por segmento

Para isentar contas premium, configure o pacote de taxas (Motor 1) para a rota pix-send com uma referência de segmento em waivedAccounts: 
{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}
Todas as contas pertencentes ao segmento premium são isentas automaticamente. Quando novas contas entram ou saem do segmento no Midaz, a mudança entra em vigor no próximo cálculo — sem necessidade de atualizar o pacote.

​
Como o cálculo funciona

Exemplo de resultado — 5.000 transações Pix de contas padrão:
DetalheValor
Total de Pix enviados5.000
Preço unitárioR$ 0,10
TotalR$ 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ólioContas ativasTaxaTotal
PME500R$ 29,90R$ 14.950,00
Corporativo50R$ 89,90R$ 4.495,00
Consolidado550—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.