Why Pix Switch
Historically, supporting Pix across different connectivity providers meant maintaining separate, isolated plugins — one per provider, each with its own codebase, API contracts, and integration patterns. This created real problems:
- Duplicated business logic — The same Pix rules had to be implemented and maintained independently in each plugin
- Different API contracts — Each provider integration exposed a different API to the client, making it harder to switch or add providers
- Higher maintenance cost — Bug fixes, regulatory updates, and new features had to be applied separately to each plugin
- No portability — Moving from one provider to another required a full re-integration
What Pix Switch provides
Pix Switch delivers a complete Pix orchestration layer that handles the full business lifecycle of Pix operations:
- Cash-out and cash-in flows — Send and receive Pix payments with full message lifecycle management
- Pix key management (DICT) — Create, update, delete, and resolve ownership of Pix keys
- Static and dynamic QR Code generation — Issue QR Codes for payment initiation across all supported formats
- MED lifecycle orchestration — Manage the Special Refund Mechanism (Mecanismo Especial de Devolucao) end to end
- Refund handling — Process full and partial refunds with proper regulatory sequencing
- Webhooks, event processing, and background workers — React to provider events in real time and run async jobs reliably
- Native Midaz integration — Midaz is the mandatory ledger for Pix Switch, providing account validation, balance checks, debit/credit posting, and routing
How it works
Pix Switch uses a Provider Adapter Layer to separate your integration from the specifics of any single connectivity provider. The plugin exposes a single API to your application. Behind that API, a provider adapter translates every operation — transactions, key lookups, QR Code registrations, refunds — into the protocol and format required by your configured provider. Your institution selects which provider to use during setup. The plugin resolves everything else. This architecture means that switching providers or supporting additional participation models does not require rewriting your integration. You change the configuration. The API stays the same.
Regulated connectivity is always external. Pix Switch does not connect to BACEN directly. A direct participant or a certified PSTI provides the SPI/DICT gateway layer. Pix Switch operates above that layer, handling all Pix business logic.
Participation models
BACEN defines two regulatory models for Pix participation: direct (your institution connects to BACEN on its own) and indirect (you connect through a licensed direct participant). For a detailed explanation of each model, see What is Pix?. In Pix Switch, the participation model is a configuration — not a different product. Both models are supported through the Provider Adapter Layer. You choose a provider that matches your regulatory status, and the plugin API stays the same. Switching providers or upgrading your participation model does not require re-integrating the plugin.
Integrations in the Lerian ecosystem
Pix Switch requires Midaz as its core ledger. This native integration simplifies:
- Account validation
- Balance checks
- Debit/credit posting
- Routing
- Business rules (fees, authorizations, antifraud triggers)
- CRM (Midaz CRM) — Customer relationship and entity management
- Fee Engine — Automated fee calculation and collection
- Access Manager — Authentication, authorization, and credential governance
- Reporter — Regulatory and COSIF-ready reporting
- Matcher — Reconciliation and identity matching
- Flowker — Workflow orchestration
- Tracer — Observability and distributed tracing
Deployment model
Pix Switch follows the same deployment models available across the Lerian platform: SaaS and BYOC (Bring Your Own Cloud). Both give you access to the full product — the difference is who operates the infrastructure.
- SaaS — Lerian hosts and operates Pix Switch in a fully managed environment. Your team focuses on product configuration and integration. Lerian handles infrastructure, updates, and availability.
- BYOC — Your institution deploys and operates Pix Switch in its own infrastructure — whether on a public cloud, private cloud, or on-premises.
Target audience
Pix Switch is designed for institutions that:
- Participate in the Pix arrangement (or intend to)
- Own a valid ISPB (identifier assigned by BACEN to financial institutions in Brazil)
- Own the ledger at the business level — your institution controls accounts and balances, regardless of where the infrastructure runs
Requirements to operate
Before adopting Pix Switch, your institution must have:
- A valid ISPB registered with BACEN
- A contract with a connectivity provider — a direct participant (for indirect participation) or a certified PSTI (for direct participation), depending on your regulatory model
- Logical ownership of the ledger — Midaz must be deployed and operational, with your institution controlling accounts and balances
- Your own cloud or on-premise environment to host the plugin
- DevOps and SRE readiness — your team manages deployment, monitoring, updates, and incident response
- Security and compliance ownership — your institution is responsible for access control, redundancy, observability, and audit trails
Advantages
Ecosystem-native integrations
Connect to Midaz, Fee Engine, CRM, Matcher, Flowker, Reporter, Tracer, and Access Manager out of the box. Each integration is built into the platform, not bolted on.Customization
Extend or modify business logic to match your institution’s specific requirements. Adapt to regulatory changes at your own pace.Economic efficiency
Remove reliance on multi-layer intermediaries that add cost without adding control. In SaaS, go to production without upfront infrastructure investment. In BYOC, size infrastructure for your actual demand.Fastest path to production (SaaS)
Go live without provisioning or managing infrastructure. Lerian handles operations, updates, and availability — your team focuses on building financial products.Full control and data sovereignty (BYOC)
Run everything in your own infrastructure. Apply your own IAM policies, encryption standards, and governance frameworks. Define routing rules, business policies, and operational practices. Your data never leaves your environment.Trade-offs
Each deployment model comes with different trade-offs.
SaaS
- Less infrastructure control — Lerian manages the environment. You configure the product, not the platform underneath.
- Data hosted by Lerian — Your data lives in Lerian-managed cloud infrastructure. If your regulatory requirements mandate data residency in your own environment, choose BYOC.
BYOC
- Requires technical maturity — Your institution needs DevOps capabilities, observability tooling, and operational management expertise.
- Requires governance discipline — Security, uptime, compliance, and audit readiness must be maintained by your team.
- More configuration upfront — Flexibility means more orchestration and parameterization during initial setup. Plan for a structured onboarding process.
- Operational responsibility — Your institution manages software updates, patches, scaling, and continuity plans. Lerian provides the software and tooling — your team operates it.
Pix use cases with Midaz
See how Pix Switch and Midaz work together in practice:
Pix with Transaction Routes
Model validated, reusable Pix transfer flows using Transaction Routes and Operation Routes — from simple transfers to fee collection.
Pix with automated fees
Combine Pix Switch with the Fee Engine for transparent, automated fee management across fintechs and marketplaces.