Environment variables

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.

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

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 for the response shape and startup/drain behavior.

Overview

Direct via JD

Indirect via BTG

Environment variables

Components and ports

BTG integration and mTLS

Datastores

Midaz, CRM, and Fees

Internal webhooks and scheduling

Pix and ledger scope

Health and readiness

​Components and ports

​BTG integration and mTLS

​Datastores

​Midaz, CRM, and Fees

​Internal webhooks and scheduling

​Pix and ledger scope

​Health and readiness

Components and ports

BTG integration and mTLS

Datastores

Midaz, CRM, and Fees

Internal webhooks and scheduling

Pix and ledger scope

Health and readiness