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

> Launch Pix with automated fees by combining Midaz, the Pix Plugin, and the Fees Engine for cash-in and cash-out with full double-entry audit trails.

Pix by itself is only the start. What turns a payment rail into a product is how you manage fees, split revenue, and keep a clear audit trail for every transaction.

You combine **Midaz** (the ledger), the **Pix Plugin** (Pix connectivity), and the **Fees Engine** (automated fee logic, part of Midaz). Together they 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 scenarios where this combination delivers 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                                          |

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.

|                             | 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                       |
| **Fees Engine integration** | Native                                                 | Native                                                 |
| **Midaz integration**       | Mandatory                                              | Mandatory                                              |

<Tip>
  **Indirect Pix via BTG** is production-ready. Your institution connects through BTG's infrastructure, so you skip ISPB certification and direct BACEN connectivity.

  **Direct Pix via JD** — explore its APIs and capabilities in the [API reference](/en/rails/pix/pix-switch).
</Tip>

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

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

<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. The Pix Plugin and the Fees Engine share this ledger.
  </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 follow the fee rules.
  </Step>

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

  <Step title="Organize with Segments">
    Use Segments to group customers by tier (e.g., Standard, Premium). This lets you 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**: The Fees Engine routes fee credits to the "Pix Fee Revenue" internal account
* **Exemptions**: Add Premium-tier accounts 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>
  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.
</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: it checks that the account exists, is active, and can receive funds. The plugin also checks CRM data and the Pix key validity.
  </Step>

  <Step title="Settlement begins">
    After the plugin confirms the transaction, settlement 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:

    * 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.
  </Step>

  <Step title="Transaction is complete">
    The customer sees the Pix credit in their account. The ledger records the fee transparently 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** — 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:

<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, Midaz distributes the net amount 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">
    Group sellers 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**: 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:

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

| Requirement               | Details                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| **Midaz** (v4.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 — a Midaz Enterprise capability, deployed independently     |
| **CRM**                   | Customer and account data for Pix validation — part of Midaz                                      |
| **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 — the Fees Engine under the Midaz Enterprise tier. For license details, see the [License documentation](/en/reference/lerians-license).
</Note>

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

This helps most during onboarding, before you set final fee structures with business stakeholders.

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

## Next steps

***

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

  <Card title="Using Fees Engine" icon="gear" href="/en/midaz/fees/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/rails/pix/pix-switch">
    Compare participation models and choose the right plugin.
  </Card>

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