> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Deploy-time environment variables for the Boleto and bill payments rail, via BTG — BTG integration, credential encryption and key rotation, Midaz ledger binding, reconciliation, and webhook dispatch.

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](/en/reference/byoc-configuration).

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

<Note>
  This rail does **not** mount the systemplane admin API. It uses the shared `POSTGRES_*` datastore shape — see [Datastores](/en/reference/byoc-configuration#datastores).
</Note>

## 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](/en/reference/byoc-configuration#multi-tenancy) and [Default network ports](/en/reference/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](/en/reference/health-and-readiness) for the response shape and startup/drain behavior.