- Creating Pix transactions
- Managing keys (DICT)
- Generating QR Codes
- Setting limits
- Handling webhooks
- Recovering from failures
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 uniquetransactionId 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 returned200. Instead, wait for the webhook confirmation to reflect the actual transaction status.