> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment variables
> Configure the Pix Indirect via BTG rail — BTG mTLS, DB_* datastores, Midaz and CRM bindings, webhook endpoints, and worker components at deploy time.
Pix Indirect via BTG reaches the Pix arrangement through BTG as the direct participant. It ships as several components: an API, plus reconciliation, schedule, and inbound and outbound webhook workers. DevOps sets the environment variables for each component at deploy time. To change a variable, you restart that component. This page covers the variables **distinctive to this rail**. For the multi-tenancy, streaming, telemetry, and authentication knobs shared across every Lerian Go service, see [BYOC configuration essentials](/en/reference/byoc-configuration).
In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks variables you must set. `—` means no default. `🔒` marks a **secret**. Inject each secret at deploy time from your secret store. Never commit a secret. This page lists variable names and behavior only. It prints no secret values.
This rail does **not** mount the systemplane admin API. Its datastore variables use a `DB_*` prefix rather than the shared `POSTGRES_*` shape — see [Datastores](#datastores) below.
## Components and ports
The API component listens on `SERVER_PORT` (default `4014`). `SERVER_ADDRESS` derives from it. The reconciliation, schedule, and webhook workers each bind a `WORKER_PORT` for their health probes. Each worker carries its own tuning knobs — batch sizes, polling intervals, concurrency, and circuit breakers — in its `.env.example` file. See [Default network ports](/en/reference/default-network-ports).
## BTG integration and mTLS
These variables hold the credentials and mutual-TLS settings for the BTG connection.
| Variable | Default / Required | Description |
| -------------------------------- | ------------------ | --------------------------------------------------------------- |
| `BTG_BASE_URL` | **Required** | Base URL of the BTG API. |
| `BTG_CERTIFICATE_URL` | **Required** | Endpoint from which the client certificate is fetched for mTLS. |
| `BTG_CLIENT_ID` | **Required** | OAuth client ID for the BTG API. |
| `BTG_CLIENT_SECRET` | 🔒 **Required** | OAuth client secret for the BTG API. |
| `BTG_WEBHOOK_SECRET` | 🔒 **Required** | Secret used to validate inbound BTG webhook signatures. |
| `BTG_WEBHOOK_VALIDATION_ENABLED` | `true` | Verify BTG webhook signatures. Keep `true` in production. |
| `MTLS_ENABLED` | `false` | Enable mutual TLS on the BTG connection. Enable in production. |
| `MTLS_CERTIFICATE_TTL` | `24h` | How long a fetched client certificate is cached before refresh. |
| `MTLS_HTTP_TIMEOUT` | `10s` | Timeout for the certificate-fetch HTTP call. |
## Datastores
This rail uses a `DB_*` prefix for datastores, not the shared `POSTGRES_*` shape. It connects to a primary PostgreSQL, a separate read replica, MongoDB, and Redis.
| Variable | Default / Required | Description |
| ----------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_HOST` · `DB_PORT` | **Required** | Primary PostgreSQL host and port. |
| `DB_USER` · `DB_PASSWORD` | 🔒 **Required** | Primary PostgreSQL credentials. |
| `DB_NAME` | **Required** | Primary database name. |
| `DB_SSL_MODE` | `disable` | libpq TLS mode. Use `require` or stronger in production. |
| `DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD` | 🔒 — | Optional read-replica connection (same shape as the primary). |
| `REPLICATION_USER` · `REPLICATION_PASSWORD` | 🔒 — | Credentials for the streaming-replication role. |
| `MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME` | 🔒 **Required** | MongoDB connection. `MONGO_URI` sets the connection scheme (`mongodb` or `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD`, and `MONGO_NAME` supply the host, credentials, and database. All combine into one connection string — they are not URI-versus-discrete alternatives. The password is a secret. |
| `MONGO_TLS` | `false` | Enable TLS to MongoDB. |
| `REDIS_HOST` · `REDIS_PORT` · `REDIS_PASSWORD` | 🔒 — | Redis/Valkey endpoint and auth password. |
| `REDIS_TLS` · `REDIS_CA_CERT` | `false` · — | Enable TLS to Redis and supply a base64-encoded PEM CA. |
## Midaz, CRM, and Fees
| Variable | Default / Required | Description |
| --------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------- |
| `MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL` | **Required** | Midaz onboarding and transaction service URLs. |
| `MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID` | **Required** | Midaz organization and ledger UUIDs for Pix bookings. |
| `MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET` | 🔒 — | OAuth credentials for Midaz M2M. |
| `PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET` | 🔒 — | CRM service URL and OAuth credentials. |
| `FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET` | 🔒 — | Fees Engine service URL and OAuth credentials. |
| `FEE_SERVICE_TIMEOUT` | — | Fee request timeout. |
| `CASHIN_FEE_CALCULATION_TYPE` | — | How cash-in fees are calculated. |
## Internal webhooks and scheduling
The API and workers exchange events over an internal webhook channel. They also run recurring and scheduled Pix flows.
| Variable | Default / Required | Description |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------- |
| `INTERNAL_WEBHOOK_SECRET` | 🔒 **Required** | HMAC secret shared between the API and workers for internal webhook signing. |
| `INTERNAL_WEBHOOK_VALIDATION_ENABLED` | `true` | Verify internal webhook signatures. |
| `INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE` | — | Allowed clock skew when validating internal webhook timestamps. |
| `WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES` | `10485760` (10 MB) · `3` | Inbound webhook payload cap and retry ceiling. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | `1` · `720h` · `150ms` · `3` | Recurring-Pix scheduling and reply-handling knobs. |
| `SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | `6` · `2` · `180` · `60` | Scheduled-payment execution window and bounds. |
| `RECONCILIATION_INTERNAL_CIDR` | — | CIDR range trusted for internal reconciliation calls. |
## Pix and ledger scope
| Variable | Default / Required | Description |
| --------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `PIX_ISPB` | **Required** | The ISPB (participant code) this deployment operates under. |
| `ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END` | — | Daily window during which ledger-entry writes are blocked. |
| `ORGANIZATION_IDS` | **Required in production** | Comma-separated Midaz organization UUIDs in the licensing scope. |
| `GOOGLE_APPLICATION_CREDENTIALS` | 🔒 — | Path to a Google service-account credentials file, when running against GCP-managed dependencies. |
## Health and readiness
Each component exposes `GET /health` (liveness) and `GET /readyz` (readiness) on its port. See [Health and readiness](/en/reference/health-and-readiness) for the response shape and the startup and drain behavior.