The Pix plugin enables you or your system to send and receive instant payments through Brazil’s real-time payment network. It manages the entire process:

Creating Pix transactions
Managing keys (DICT)
Generating QR Codes
Setting limits
Handling webhooks
Recovering from failures

All of this is available through a secure and easy-to-integrate API.

You don’t need to worry about the complexities of working directly with PSTIs, DICT services, or Core Banking coordination. The Pix plugin abstracts these concerns, offering a reliable layer that guarantees atomic operations, automatic retries, and full traceability.

It was built to serve companies that need fast, compliant, and customizable Pix operations, without requiring them to reinvent their infrastructure.

Why use it?

The Pix plugin exists to simplify the parts of Pix that are painful to build and risky to get wrong.

Whether you're a fintech, digital bank, ERP provider, or embedded finance platform, this plugin gives you:

Reliable orchestration: We manage the entire transaction lifecycle, from balance validation to retries, status updates, and compensation in the event of failure.
Seamless integration: Your application only needs to interact with the Pix plugin API. We handle Core Bank, PSTI, DICT, and QR Code operations behind the scenes.
Webhook-driven design: The plugin sends and receives Pix events asynchronously, so your system stays in sync without polling or guesswork.
Compliance built-in: All logic follows BACEN regulations, including DICT rules, Pix key validation, and ownership confirmation flows.
Audit-ready flows: Each transaction is logged with status, timestamps, and event links, making it easy to track and debug.

When to use it

The Pix plugin is ideal for use cases like:

Digital wallets or banking apps
B2B platforms needing bulk Pix payouts or collections
ERP and financial management systems
Marketplaces with automated payment flows
Institutions handling large volumes of Pix transactions and reversals

Key Concepts

Here are the core ideas and terms you’ll see across the Pix plugin:

Term	Description
PSTI	A “Prestador de Serviços de Tecnologia da Informação” (Information Technology Service Provider) that connects to the Brazilian Central Bank’s Pix infrastructure.
DICT	The Central Bank's directory for Pix keys. It validates, stores, and manages key registrations.
Pix Key	Identifiers like CPF/CNPJ, phone number, email, or EVP used to send/receive Pix transfers.
Webhook	Notifications sent or received by the Authorizer to keep systems in sync. For example, status updates or external Pix deposits.
Cash-in	When your user receives a Pix transfer from another institution.
Reversal	A refund or rollback operation that undoes a Pix transaction.
Pending	A transaction that has been submitted but not yet confirmed by the PSTI.
Confirmed	A transaction that was processed successfully.
Failed	A transaction that could not be processed, often due to insufficient balance or PSTI rejection.

Technical Specs

API Format

Protocol: HTTPS only
Authentication: Bearer Token
Payload: JSON
Status codes: Standard REST (200, 201, 400, 422, 500)

Required environment

Must expose publicly accessible HTTPS endpoints to receive webhooks.
All outgoing requests from Lerian use TLS 1.2+ and verified certificates.
Retry logic on webhooks uses exponential backoff with TTL.

Dependencies

Core Bank (for account validation, balance checks, debits, and credits)
PSTI (for Pix transaction submission and DICT interaction)

Internal validation rules

CPF/CNPJ must be valid and match the Brazilian format.
Email and phone must pass basic format checks.
Pix amounts must be greater than zero and below the configured limits.
Transactions must be uniquely identified by client-supplied ID.

Configurable variables

Variable	Description
`MAX_TRANSACTION_RETRIES`	How many times a transaction will be retried in case of failure.
`WEBHOOK_SIGNATURE_SECRET`	Used to verify incoming/outgoing webhook authenticity.
`PENDING_JOB_INTERVAL`	Frequency (in seconds) for checking pending transactions.
`MAX_PIX_AMOUNT`	An optional cap for any single Pix transfer.

Best Practices

To get the most out of the Pix plugin and avoid common issues, keep the following in mind:

Use idempotent transaction IDs

Always send a unique transactionId generated by your system. This ensures retries don’t result in duplicate transfers.

Handle webhooks before displaying the final status

Do not assume a Pix was successful just because the API returned 200. Instead, wait for the webhook confirmation to reflect the actual transaction status.

Validate webhook authenticity

Use the X-Signature header and your secret to verify that incoming webhooks were truly sent by Lerian.

Design for failure

Transactions may fail due to insufficient balance, PSTI downtime, or other edge cases. Handle errors and retries gracefully, including user messaging.

Monitor pending jobs

If a webhook is missed or a PSTI callback fails, the system will mark the transaction as pending. Jobs will retry automatically, but you can monitor logs or receive alerts if retries exceed thresholds.

Keep your keys updated

If a user changes their phone number or email, consider removing and re-registering the old Pix key to avoid unexpected conflicts.