> ## 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
> Deploy-time environment variables for the Pix Indirect, via BTG rail — BTG integration and mTLS, the DB_* datastore convention, Midaz/CRM/Fee bindings, internal webhooks, and worker components.
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/outbound webhook workers — each configured through environment variables set at deploy time by DevOps; changing one requires a restart of 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 it at deploy time from your secret store, never commit it. 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 and carry their own extensive tuning knobs (batch sizes, polling intervals, concurrency, and circuit breakers) in their respective `.env.example` files. See [Default network ports](/en/reference/default-network-ports).
## BTG integration and mTLS
Credentials and the mutual-TLS settings for the connection to BTG.
| 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 (not the shared `POSTGRES_*` shape) for its primary PostgreSQL connection and a separate read replica, plus 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 and 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` | — | Inbound webhook payload cap and retry ceiling. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | — | Recurring-Pix scheduling and reply-handling knobs. |
| `SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | — | 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; the API also answers `/ready`. See [Health and readiness](/en/reference/health-and-readiness) for the response shape and startup/drain behavior.