> ## 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

> Configure the Pix Direct via JD rail — JD OAuth and JDPI endpoints, dynamic QR code hosting with JWS, Midaz ledger binding, and notification settings.

Pix Direct, via JD connects your ledger straight to the Pix arrangement through JD's DICT and SPI gateway. DevOps sets its behavior through environment variables at deploy time. To change a variable, restart the service. This page covers the variables **distinctive to this rail**. For the datastore, multi-tenancy, streaming, telemetry, and authentication knobs that every Lerian Go service shares, 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, and 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. The plugin serves those documents under the host in `QRCODE_PUBLIC_BASE_URL`. Set a bare host (FQDN) with no URL scheme, because JDPI rejects a scheme.

| Variable                   | Default / Required         | Description                                                                          |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------------------ |
| `QRCODE_PUBLIC_BASE_URL`   | **Required**               | Scheme-less host (FQDN) where the plugin serves dynamic-QR payloads and the JWK set. |
| `QRCODE_PAYLOAD_PATH`      | `v1/qrcodes/payload`       | Path segment where the plugin exposes signed QR payloads.                            |
| `QRCODE_JWK_PATH`          | `v1/qrcodes/jwks`          | Path segment where the plugin exposes the JWK set.                                   |
| `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`        | `1`                | 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

The plugin maps Pix cash-in, cash-out, reversal, and intra-PSP flows 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`                                                     | `*/10 * * * * *`   | Cron expression for the transaction-processing job.                      |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC`                                         | `80`               | Age in seconds after which a pending cash-out is flagged as stuck.       |
| `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`                   | `100` · `3`        | 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 you enable multi-tenancy (`MULTI_TENANT_ENABLED=true`), the rail 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.