Skip to main content
This page is business-oriented — it focuses on what each billing model solves and how to configure it. For field-level details, see the Billing Packages overview and the API reference.

​
Volume billing: boleto issuance with tiered pricing

​
The business need

A fintech offers boleto issuance to its business clients. Pricing is volume-based: the more boletos a client issues per month, the lower the unit cost. The first 50 boletos each month are complimentary. Clients issuing over 1,000 boletos receive an additional 5% discount; above 3,000, the discount increases to 10%.

​
Pricing structure

RangeUnit price
1–500R$ 1.20
501–2,000R$ 0.80
2,001+R$ 0.45

​
Package configuration

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"
}

​
How the calculation works

At month-end, the orchestrator calls POST /v1/billing/calculate with the billing period. The engine counts approved boleto transactions per account, subtracts the free quota, applies tiered pricing, and applies the matching discount. Example result — a client that issued 1,800 boletos in March:
StepDetailAmount
Total issued1,800 boletos—
Free quota50 exempt—
Billable1,750 boletos—
Tier 1500 × R$ 1.20R$ 600.00
Tier 21,250 × R$ 0.80R$ 1,000.00
Subtotal—R$ 1,600.00
Discount5% (> 1,000 boletos)−R$ 80.00
Total—R$ 1,520.00
The engine returns a transaction payload that debits client-operating by R$ 1,520.00 and credits fees-boleto-revenue.

​
Maintenance billing: monthly account fee (PF)

​
The business need

A digital bank charges a fixed monthly maintenance fee for active personal (PF) accounts. The fee is R$ 9.90 per account. Inactive, closed, or suspended accounts are excluded automatically — no manual filtering required. Accounts are organized by segment in Midaz. The segment seg_pf groups all personal accounts.

​
Package configuration

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..."
  }
}

​
How the calculation works

The engine resolves all accounts in the PF segment, filters for active status, and generates a single N:1 transaction: each active account is debited R$ 9.90, and the full total goes to fees-maintenance-pf. Example result — 12,000 active PF accounts:
DetailValue
Active accounts12,000
Fee per accountR$ 9.90
Transaction entries (source)12,000 debit entries
Transaction entries (destination)1 credit entry
Total revenueR$ 118,800.00

​
Volume billing: fixed-price Pix with segment exemption

​
The business need

A fintech charges R$ 0.10 per Pix sent — flat rate, no tiers. Premium-tier customers are fully exempt from this fee. Instead of listing each premium account individually, the exemption is configured at the segment level.

​
Package configuration

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"
}

​
Segment exemption

To exempt premium accounts, configure the fee package (Motor 1) for the pix-send route with a segment reference in waivedAccounts: 
{
  "waivedAccounts": [
    "segment:seg_premium_01HZ..."
  ]
}
All accounts belonging to the premium segment are exempt automatically. When new accounts join or leave the segment in Midaz, the change takes effect on the next calculation — no package update needed.

​
How the calculation works

Example result — 5,000 Pix transactions from standard accounts:
DetailValue
Total Pix sent5,000
Unit priceR$ 0.10
TotalR$ 500.00
Premium accounts show zero charges in the billing results.

​
Maintenance billing: PJ portfolios with different rates

​
The business need

A financial institution manages multiple business (PJ) account portfolios: PME (small and medium enterprises) and Corporate. Each portfolio has a different monthly maintenance fee. The institution wants to calculate both in a single billing run.

​
Package configuration

PME portfolio — R$ 29.90/month: 
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..."
  }
}
Corporate portfolio — R$ 89.90/month: 
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..."
  }
}

​
How the calculation works

A single call to POST /v1/billing/calculate with "type": "maintenance" processes both packages. The response includes one result per package and a consolidated summary. Example result — 500 PME accounts + 50 Corporate accounts:
PortfolioActive accountsFeeTotal
PME500R$ 29.90R$ 14,950.00
Corporate50R$ 89.90R$ 4,495.00
Consolidated550—R$ 19,445.00
Both results credit the same fees-maintenance-pj account, keeping revenue consolidated. The orchestrator sends each transaction payload to Midaz independently.

​
Next steps

Create a billing package

API reference for creating volume and maintenance billing packages.

Calculate billing

Trigger billing calculations for a period and retrieve transaction payloads.

Billing calculations

Detailed mechanics of tiered pricing, free quotas, and maintenance billing.

Best practices

Operational guidance for billing packages in production.