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.

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

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