Environment variables

Configure the Boleto and bill payments rail via BTG — BTG OAuth, credential encryption with key rotation, Midaz ledger, reconciliation, and webhooks.

The Boleto and bill payments rail issues boletos and settles bill and tax (DARF) payments through BTG. DevOps sets its behavior through environment variables at deploy time. A change to one variable needs 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_ENABLED toggles multi-tenancy (note the MULTI_TENANCY_ spelling). The Tenant Manager connection uses the shared MULTI_TENANT_* variables. See Multi-tenancy and Default network ports.

BTG integration

These variables set the endpoints and credentials for the BTG connection. They also set the background refresh intervals for the BTG access token and the 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. It authenticates internal calls between the worker and API pods with an API key. Both keys 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	100	Maximum boletos reconciled per cycle, per tenant.
RECONCILIATION_DELAY_MS	500	Delay in milliseconds between reconciliation steps.

Webhook dispatch and idempotency

Variable	Default / Required	Description
WEBHOOK_DISPATCHER_BATCH_SIZE	50	Number of webhook events dispatched per batch.
WEBHOOK_DISPATCHER_INTERVAL	10s	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	300	Timeout in seconds for a database migration run.
MIGRATION_LOCK_TIMEOUT_MS	10000	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. If you enable multi-tenancy, 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.