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 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 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_ADDRESS (for example :4014). The reconciliation, schedule, and webhook workers each bind a WORKER_PORT for their health probes. See Default network ports.

BTG integration and mTLS

These variables hold the BTG credentials and the mutual-TLS settings in both directions: the client certificate the plugin presents to BTG, and the check of the certificate BTG presents on inbound webhooks.

Variable	Default / Required	Description
`BTG_BASE_URL`	Required	Base URL of the BTG API.
`BTG_CERTIFICATE_URL`	Required when `MTLS_ENABLED=true`	URL of BTG’s public certificate. The API compares it with the certificate BTG presents on inbound webhooks.
`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 when validation is enabled	Secret used to validate inbound BTG webhook signatures.
`BTG_WEBHOOK_VALIDATION_ENABLED`	`false`	Verify BTG webhook signatures. Set `true` in production.
`MTLS_ENABLED`	`false`	Check the certificate BTG presents on inbound webhooks. Enable in production.
`MTLS_CERTIFICATE_HEADER`	`X-Client-Cert`	Header in which your ingress forwards the certificate BTG presented. Your ingress must set this header from the TLS handshake and overwrite any value the caller sends.
`MTLS_CERTIFICATE_TTL`	`24h`	How long the fetched BTG certificate is cached before refresh.
`MTLS_HTTP_TIMEOUT`	`10s`	Timeout for the certificate-fetch HTTP call.
`BTG_OUTBOUND_MTLS_ENABLED`	`false`	Present a client certificate on calls to BTG.
`CLIENT_TLS_CERT_FILE` · `CLIENT_TLS_KEY_FILE`	🔒 Required when outbound mTLS is enabled	Paths to the PEM client certificate and private key.
`CLIENT_TLS_CA_FILE`	—	Optional PEM bundle that verifies the BTG server certificate.

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`	—	libpq TLS mode. Set it explicitly. 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).
`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_PASSWORD`	🔒 —	Redis/Valkey `host:port` 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`	🔒 Required	OAuth credentials for Midaz M2M.
`PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET`	🔒 Required	CRM service URL and OAuth credentials.
`FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET`	🔒 Required when `CASHIN_FEE_CALCULATION_TYPE=segment`	Fees Engine service URL and OAuth credentials.
`FEE_SERVICE_TIMEOUT`	`5000`	Fee request timeout, in milliseconds.
`CASHIN_FEE_CALCULATION_TYPE`	—	Set `segment` to calculate cash-in fees from the account segment. Leave it empty to skip cash-in fees.

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. At least 32 characters.
`INTERNAL_WEBHOOK_VALIDATION_ENABLED`	`false`	Verify internal webhook signatures. Set `true` in production.
`INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE`	`300`	Allowed clock skew, in seconds, 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`	—	Network range of your internal reconciliation service.

Pix and ledger scope

Variable	Default / Required	Description
`PIX_ISPB`	Required	The ISPB (participant code) this deployment operates under: 8 characters, digits or uppercase letters.
`ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END`	—	Daily window (`HH:MM`, São Paulo time) during which the API blocks Pix key create, update, and delete.
`ORGANIZATION_IDS`	Required in production	Comma-separated Midaz organization UUIDs in the licensing scope.
`GOOGLE_APPLICATION_CREDENTIALS`	🔒 —	Google service-account credentials (a file path or the JSON content) for Redis GCP IAM authentication.

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.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments 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