The Pix Indirect Plugin (BTG) connects to multiple Lerian services and external providers to process Pix payments. Setting it up involves configuring the plugin’s connection to each service and preparing the data those services need to operate. The plugin runs as two main layers — an Application that exposes the Pix API and processes business logic, and a set of Workers that handle inbound webhooks from BTG, outbound event delivery to your system, and DICT reconciliation with BACEN. Both layers share the same foundational configuration (license, Midaz, CRM, BTG) but have their own service-specific settings.

Prerequisites

Before you begin, make sure you have:

Your ISPB (Identificador do Sistema de Pagamentos Brasileiro) — the 8-digit identifier derived from your institution’s CNPJ
Access to your Midaz and CRM instances (deployed and running)
Access to BTG provider services (BTG provides the credentials)

# Your institution's ISPB (8 digits)
PIX_ISPB=12345678

1. License

The plugin is an enterprise solution and requires a valid license to operate. Lerian provides the license key during onboarding.

# License key provided by Lerian
LICENSE_KEY=

# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=

Related documentation: Lerian’s License

2. Access Manager (optional)

Access Manager handles authentication for the plugin. When enabled, it validates all incoming requests before they reach the plugin’s API.

# Require authentication for all plugin requests (true/false)
PLUGIN_AUTH_ENABLED=false

# Access Manager service URL
PLUGIN_AUTH_ADDRESS=

When PLUGIN_AUTH_ENABLED=true, the plugin validates every request’s Authorization header to ensure:

The token belongs to an authorized user or application
The token grants access to the requested API endpoint and method

You only need to provide client credentials (CLIENT_ID / CLIENT_SECRET) for Midaz, CRM, and Fee services if those services also have Access Manager authentication enabled.

Related documentation: Access Manager

3. Midaz

Midaz is the core ledger for all Pix transactions the plugin processes. The plugin posts every cash-in, cash-out, and refund operation to Midaz as a double-entry transaction.

Connection

# Your organization ID in Midaz
MIDAZ_ORGANIZATION_ID=

# Your ledger ID in Midaz
MIDAZ_LEDGER_ID=

# Midaz Transaction module URL
MIDAZ_TRANSACTION_URL=

# Midaz Onboarding module URL
MIDAZ_ONBOARDING_URL=

# Midaz API credentials (required if Midaz has authentication enabled)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=

Asset requirements

Configure an asset in your organization and ledger with these properties:

Property	Value
Type	`currency`
Code	`BRL`

Link all accounts to your ledger using the BRL asset. The plugin rejects operations on accounts that don’t match this configuration.

Account setup

Before using the plugin, create an account in Midaz for each customer under your ISPB. Use the Create an Account endpoint to set up accounts. Each account must:

Belong to your configured organization and ledger
Use the BRL asset

X-Account-Id header

Many Pix operations require the X-Account-Id header to identify which account is performing the action. This ID corresponds to the Midaz ledger account ID. When you call a plugin endpoint, the X-Account-Id value tells the plugin:

Which account to use for ledger operations
Which customer data to fetch from CRM
Which balance to validate and update

How the plugin uses the account ID

The plugin uses the account ID differently depending on the operation type:

Flow type	How the plugin uses the account ID
Non-transactional (e.g., creating keys or QR codes)	Fetches customer and bank account data from CRM
Transactional (e.g., payments, refunds)	Fetches customer data for payment initiation
	Validates account data for incoming payment authorization
	Executes the transaction in the ledger

Account compliance

The plugin does not enforce business-level account restrictions, such as blocked or suspended accounts. Your application is responsible for validating account status before calling the plugin. To prevent Pix settlements on a specific account, block it directly in Midaz. The plugin receives a rejection when it attempts to post the transaction. Related documentation:

4. CRM

The CRM stores customer (holder) information and their associated bank accounts. Every Midaz account must have a corresponding holder and alias account in the CRM to perform Pix operations. The plugin queries CRM data to:

Register and validate Pix keys
Build payment messages for BACEN
Authorize incoming transactions
Process refund and dispute workflows

Connection

# CRM base URL
PLUGIN_CRM_BASE_URL=

# CRM API credentials (required if CRM has authentication enabled)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=

Holders

Holder data represents the customer who owns the account. Create each holder in the CRM before executing any Pix operation for that customer.

Required fields

Field	Requirement	Example
`name`	Maximum 120 characters	`Maria Silva Santos`
`document`	For `NATURAL_PERSON`, a CPF with 11 digits; for `LEGAL_PERSON`, a CNPJ with 14 digits (numbers only)	`12345678900`
`type`	Person type (enum values from CRM)	`NATURAL_PERSON`

Optional fields

Field	When to use
`legalPerson.tradeName`	When associating a trade name with the key data
`addresses.primary`	Required for Due Date collection creation

Related documentation: Create a Holder

Alias accounts

Alias accounts link a Midaz account to its banking details. Each alias account must include the banking information that the Pix ecosystem requires for transaction processing.

Required fields

Field	Requirement	Example
`accountId`	Midaz account ID (UUID)	`3c90c3cc-0d44-4b50-8888-8dd25736052a`
`bankingDetails.branch`	Exactly 4 digits	`0001`
`bankingDetails.account`	1 to 20 digits	`123456789`
`bankingDetails.type`	Account type (see table below)	`CACC`
`bankingDetails.openingDate`	YYYY-MM-DD format	`2024-01-15`

The bankingDetails.branch field must contain exactly 4 digits. Pad with leading zeros if necessary. For example, if the branch number is 1, register it as 0001. The plugin can only validate the account in the CRM when the branch code follows this format.

Supported account types

Code	Description
`CACC`	Checking account
`SLRY`	Salary account
`SVGS`	Savings account
`TRAN`	Transaction account

Related documentation: Create an Alias Account

5. BTG provider

BTG is the direct participant that connects your institution to BACEN’s Pix infrastructure. BTG provides the credentials directly when your institution signs up for indirect BACEN integration.

Connection

# BTG API base URL
BTG_BASE_URL=

# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=

mTLS (webhook security)

Mutual TLS (mTLS) adds an extra layer of security by validating BTG’s certificate on webhook requests. This ensures that incoming webhooks genuinely originate from BTG.

# Enable mTLS validation (true/false)
# Use 'true' in production, 'false' for local development
MTLS_ENABLED=false

# How long to cache the certificate before refreshing
# Format: Go duration (e.g., 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# BTG endpoint that provides the public certificate for signature validation
BTG_CERTIFICATE_URL=

# Timeout for certificate fetch requests
# Format: Go duration (e.g., 10s, 30s)
MTLS_HTTP_TIMEOUT=10s

Always enable mTLS in production environments. Only disable it during local development.

6. Fee service (optional)

Enable fee calculation to automatically charge and distribute fees on incoming payments. This is optional — if you don’t configure it, the plugin processes transactions without fee calculation.

Connection

# Fee calculation method (currently only 'segment' is supported)
CASHIN_FEE_CALCULATION_TYPE=

# Fee service URL
FEE_SERVICE_URL=

# Request timeout in milliseconds
FEE_SERVICE_TIMEOUT=5000

# Fee service API credentials (required if the fee service has authentication enabled)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=

How it works

When you set CASHIN_FEE_CALCULATION_TYPE=segment, the plugin:

Retrieves the segment associated with the receiving account
Calculates applicable fees before processing the transaction in Midaz
Distributes the incoming payment according to any package rules linked to that segment

Setup steps

Create segments in Midaz — Define the account segments that determine fee rules
Configure packages in Fee Engine — Link each segment to its fee calculation rules
Assign segments to accounts — Create or update Midaz accounts with the appropriate segment ID

Related documentation:

7. DICT reconciliation (VSync)

VSync reconciles your local DICT data with BACEN by processing all key-related events from the day. This ensures your local state stays consistent with BACEN’s authoritative records.

# Write block window (24-hour format, UTC)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Allowed network range for reconciliation services
RECONCILIATION_INTERNAL_CIDR=

During reconciliation, the database temporarily blocks write operations to prevent data inconsistencies with BACEN. Plan the write block window during low-traffic periods.

The CIDR range restricts which networks can trigger reconciliation. The plugin automatically rejects requests from outside this range.

8. Internal webhook security

The plugin uses an internal communication channel between the Worker and Application services. HMAC-SHA256 signatures secure this channel to prevent tampering and replay attacks.

# Shared secret for signing internal requests (Worker -> Application)
# Must be at least 32 characters
# Generate one with: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validate signatures on incoming internal webhooks (true/false)
# Always use 'true' in production
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Maximum age (in seconds) for request timestamps before rejection
# Default: 300 (5 minutes)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300

Use the exact same INTERNAL_WEBHOOK_SECRET value in both the Application and Worker services. A mismatch causes the plugin to reject all internal webhooks.

9. Worker layers

The plugin operates with three worker layers, each handling a different part of the Pix lifecycle. All workers run as separate services alongside the main application.

Inbound worker

The inbound worker receives webhook notifications from BTG and forwards them to your application for processing.

# URL where the application receives internal webhooks
WEBHOOK_INBOUND_BASE_URL=

# Shared secret for signing requests (must match the application's INTERNAL_WEBHOOK_SECRET)
INTERNAL_WEBHOOK_SECRET=

Outbound worker

The outbound worker sends event notifications from the plugin to your application via webhooks. This is how your system stays informed about Pix events (transfers, refunds, claims, disputes).

URL resolution priority

The plugin resolves webhook URLs in this order, using the first match:

Entity URL — A URL specific to the event type (e.g., WEBHOOK_DICT_CLAIM_URL)
Flow URL — A URL for the broader category (e.g., WEBHOOK_DICT_URL)
Default URL — The fallback URL (WEBHOOK_DEFAULT_URL)

# Default fallback URL
WEBHOOK_DEFAULT_URL=

# DICT-related events
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=

You can start with just WEBHOOK_DEFAULT_URL to receive all events at a single endpoint, then gradually split into entity-specific URLs as your system evolves.

For a deep dive into webhook event types, payloads, retry behavior, and best practices, see the Webhooks guide.

Reconciliation worker

The reconciliation worker needs the same credentials as the Application layer for these services:

CRM — URL and credentials
BTG — URL and credentials
Midaz — Organization ID

See the corresponding sections above for details on each configuration. You can restrict when the worker operates by configuring a specific time window. This is especially useful for scheduling reconciliation tasks during off-peak hours. The plugin supports time windows that span midnight.

# Start time in HH:MM format (24-hour). Example: "23:00" for 11 PM
RECONCILIATION_START_TIME=

# End time in HH:MM format (24-hour). Example: "05:00" for 5 AM
RECONCILIATION_END_TIME=

If you leave both fields empty, the worker runs without time restrictions — 24/7.

Next steps

With the plugin fully configured, you’re ready to start operating Pix. Explore these topics to go deeper:

Webhooks — Event types, payloads, retries, and best practices
Main domains: DICT — Understanding Pix key management
Main domains: transactions — Transaction flows and lifecycle
Main domains: QR Codes — Static and dynamic QR code generation
API reference — Full API documentation for DICT, Claims, Transactions, QR Codes, and MED operations

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

Bank Transfer (TED)

​Prerequisites

​1. License

​2. Access Manager (optional)

​3. Midaz

​Connection

​Asset requirements

​Account setup

​X-Account-Id header

​How the plugin uses the account ID

​Account compliance

​4. CRM

​Connection

​Holders

​Required fields

​Optional fields

​Alias accounts

​Required fields

​Supported account types

​5. BTG provider

​Connection

​mTLS (webhook security)

​6. Fee service (optional)

​Connection

​How it works

​Setup steps

​7. DICT reconciliation (VSync)

​8. Internal webhook security

​9. Worker layers

​Inbound worker

​Outbound worker

​URL resolution priority

​Reconciliation worker

​Next steps

Prerequisites

1. License

2. Access Manager (optional)

3. Midaz

Connection

Asset requirements

Account setup

X-Account-Id header

How the plugin uses the account ID

Account compliance

4. CRM

Connection

Holders

Required fields

Optional fields

Alias accounts

Required fields

Supported account types

5. BTG provider

Connection

mTLS (webhook security)

6. Fee service (optional)

Connection

How it works

Setup steps

7. DICT reconciliation (VSync)

8. Internal webhook security

9. Worker layers

Inbound worker

Outbound worker

URL resolution priority

Reconciliation worker

Next steps