> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Midaz with Pix and automated fees

> Combine Midaz, the Pix Plugin, and Fees Engine to launch Pix with automated fee management and full audit traceability.

Offering Pix is just the beginning. What turns a payment rail into a financial product is how you manage fees, distribute revenue, and maintain a clear audit trail for every transaction.

By combining **Midaz** (the ledger), the **Pix Plugin** (Pix connectivity), and the **Fees Engine** (automated fee logic), institutions can launch Pix operations with built-in fee management — no custom middleware, no manual reconciliation, and no gaps in your accounting.

This page walks through two real-world scenarios where this combination delivers immediate value.

## 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                                          |

When connected, these three components create a **closed-loop system**: Pix transactions arrive, fees are calculated automatically, and the ledger records every movement — principal, net, and fee amounts — in a single, auditable operation.

## 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                                              |

<Tip>
  **Indirect Pix via BTG** is production-ready and the fastest path to offering Pix with enterprise-grade compliance. Your institution connects through BTG's infrastructure, eliminating the need for ISPB certification or direct BACEN connectivity.

  **Direct Pix via JD** is currently under active development. You can already explore its APIs and capabilities in the [API reference](/en/midaz/plugins/pix/pix-switch).
</Tip>

For a detailed comparison, see [Direct vs. Indirect Pix Plugin](/en/midaz/plugins/pix/pix-switch).

## 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:

<Steps>
  <Step title="Create the Organization">
    Register the fintech as an Organization in Midaz. This is the top-level entity that owns all ledgers, accounts, and transactions.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Define the Asset">
    Register **BRL** as the operating asset. All Pix transactions and fee calculations use this asset.
  </Step>

  <Step title="Create customer accounts">
    Each customer gets an account under the ledger. These accounts receive Pix credits and are subject to fee rules.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Organize with Segments">
    Use Segments to group customers by tier (e.g., Standard, Premium). This allows you to apply different fee packages to different groups.
  </Step>
</Steps>

### 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

The Fees Engine supports multiple calculation methods — flat fees, percentage-based fees, or a "max between" rule that applies whichever is greater. For this scenario, a flat fee keeps pricing predictable for customers.

<Note>
  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.
</Note>

### How a transaction flows

When a customer receives a Pix transfer, here's what happens behind the scenes:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Settlement begins">
    Once the transaction is confirmed, the settlement process starts. The plugin fetches the destination account details from Midaz.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Transaction is complete">
    The customer sees the Pix credit in their account. The fee is recorded transparently, available for reporting and reconciliation.
  </Step>
</Steps>

### 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:

<Steps>
  <Step title="Create the Organization">
    Register the marketplace as an Organization in Midaz.
  </Step>

  <Step title="Set up the Ledger">
    Create a single Ledger to manage all payment flows — buyer payments, seller credits, and marketplace fees.
  </Step>

  <Step title="Define the Asset">
    Register **BRL** as the operating asset.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Create the marketplace fee account">
    An internal account (e.g., "Marketplace Service Fee") receives the fee portion of every transaction.
  </Step>

  <Step title="Use Segments for seller tiers">
    Sellers can be grouped into segments (e.g., Standard Sellers, Partner Sellers) to apply different fee rates per group.
  </Step>
</Steps>

### 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   |

<Steps>
  <Step title="Buyer sends Pix">
    The buyer scans a QR Code or uses a Pix key to send R\$ 1,000 to the marketplace.
  </Step>

  <Step title="Pix arrives at the Plugin">
    The connectivity provider processes the transaction and notifies the Pix Plugin.
  </Step>

  <Step title="Fees are calculated with proportional split">
    The Fees Engine calculates a 3% fee (R\$ 30.00) and distributes it proportionally:

    * Seller A: R$ 15.00 fee (R$ 485.00 net)
    * Seller B: R$ 9.00 fee (R$ 291.00 net)
    * Seller C: R$ 6.00 fee (R$ 194.00 net)
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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**                   | 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                         |

<Note>
  The Pix Plugin and the Fees Engine require a valid Lerian license. For license details, see the [License documentation](/en/reference/lerians-license).
</Note>

## Estimating before going live

***

Before processing real transactions, use the Fees Engine's estimation capability to validate your fee configuration.

Estimations 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

This is especially useful during onboarding, when you're finalizing fee structures with business stakeholders before launch.

<Tip>
  Use the [Estimate Transaction Fees](/en/reference/midaz/plugins/fees-engine/simulate-fees) endpoint to test specific fee packages without writing anything to the ledger.
</Tip>

## Next steps

***

<CardGroup>
  <Card title="Fees Engine overview" icon="calculator" href="/en/midaz/plugins/fees-engine/fees-engine-overview">
    Understand fee packages, calculation rules, and routing options.
  </Card>

  <Card title="Using Fees Engine" icon="gear" href="/en/midaz/plugins/fees-engine/using-fee-engine">
    Step-by-step guide to creating packages and processing fees.
  </Card>

  <Card title="Direct vs. Indirect Pix" icon="code-compare" href="/en/midaz/plugins/pix/pix-switch">
    Compare participation models and choose the right plugin.
  </Card>

  <Card title="Pix Switch" icon="money-bill-transfer" href="/en/midaz/plugins/pix/pix-switch">
    Explore the full Pix Plugin architecture and connection models.
  </Card>
</CardGroup>