Environment variables

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 shared datastore, telemetry, and authentication knobs, 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. PLUGIN_AUTH_ENABLED defaults to true, and production forces it on. See Default network ports.

License

A license is mandatory in every environment. The boot fails when either variable is blank. License Manager describes how the product checks the license.

Variable	Default / Required	Description
`LICENSE_KEY`	🔒 Required	The license key that Lerian issued for this rail.
`ORGANIZATION_IDS`	Required	License scope: `global`, or a comma-separated list of lowercase organization UUIDs.

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_COMMON_BASE_URL`	—	Base URL of the BTG Common Methods API. Without it, provider connect does not verify the account and answers `account_verified: false`.
`PROVIDER_CLIENT_ID`	Required	OAuth client ID for the BTG API.
`PROVIDER_CLIENT_SECRET`	🔒 Required	OAuth client secret for the BTG API.
`BTG_WEBHOOK_HMAC_SECRET`	🔒 Required in production	Secret that authenticates inbound BTG webhooks. At least 32 characters.
`BTG_HTTP_TIMEOUT`	`30s`	Timeout for calls to the BTG API.
`BTG_TOKEN_REFRESH_INTERVAL`	`2m`	How often the BTG access token is refreshed. Values above `4m` are capped at `4m`.
`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	Key the API presents on its calls to the worker. At least 32 characters. Worker pods always need it; API pods need it in production.
`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_CRM_URL`	—	Midaz CRM service URL. Bill and DARF payments read the payer from the account holder there, and fail while it is empty.
`MIDAZ_AUTH_ENABLED`	`false`	Authenticate calls to Midaz through Access Manager. Production requires `true`.
`MIDAZ_ALLOW_INSECURE_HTTP`	`false`	Allow a cleartext `http://` Midaz or Access Manager URL. Leave `false` in production.

Internal Midaz outbox

The rail always initializes an internal PostgreSQL outbox for asynchronous Midaz ledger operations. This is an internal work queue, not an external CloudEvents or Streaming Hub catalog. Startup validates the retry and processing-time budgets together and rejects unsafe combinations.

Variable	Default / Required	Description
`OUTBOX_DISPATCH_INTERVAL_SEC`	`2`	Interval in seconds between dispatcher polls.
`OUTBOX_BATCH_SIZE`	`50`	Maximum rows claimed per poll.
`OUTBOX_PUBLISH_MAX_ATTEMPTS`	`1`	Handler attempts within one claimed-row dispatch. Keep this low because Midaz calls already retry internally.
`OUTBOX_PUBLISH_BACKOFF_MS`	`200`	Backoff in milliseconds between handler attempts.
`OUTBOX_RETRY_WINDOW_SEC`	`180`	Delay before a failed row becomes eligible for another dispatch.
`OUTBOX_MAX_DISPATCH_ATTEMPTS`	`10`	Maximum outer dispatch attempts before the row becomes invalid.
`OUTBOX_PROCESSING_TIMEOUT_SEC`	`120`	Processing timeout in seconds for a claimed row.
`OUTBOX_MAX_FAILED_PER_BATCH`	`25`	Maximum failed rows handled in one batch.
`OUTBOX_INCLUDE_TENANT_METRICS`	`false`	Include tenant identifiers in outbox metrics.
`OUTBOX_PRIORITY_EVENT_TYPES`	—	Keep empty. Any non-empty value makes startup fail.
`OUTBOX_ALLOW_EMPTY_TENANT`	`true`	Allow internal outbox rows without a tenant identifier.

Reconciliation

Variable	Default / Required	Description
`RECONCILIATION_INTERVAL`	`90s`	How often the reconciliation cycle runs.
`RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE`	`100`	Maximum payment and settlement items reconciled per cycle.
`RECONCILIATION_MAX_BOLETOS_PER_CYCLE`	`40`	Maximum boletos reconciled per cycle.
`RECONCILIATION_DELAY_MS`	`500`	Delay in milliseconds between reconciliation steps.
`PAYMENT_UNCONFIRMED_DISPATCH_GRACE`	`5m`	Minimum age before the reconciliation fails an `UNCONFIRMED` payment that was never sent to BTG. Nothing was paid, and any reservation is cancelled. Startup fails below `5m`.
`PAYMENT_UNCONFIRMED_ABSENCE_WINDOW`	`30m`	How long BTG must have no record of a sent bill or utility payment before the reconciliation fails it with `PBP-0211` and releases its funds. Startup fails below `10m`.
`PAYMENT_UNCONFIRMED_BATCH_SIZE`	`50`	Maximum `UNCONFIRMED` payments read per cycle. Values above `100` read `100`.
`RECONCILIATION_BOLETO_GRACE_PERIOD`	`5m`	Age a boleto must reach before the reconciliation asks BTG about it. Values below `2m` read `2m`.
`RECONCILIATION_BOLETO_PROCESSING_CEILING`	`24h`	Age, by the creation time at BTG, after which a boleto that BTG still answers as `PROCESSING` or `ERROR` stops counting as a registration in progress. It must be greater than `RECONCILIATION_BOLETO_GRACE_PERIOD`, or the reconciliation does not start. Values below `15m` read `15m`.
`RECONCILIATION_BOLETO_RESERVATION_GRACE_PERIOD`	`30m`	Minimum age before the reconciliation asks BTG about a boleto issuance that holds a nosso número and has no BTG identifier.

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.

Bill consult

These variables configure POST /v1/payments/consult. The rate limit counts consults per caller, and each replica counts on its own.

Variable	Default / Required	Description
`CONSULT_RATE_LIMIT_MAX`	`100`	Maximum consults per caller in one window. `0` or a negative value reads `100`.
`CONSULT_RATE_LIMIT_WINDOW_SEC`	`60`	Length of the window, in seconds. `0` or a negative value reads `60`.
`CONSULT_AUDIT_HMAC_KEY`	🔒 Required	The key the service uses to fingerprint the payment line in each consult audit record. Use at least 32 characters, with no spaces at the start or end. A pod that serves the payment API does not start without it. In production, the service refuses the example value from the configuration template.

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. See Health and readiness for the response shape.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Environment variables

Server and port

License

BTG integration

Credential encryption and internal API keys

Midaz ledger binding

Internal Midaz outbox

Reconciliation

Webhook dispatch and idempotency

Bill consult

Migrations

Health and readiness

​Server and port

​License

​BTG integration

​Credential encryption and internal API keys

​Midaz ledger binding

​Internal Midaz outbox

​Reconciliation

​Webhook dispatch and idempotency

​Bill consult

​Migrations

​Health and readiness

Server and port

License

BTG integration

Credential encryption and internal API keys

Midaz ledger binding

Internal Midaz outbox

Reconciliation

Webhook dispatch and idempotency

Bill consult

Migrations

Health and readiness