Why this combination matters
Each component solves a specific layer of the problem:
| Component | Role |
|---|---|
| Midaz | Core ledger — records every debit, credit, and fee movement with double-entry precision |
| Pix Plugin | Pix connectivity — handles transaction orchestration, DICT, QR Codes, and settlement through your chosen participation model |
| Fees Engine | Fee automation — calculates, splits, and routes fees based on configurable packages |
Choosing your Pix participation model
The Pix Plugin supports both participation models defined by BACEN. The fee integration and ledger flow described on this page apply equally to both — the difference lies in how your institution connects to BACEN’s infrastructure.
| Indirect Pix | Direct Pix | |
|---|---|---|
| How it connects | Through a Direct Participant (e.g., BTG) | Directly to SPI/DICT via a certified PSTI (e.g., JD) |
| Best for | Fintechs, payment institutions seeking fast onboarding | Banks and regulated FIs with full operational autonomy |
| Regulatory burden | Shared with the Direct Participant | Fully owned by the institution |
| Time to market | Weeks | Longer, but with maximum control |
| Fee Engine integration | Native | Native |
| Midaz integration | Mandatory | Mandatory |
Scenario 1: Fintech launching Pix with automated fees
A fintech is preparing to offer Pix to its customers. It needs to charge a flat fee on every incoming Pix (cash-in) to cover operational costs and generate revenue — without adding complexity to the customer experience. Whether the fintech operates as an indirect participant (via BTG) or as a direct participant (via JD), the fee logic and ledger structure remain the same.
The business goal
- Offer instant Pix payments to end customers
- Charge a transparent, configurable fee on incoming transfers
- Record every fee in the ledger for compliance and financial reporting
- Launch quickly, without building custom fee logic or reconciliation pipelines
Setting up with Midaz
The fintech starts by structuring its Midaz environment:Create the Organization
Register the fintech as an Organization in Midaz. This is the top-level entity that owns all ledgers, accounts, and transactions.
Set up the Ledger
Create a Ledger to track all customer transactions and fee movements. This ledger is shared by the Pix Plugin and the Fees Engine.
Define the Asset
Register BRL as the operating asset. All Pix transactions and fee calculations use this asset.
Create customer accounts
Each customer gets an account under the ledger. These accounts receive Pix credits and are subject to fee rules.
Create fee destination accounts
Set up internal accounts to receive fee credits — for example, a “Pix Fee Revenue” account. These are referenced in the Fees Engine package configuration.
Configuring the Fees Engine
With the ledger structure in place, the fintech configures a fee package:- Fee type: Flat fee of R$ 1.50 per incoming Pix
- Scope: Applied to all cash-in transactions on the main ledger
- Routing: Fee credits are routed to the “Pix Fee Revenue” internal account
- Exemptions: Premium-tier accounts are added to the waived accounts list
Fee packages are configured once and applied automatically. When a Pix transaction matches the package criteria (ledger, segment, amount range), the Fees Engine calculates and routes the fee without any manual intervention.
How a transaction flows
When a customer receives a Pix transfer, here’s what happens behind the scenes:Pix arrives
The sending institution initiates a Pix. Your connectivity provider (BTG for indirect, JD for direct) receives the transaction and notifies the Pix Plugin.
Transaction is validated
The plugin validates the recipient: checks the account exists, is active, and can receive funds. CRM data and Pix key validity are also verified.
Settlement begins
Once the transaction is confirmed, the settlement process starts. The plugin fetches the destination account details from Midaz.
Fees are calculated automatically
The Fees Engine evaluates the transaction against available fee packages. It finds a matching package and calculates the R$ 1.50 flat fee.
Ledger records the full picture
Midaz records the transaction with the fee distribution in a single operation:
- The customer’s account is credited with the net amount (gross minus fee).
- The fee destination account is credited with R$ 1.50.
- Every movement is traceable, with double-entry precision.
What this unlocks
- No custom fee logic — the Fees Engine handles calculation, routing, and exemptions.
- Accurate ledger — every fee is a ledger entry, not just metadata. Auditors see the same numbers your finance team sees.
- Customer segmentation — Premium customers can be exempted automatically using waived accounts.
- Fee flexibility — change fee values, add percentage-based fees, or introduce amount-based thresholds without changing your transaction pipeline.
Scenario 2: Marketplace with Pix and proportional fees
A B2B marketplace connects buyers and sellers. Buyers pay via Pix, and the marketplace charges a service fee on each transaction before distributing the remaining amount to sellers.
The business goal
- Accept Pix payments from buyers
- Charge a percentage-based service fee on each payment
- Distribute the net amount proportionally across multiple sellers when a single payment covers goods from different sellers
- Maintain a clear audit trail for every split and fee
Setting up with Midaz
The marketplace structures its Midaz environment to reflect the multi-party nature of its operations:Set up the Ledger
Create a single Ledger to manage all payment flows — buyer payments, seller credits, and marketplace fees.
Create seller accounts
Each seller gets an account in the ledger. When a buyer pays via Pix, the net amount is distributed across the relevant seller accounts.
Create the marketplace fee account
An internal account (e.g., “Marketplace Service Fee”) receives the fee portion of every transaction.
Configuring the Fees Engine
The marketplace configures a fee package with proportional distribution:- Fee type: 3% of the transaction value
- Scope: Applied to all incoming Pix payments on the marketplace ledger
- Distribution: Fees are split proportionally across source accounts when multiple sellers participate in a single transaction
- Routing: Fee credits go to the “Marketplace Service Fee” account
- Deductible: The fee is deducted from the amount received by sellers (
isDeductibleFrom: true), so the buyer always sends the full amount
How a transaction flows
A buyer purchases R$ 1,000 worth of goods from three sellers:| Seller | Share | Gross amount |
|---|---|---|
| Seller A | 50% | R$ 500.00 |
| Seller B | 30% | R$ 300.00 |
| Seller C | 20% | R$ 200.00 |
Pix arrives at the Plugin
The connectivity provider processes the transaction and notifies the Pix Plugin.
Fees are calculated with proportional split
The Fees Engine calculates a 3% fee (R$ 30.00) and distributes it proportionally:
- Seller A: R 485.00 net)
- Seller B: R 291.00 net)
- Seller C: R 194.00 net)
Ledger records every movement
Midaz creates the transaction with full distribution:
- Seller A’s account: credited R$ 485.00
- Seller B’s account: credited R$ 291.00
- Seller C’s account: credited R$ 194.00
- Marketplace fee account: credited R$ 30.00
- Total: R$ 1,000.00 — fully balanced
What this unlocks
- Automated revenue split — the Fees Engine handles proportional distribution across any number of accounts.
- Transparent pricing for sellers — each seller knows exactly what fee was charged and why.
- Balanced ledger — gross amount in equals the sum of all credits out. No rounding gaps, no manual adjustments.
- Configurable rates — change the fee percentage, add flat minimums, or exempt specific partners — all through fee package configuration.
What you need to get started
To run this setup, your institution needs:
| Requirement | Details |
|---|---|
| Midaz (v3.x.x+) | Core ledger for account management and transaction recording |
| Pix Plugin | Pix connectivity — choose Indirect (via BTG) or Direct (via JD) based on your participation model |
| Fees Engine | Automated fee calculation and routing |
| CRM Plugin | Customer and account metadata used during Pix validation |
| Infrastructure | Self-managed cloud (BYOC) or on-premise environment |
| Connectivity contract | Agreement with BTG (indirect) or JD/PSTI (direct) depending on your model |
The Pix Plugin and the Fees Engine require a valid Lerian license. For license details, see the License documentation.
Simulating before going live
Before processing real transactions, use the Fees Engine’s simulation capability to validate your fee configuration. Simulations let you:
- Preview exactly how fees will be calculated for a given transaction amount
- Verify that exemptions work as expected
- Confirm proportional splits produce the correct distribution
- Test edge cases like boundary amounts and waived accounts
Next steps
Fees Engine overview
Understand fee packages, calculation rules, and routing options.
Using Fees Engine
Step-by-step guide to creating packages and processing fees.
Direct vs. Indirect Pix
Compare participation models and choose the right plugin.
Pix Plugin overview
Explore the full Pix Plugin architecture and connection models.