Environment variables

The Boleto and bill payments rail issues boletos and settles bill and tax (DARF) payments through BTG. Its behavior is configured through environment variables set at deploy time by DevOps; changing one requires a service restart. This page covers the variables distinctive to this rail — for the datastore, multi-tenancy, 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. It uses the shared POSTGRES_* datastore shape — see Datastores.

Server and port

The service listens on the address in SERVER_ADDRESS (default :8080). The liveness, readiness, and version probes bind this same port. Multi-tenancy is toggled with MULTI_TENANCY_ENABLED (note the MULTI_TENANCY_ spelling; the Tenant Manager connection uses the shared MULTI_TENANT_* variables). See Multi-tenancy and Default network ports.

BTG integration

Endpoints and credentials for the connection to BTG, plus the background refresh intervals for the BTG access token and synced credentials.

Variable	Default / Required	Description
`BTG_API_BASE_URL`	Required	Base URL of the BTG API.
`BTG_AUTH_URL`	Required	BTG OAuth token endpoint.
`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_HTTP_TIMEOUT`	`30s`	Timeout for calls to the BTG API.
`BTG_TOKEN_REFRESH_INTERVAL`	`1h`	How often the BTG access token is refreshed.
`BTG_CREDENTIAL_SYNC_INTERVAL`	`20h`	How often stored BTG credentials are re-synced.

Credential encryption and internal API keys

The rail encrypts stored credentials at rest and authenticates internal (worker-to-API) calls with an API key. Both support a _PREVIOUS slot so you can rotate the active value without downtime.

Variable	Default / Required	Description
`CREDENTIAL_ENCRYPTION_KEY`	🔒 Required	Key used to encrypt stored credentials at rest.
`CREDENTIAL_ENCRYPTION_KEY_PREVIOUS`	🔒 —	Prior encryption key, kept readable during rotation.
`INTERNAL_API_KEY`	🔒 Required	API key authenticating internal worker-to-API calls.
`INTERNAL_API_KEY_PREVIOUS`	🔒 —	Prior internal API key, accepted during rotation.
`INTERNAL_WORKER_URL`	Required	URL the API uses to reach the internal worker.

Midaz ledger binding

Variable	Default / Required	Description
`MIDAZ_LEDGER_URL`	Required	Midaz ledger service URL.
`MIDAZ_DEFAULT_ORG_ID`	Required	Default Midaz organization UUID for bookings.
`MIDAZ_DEFAULT_LEDGER_ID`	Required	Default Midaz ledger UUID for bookings.
`MIDAZ_ALLOW_INSECURE_HTTP`	`false`	Allow a cleartext `http://` Midaz URL. Leave `false` in production.

Reconciliation

Variable	Default / Required	Description
`RECONCILIATION_INTERVAL`	`5m`	How often the reconciliation cycle runs.
`RECONCILIATION_LOOKBACK_HOURS`	`24`	How far back each reconciliation cycle scans.
`RECONCILIATION_MAX_BOLETOS_PER_CYCLE`	—	Maximum boletos reconciled per cycle.
`RECONCILIATION_DELAY_MS`	—	Delay in milliseconds between reconciliation steps.

Webhook dispatch and idempotency

Variable	Default / Required	Description
`WEBHOOK_DISPATCHER_BATCH_SIZE`	—	Number of webhook events dispatched per batch.
`WEBHOOK_DISPATCHER_INTERVAL`	—	Interval between webhook dispatch cycles.
`WEBHOOK_SKIP_URL_VALIDATION`	`false`	Skip subscriber-URL validation. Keep `false` in production.
`IDEMPOTENCY_RECORD_TTL_HOURS`	`48`	How long idempotency records are retained, in hours.
`ACCOUNT_VALIDATION_DISABLED`	`false`	Disable account validation. Keep `false` in production.

Migrations

Variable	Default / Required	Description
`MIGRATION_TIMEOUT_SEC`	—	Timeout in seconds for a database migration run.
`MIGRATION_LOCK_TIMEOUT_MS`	—	Timeout in milliseconds to acquire the migration lock.

Health and readiness

The rail exposes GET /health (liveness) and GET /readyz (readiness) on the main port. When multi-tenancy is enabled, it adds an auth-gated per-tenant probe at GET /readyz/tenant/{id}. See Health and readiness for the response shape and startup/drain behavior.

Overview

Console

Environment variables

Server and port

BTG integration

Credential encryption and internal API keys

Midaz ledger binding

Reconciliation

Webhook dispatch and idempotency

Migrations

Health and readiness

​Server and port

​BTG integration

​Credential encryption and internal API keys

​Midaz ledger binding

​Reconciliation

​Webhook dispatch and idempotency

​Migrations

​Health and readiness

Server and port

BTG integration

Credential encryption and internal API keys

Midaz ledger binding

Reconciliation

Webhook dispatch and idempotency

Migrations

Health and readiness