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

PIX_ISPB is also used to detect intra-PSP (P2P) transfers: when a transfer’s destination ISPB matches this value, the plugin settles it internally instead of routing it to BTG, while still reporting it to BACEN. See Intra-PSP transfers.

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 Fees 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.

Redis cache configuration

VSync uses Redis to cache BTG/DICT entries and CRM holders during reconciliation. In Helm deployments the default REDIS_HOST points to the built-in Valkey sidecar, so no extra setup is required for a standard install.

# Connection (always used)
REDIS_HOST=<release>-valkey:6379
REDIS_MASTER_NAME=
REDIS_DB=0
REDIS_PROTOCOL=3

# Connection pool and retries (always used)
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2
REDIS_MAX_RETRIES=3
REDIS_MIN_RETRY_BACKOFF=8
REDIS_MAX_RETRY_BACKOFF=512

# Authentication (optional — only used if set)
REDIS_PASSWORD=

# TLS (optional — only used if REDIS_TLS=true)
REDIS_TLS=false
REDIS_CA_CERT=

# GCP IAM authentication (optional — only used if REDIS_USE_GCP_IAM=true)
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
REDIS_TOKEN_LIFETIME=60
REDIS_TOKEN_REFRESH_DURATION=45

# VSync cache TTLs (always used)
CACHE_BTG_ENTRY_TTL=30m
CACHE_CRM_HOLDER_TTL=30m

In Helm deployments, the default REDIS_HOST points to the built-in Valkey sidecar (<release-name>-valkey:6379) — no additional Redis setup is needed unless you connect to an external instance.

Connection (always used)

Var	Type	Default	Description
`REDIS_HOST`	string (host:port, CSV)	`<release>-valkey:6379` (Helm chart)	Redis address(es). Default points to the built-in Valkey (`<release-name>-valkey:6379`). Multiple addresses separated by comma define Sentinel/Cluster topology.
`REDIS_MASTER_NAME`	string	`""`	Sentinel master name. Empty = standalone (direct connection).
`REDIS_DB`	int	`0`	Redis logical database number.
`REDIS_PROTOCOL`	int	`3`	RESP protocol version (2 or 3).

Connection pool and retries (always used)

Var	Type	Default	Description
`REDIS_POOL_SIZE`	int	`10`	Maximum connections in the pool.
`REDIS_MIN_IDLE_CONNS`	int	`0`	Minimum idle connections kept ready.
`REDIS_READ_TIMEOUT`	int (seconds)	`3`	Read operation timeout.
`REDIS_WRITE_TIMEOUT`	int (seconds)	`3`	Write operation timeout.
`REDIS_DIAL_TIMEOUT`	int (seconds)	`5`	Timeout to establish the initial connection.
`REDIS_POOL_TIMEOUT`	int (seconds)	`2`	Timeout waiting for a free connection from the pool.
`REDIS_MAX_RETRIES`	int	`3`	Maximum retries for a failed command.
`REDIS_MIN_RETRY_BACKOFF`	int (milliseconds)	`8`	Minimum delay between retries.
`REDIS_MAX_RETRY_BACKOFF`	int (seconds)	`512`	Maximum delay between retries. Note: stored in seconds in code (different unit from min).

Authentication (optional — only used if set)

Var	Type	Default	Description
`REDIS_PASSWORD`	string (secret)	`""`	Redis password. Empty = no password authentication.

TLS (optional — only used if `REDIS_TLS=true`)

Var	Type	Default	Description
`REDIS_TLS`	bool	`false`	Enables TLS. Required `true` in `DEPLOYMENT_MODE=saas` (validated at boot).
`REDIS_CA_CERT`	string (PEM base64)	`""`	CA certificate (base64) to validate the server when TLS is active.

GCP IAM authentication (optional — only used if `REDIS_USE_GCP_IAM=true`)

Var	Type	Default	Description
`REDIS_USE_GCP_IAM`	bool	`false`	Enables GCP IAM authentication (Memorystore) instead of password.
`REDIS_SERVICE_ACCOUNT`	string	`""`	GCP service account that generates the access token.
`GOOGLE_APPLICATION_CREDENTIALS`	string	`""`	GCP credentials path (read via CredentialsBase64FromEnvValue) to generate the token.
`REDIS_TOKEN_LIFETIME`	int (minutes)	`60`	Lifetime of the generated IAM token.
`REDIS_TOKEN_REFRESH_DURATION`	int (minutes)	`45`	Token refresh interval (must be less than lifetime).

VSync cache TTLs (always used)

Var	Type	Default	Description
`CACHE_BTG_ENTRY_TTL`	Go duration	`30m`	Cache TTL for BTG/DICT entries in Redis. Negative value reverts to default.
`CACHE_CRM_HOLDER_TTL`	Go duration	`30m`	Cache TTL for CRM holders in Redis. Negative value reverts to default.

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=

# MED 2.0 Funds Recovery events (DICT flow)
# These route under the DICT flow and fall back to WEBHOOK_DICT_URL,
# then WEBHOOK_DEFAULT_URL, if no entity-specific URL is set.
WEBHOOK_DICT_FUNDS_RECOVERY_URL=
WEBHOOK_DICT_FUNDS_RECOVERY_EVENT_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.

The reconciliation operational window is anchored to the America/Sao_Paulo timezone. On minimal/distroless container images that ship without timezone data, the runtime falls back to UTC and the configured window can drift by up to 3 hours relative to the DICT write-block. Set TZ=America/Sao_Paulo (and ensure tzdata is available) in the reconciliation worker container to keep the window aligned with BACEN.

Indirect Pix cashout and refund endpoints support idempotency through the X-Idempotency request header, with configurable TTL via X-TTL. For retry strategies and implementation details, see Retries and idempotency.

10. Observability (OpenTelemetry)

The plugin ships with full OpenTelemetry instrumentation (traces, metrics, and logs) across the Application and Worker layers. Every Pix flow is traced end to end — transfers (cash-in and cash-out), refunds, inbound and outbound webhooks, DICT reconciliation, and intra-PSP settlement — so you can follow a single payment across the plugin, Midaz, CRM, and BTG calls. Telemetry is disabled by default. Enable it and point the OTLP exporter at your collector:

# Master switch — telemetry is off until this is true
ENABLE_TELEMETRY=true

# Resource attributes that identify this service in your backend
OTEL_RESOURCE_SERVICE_NAME=plugin-br-pix-indirect-btg
OTEL_LIBRARY_NAME=github.com/LerianStudio/plugin-br-pix-indirect-btg
OTEL_RESOURCE_SERVICE_VERSION=${VERSION}
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=${ENV_NAME}

# OTLP collector endpoint (gRPC, default port 4317)
OTEL_EXPORTER_OTLP_ENDPOINT_PORT=4317
OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:${OTEL_EXPORTER_OTLP_ENDPOINT_PORT}

When ENABLE_TELEMETRY=true, OTEL_EXPORTER_OTLP_ENDPOINT is required. Set the same OTel variables on the Application and on each Worker so traces correlate across services.

Exporter: gRPC and TLS

The plugin exports traces, metrics, and logs over OTLP/gRPC. The endpoint scheme controls transport security:

Endpoint value	Transport	Security
`https://collector:4317`	gRPC over TLS	Secure (recommended for production)
`http://collector:4317`	gRPC, plaintext	Insecure — inferred automatically
`collector:4317` (bare `host:port`)	gRPC, plaintext	Insecure — inferred automatically

Insecure (plaintext) exporters are rejected outside development environments. In staging or production, use an https:// endpoint, or explicitly acknowledge the risk via the lib-commons insecure-OTEL allowance only when you fully control the network path to the collector.

Example: collector endpoint

Point the plugin at any OTLP-compatible collector (the OpenTelemetry Collector, Grafana LGTM/Alloy, etc.) listening on the gRPC port:

# Local / development (plaintext gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Production (TLS gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317

The collector then fans telemetry out to your tracing, metrics, and logging backends.

11. Health and readiness

The Application and Workers expose a readiness probe at /readyz (alongside the standard liveness checks). Point your orchestrator’s readiness probe at this endpoint so traffic is only routed once the service and its dependencies are ready.

Transfer purpose (MED 2.0)

The cashout endpoint accepts an optional X-Purpose header that identifies the transaction purpose, used for MED 2.0 refund transfers. When omitted, it defaults to TRANSFER.

# Example: a MED 2.0 refund transfer
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND

Supported values are TRANSFER and INSTANT_PAYMENT_REFUND. See MED 2.0 — Funds Recovery for details.

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
MED 2.0 — Funds Recovery — Cross-account fraud recovery and the X-Purpose header
Refund operations — Distributed partial refunds and unblocking
Intra-PSP transfers — Internal P2P settlement and TRCK002 reporting
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

​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)

​Redis cache configuration

​Connection (always used)

​Connection pool and retries (always used)

​Authentication (optional — only used if set)

​TLS (optional — only used if REDIS_TLS=true)

​GCP IAM authentication (optional — only used if REDIS_USE_GCP_IAM=true)

​VSync cache TTLs (always used)

​8. Internal webhook security

​9. Worker layers

​Inbound worker

​Outbound worker

​URL resolution priority

​Reconciliation worker

​10. Observability (OpenTelemetry)

​Exporter: gRPC and TLS

​Example: collector endpoint

​11. Health and readiness

​Transfer purpose (MED 2.0)

​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)

Redis cache configuration

Connection (always used)

Connection pool and retries (always used)

Authentication (optional — only used if set)

TLS (optional — only used if `REDIS_TLS=true`)

GCP IAM authentication (optional — only used if `REDIS_USE_GCP_IAM=true`)

VSync cache TTLs (always used)

8. Internal webhook security

9. Worker layers

Inbound worker

Outbound worker

URL resolution priority

Reconciliation worker

10. Observability (OpenTelemetry)

Exporter: gRPC and TLS

Example: collector endpoint

11. Health and readiness

Transfer purpose (MED 2.0)

Next steps