> ## 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 Pix Direct, via JD rail — JD integration, dynamic-QR hosting, Midaz ledger binding, transaction routes, and notifications.

Pix Direct, via JD connects your ledger straight to the Pix arrangement through JD's DICT and SPI gateway. 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, streaming, 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>

## Server and port

The service listens on the address in `SERVER_ADDRESS` (default `:8080`). The liveness, readiness, and version probes bind this same port. See [Server](/en/reference/byoc-configuration#server) for the shared server knobs and [Default network ports](/en/reference/default-network-ports).

## JD integration

Credentials and endpoints for JD's OAuth-secured API and its Pix (JDPI) surface.

| Variable                   | Default / Required   | Description                                              |
| -------------------------- | -------------------- | -------------------------------------------------------- |
| `JD_BASE_URL`              | **Required**         | Base URL of the JD API.                                  |
| `JD_CLIENT_ID`             | **Required**         | OAuth client ID for the JD API.                          |
| `JD_SECRET`                | 🔒 **Required**      | OAuth client secret for the JD API.                      |
| `JD_GRANT_TYPE`            | `client_credentials` | OAuth grant type used against JD.                        |
| `JD_BANK_ID`               | **Required**         | Your institution identifier at JD.                       |
| `JD_USE_SERVICE_SEGMENTS`  | `false`              | Route calls through JD service segments when `true`.     |
| `JD_PIX_URL`               | **Required**         | Base URL of the JD Pix (JDPI) API.                       |
| `JD_PIX_CLIENT_ID`         | **Required**         | OAuth client ID for the JD Pix API.                      |
| `JD_PIX_CLIENT_SECRET`     | 🔒 **Required**      | OAuth client secret for the JD Pix API.                  |
| `JDPI_MAX_RETRIES`         | `2`                  | Retry attempts on a failed JDPI call.                    |
| `JDPI_RETRY_BASE_DELAY_MS` | `100`                | Base backoff delay in milliseconds between JDPI retries. |

## Dynamic QR code hosting

The rail hosts signed (JWS) dynamic-QR payloads and the JWK set used to verify them. `QRCODE_PUBLIC_BASE_URL` is the externally reachable base under which those documents are served.

| Variable                   | Default / Required         | Description                                                           |
| -------------------------- | -------------------------- | --------------------------------------------------------------------- |
| `QRCODE_PUBLIC_BASE_URL`   | **Required**               | Public base URL where dynamic-QR payloads and the JWK set are served. |
| `QRCODE_PAYLOAD_PATH`      | **Required**               | Path segment where signed QR payloads are exposed.                    |
| `QRCODE_JWK_PATH`          | **Required**               | Path segment where the JWK set is exposed.                            |
| `QRCODE_JWS_CONTENT_TYPE`  | `application/jose`         | `Content-Type` returned for the signed payload.                       |
| `QRCODE_JWKS_CONTENT_TYPE` | `application/jwk-set+json` | `Content-Type` returned for the JWK set.                              |

## Midaz ledger binding

Which Midaz organization, ledger, asset, and external account this rail books Pix movements against, plus the ledger service endpoints and machine-to-machine credentials.

| Variable                | Default / Required | Description                                               |
| ----------------------- | ------------------ | --------------------------------------------------------- |
| `MIDAZ_ORGANIZATION_ID` | **Required**       | Midaz organization UUID that owns the Pix ledger.         |
| `MIDAZ_LEDGER_ID`       | **Required**       | Midaz ledger UUID for Pix bookings.                       |
| `MIDAZ_ASSET_ID`        | **Required**       | Asset (currency) booked for Pix operations.               |
| `MIDAZ_EXTERNAL_ID`     | **Required**       | External account used as the Pix settlement counterparty. |
| `MIDAZ_URL_ONBOARDING`  | **Required**       | Midaz onboarding service URL.                             |
| `MIDAZ_URL_TRANSACTION` | **Required**       | Midaz transaction service URL.                            |
| `MIDAZ_AUTH_ADDRESS`    | —                  | Access Manager URL for Midaz M2M tokens.                  |
| `MIDAZ_CLIENT_ID`       | —                  | OAuth client ID for Midaz M2M.                            |
| `MIDAZ_CLIENT_SECRET`   | 🔒 —               | OAuth client secret for Midaz M2M.                        |
| `MIDAZ_TIMEOUT`         | `30000`            | Midaz request timeout in milliseconds.                    |

## Transaction and operation routes

Pix cash-in, cash-out, reversal, and intra-PSP flows are mapped onto named Midaz transaction and operation routes. Set one value per flow so the plugin books each Pix event onto the correct route.

| Variable                                                                                             | Default / Required | Description                                                                                     |
| ---------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
| `TRANSACTION_ROUTE_CASHIN` · `TRANSACTION_ROUTE_CASHIN_QRCODE` · `TRANSACTION_ROUTE_CASHIN_REVERSAL` | **Required**       | Transaction-route IDs for the cash-in family (standard, QR code, reversal).                     |
| `TRANSACTION_ROUTE_CASHOUT` · `TRANSACTION_ROUTE_CASHOUT_REVERSAL`                                   | **Required**       | Transaction-route IDs for the cash-out family.                                                  |
| `TRANSACTION_ROUTE_INTRAPSP` · `TRANSACTION_ROUTE_INTRAPSP_REVERSAL`                                 | **Required**       | Transaction-route IDs for intra-PSP transfers and their reversals.                              |
| `OPERATION_ROUTE_CASHIN_*`                                                                           | **Required**       | Operation-route IDs for each cash-in leg (credit, debit, QR code, external, reversal variants). |
| `OPERATION_ROUTE_CASHOUT_*`                                                                          | **Required**       | Operation-route IDs for each cash-out leg (credit, debit, external, reversal variants).         |

<Note>
  `OPERATION_ROUTE_CASHIN_*` and `OPERATION_ROUTE_CASHOUT_*` stand for exactly twelve concrete per-leg route-mapping variables (eight cash-in, four cash-out). Each maps one pipeline leg to a Midaz operation-route ID — set each one explicitly:

  **Cash-in (8):** `OPERATION_ROUTE_CASHIN_CREDIT`, `OPERATION_ROUTE_CASHIN_CREDIT_QRCODE`, `OPERATION_ROUTE_CASHIN_CREDIT_REVERSAL`, `OPERATION_ROUTE_CASHIN_DEBIT`, `OPERATION_ROUTE_CASHIN_DEBIT_QRCODE_EXTERNAL`, `OPERATION_ROUTE_CASHIN_DEBIT_REVERSAL_EXTERNAL`, `OPERATION_ROUTE_CASHIN_REVERSAL_CREDIT`, `OPERATION_ROUTE_CASHIN_REVERSAL_DEBIT`

  **Cash-out (4):** `OPERATION_ROUTE_CASHOUT_CREDIT_EXTERNAL`, `OPERATION_ROUTE_CASHOUT_CREDIT_REVERSAL`, `OPERATION_ROUTE_CASHOUT_DEBIT`, `OPERATION_ROUTE_CASHOUT_DEBIT_REVERSAL_EXTERNAL`
</Note>

## Jobs and limits

| Variable                                                                     | Default / Required | Description                                                                          |
| ---------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------ |
| `JOBS_CRON`                                                                  | `*/10 * * * * *`   | Cron expression for the reconciliation/housekeeping job.                             |
| `JOBS_CRON_TRANSACTIONS`                                                     | —                  | Cron expression for the transaction-processing job.                                  |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC`                                         | —                  | Age in seconds after which a pending transaction is treated as stuck and reconciled. |
| `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` · `TRANSACTION_LIMIT_DAILY_PERIOD_END` | —                  | Start and end of the daily window used for transaction-limit accounting.             |
| `MAX_PAGINATION_LIMIT` · `MAX_PAGINATION_MONTH_DATE_RANGE`                   | —                  | Upper bounds on list page size and date-range span.                                  |

## Notifications

Optional end-customer notifications for Pix events. Leave the provider blocks unset to disable that channel.

| Variable                 | Default / Required | Description                                     |
| ------------------------ | ------------------ | ----------------------------------------------- |
| `SENDGRID_API_KEY`       | 🔒 —               | SendGrid API key for email notifications.       |
| `SENDGRID_FROM_EMAIL`    | —                  | Sender address for email notifications.         |
| `SENDGRID_FROM_TEMPLATE` | —                  | SendGrid template ID used for the message body. |
| `TWILIO_ACCOUNT_SID`     | 🔒 —               | Twilio account SID for SMS notifications.       |
| `TWILIO_AUTH_TOKEN`      | 🔒 —               | Twilio auth token for SMS notifications.        |
| `TWILIO_PHONE_NUMBER`    | —                  | Sender phone number for SMS notifications.      |

## CRM

| Variable            | Default / Required | Description                               |
| ------------------- | ------------------ | ----------------------------------------- |
| `CRM_URL`           | —                  | CRM service URL for counterparty lookups. |
| `CRM_CLIENT_ID`     | —                  | OAuth client ID for CRM M2M.              |
| `CRM_CLIENT_SECRET` | 🔒 —               | OAuth client secret for CRM M2M.          |

## Runtime configuration (systemplane)

This rail mounts the systemplane admin API on its main port, gated by `SYSTEMPLANE_ENABLED`.

| Variable              | Default / Required | Description                                             |
| --------------------- | ------------------ | ------------------------------------------------------- |
| `SYSTEMPLANE_ENABLED` | `false`            | Enable the systemplane runtime-configuration admin API. |

When enabled, the service exposes an authenticated plane for reading and writing runtime configuration. See [Systemplane](/en/reference/systemplane/overview) for the API, namespaces, and required permissions.

## Health and readiness

The rail exposes `GET /health` (liveness) and `GET /readyz` (readiness) on the main port, plus `/metrics` and `/version`. When multi-tenancy is enabled (`MULTI_TENANT_ENABLED=true`), 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.