Why this combination matters
Each component solves a specific layer of the problem:
Together, these three parts form a closed-loop system. Pix transactions arrive, the Fees Engine calculates fees automatically, and the ledger records every movement — gross, net, and fee amounts — in one auditable operation.
Choosing your Pix participation model
The Pix Plugin supports both participation models defined by BACEN. The fee integration and ledger flow on this page apply to both. Only the connection to BACEN differs.
For a detailed comparison, see Direct vs. Indirect Pix Plugin.
Scenario 1: Fintech launching Pix with automated fees
A fintech plans to offer Pix to its customers. It wants to charge a flat fee on every incoming Pix (cash-in). The fee covers operational costs and adds revenue without extra complexity for the customer. The fee logic and ledger structure stay the same for both models. This holds whether the fintech is an indirect participant (via BTG) or a direct participant (via JD).
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 custom fee logic or reconciliation pipelines
Setting up with Midaz
The fintech first structures its Midaz environment:1
Create the Organization
Register the fintech as an Organization in Midaz. This is the top-level entity that owns all ledgers, accounts, and transactions.
2
Set up the Ledger
Create a Ledger to track all customer transactions and fee movements. The Pix Plugin and the Fees Engine share this ledger.
3
Define the Asset
Register BRL as the operating asset. All Pix transactions and fee calculations use this asset.
4
Create customer accounts
Each customer gets an account under the ledger. These accounts receive Pix credits and follow the fee rules.
5
Create fee destination accounts
Set up internal accounts to receive fee credits — for example, a “Pix Fee Revenue” account. The Fees Engine package configuration references these accounts.
6
Organize with Segments
Use Segments to group customers by tier (e.g., Standard, Premium). This lets you apply different fee packages to different groups.
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: The Fees Engine routes fee credits to the “Pix Fee Revenue” internal account
- Exemptions: Add Premium-tier accounts to the waived accounts list
You configure fee packages once, and the Fees Engine applies them automatically. When a Pix transaction matches the package criteria (ledger, segment, amount range), the Fees Engine calculates and routes the fee without any manual step.
How a transaction flows
When a customer receives a Pix transfer, here’s what happens behind the scenes:1
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.
2
Transaction is validated
The plugin validates the recipient: it checks that the account exists, is active, and can receive funds. The plugin also checks CRM data and the Pix key validity.
3
Settlement begins
After the plugin confirms the transaction, settlement starts. The plugin fetches the destination account details from Midaz.
4
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.
5
Ledger records the full picture
Midaz records the transaction with the fee distribution in a single operation:
- Midaz credits the customer’s account with the net amount (gross minus fee).
- Midaz credits the fee destination account with R$ 1.50.
- Every movement is traceable, with double-entry precision.
6
Transaction is complete
The customer sees the Pix credit in their account. The ledger records the fee transparently for reporting and reconciliation.
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 — the Fees Engine exempts Premium customers automatically through waived accounts.
- Fee flexibility — change fee values, add percentage-based fees, or introduce amount-based thresholds without changes to 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 it distributes the rest 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:1
Create the Organization
Register the marketplace as an Organization in Midaz.
2
Set up the Ledger
Create a single Ledger to manage all payment flows — buyer payments, seller credits, and marketplace fees.
3
Define the Asset
Register BRL as the operating asset.
4
Create seller accounts
Each seller gets an account in the ledger. When a buyer pays via Pix, Midaz distributes the net amount across the relevant seller accounts.
5
Create the marketplace fee account
An internal account (e.g., “Marketplace Service Fee”) receives the fee portion of every transaction.
6
Use Segments for seller tiers
Group sellers into segments (e.g., Standard Sellers, Partner Sellers) to apply different fee rates per group.
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: The Fees Engine splits fees proportionally across source accounts when a single transaction covers multiple sellers
- Routing: Fee credits go to the “Marketplace Service Fee” account
- Deductible: The Fees Engine deducts the fee from the sellers’ amount (
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:1
Buyer sends Pix
The buyer scans a QR Code or uses a Pix key to send R$ 1,000 to the marketplace.
2
Pix arrives at the Plugin
The connectivity provider processes the transaction and notifies the Pix Plugin.
3
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)
4
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
5
Sellers and marketplace are settled
Each seller sees their net credit. The marketplace sees the fee revenue. Every number ties back to a ledger entry.
What this unlocks
- Automated revenue split — the Fees Engine handles proportional distribution across any number of accounts.
- Transparent pricing for sellers — each seller sees the exact fee and the reason for it.
- 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:
The Pix Plugin and the Fees Engine require a valid Lerian license — the Fees Engine under the Midaz Enterprise tier. For license details, see the License documentation.
Estimating before going live
Before you process real transactions, use the Fees Engine estimate to check your fee configuration. The estimate lets you:
- Preview the exact fee for a given transaction amount
- Check 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 Switch
Explore the full Pix Plugin architecture and connection models.