Environment variables

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.

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.

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 for the shared server knobs and 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).

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_DEBITCash-out (4): OPERATION_ROUTE_CASHOUT_CREDIT_EXTERNAL, OPERATION_ROUTE_CASHOUT_CREDIT_REVERSAL, OPERATION_ROUTE_CASHOUT_DEBIT, OPERATION_ROUTE_CASHOUT_DEBIT_REVERSAL_EXTERNAL

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 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 for the response shape and startup/drain behavior.

Overview

Direct via JD

Indirect via BTG

Environment variables

Server and port

JD integration

Dynamic QR code hosting

Midaz ledger binding

Transaction and operation routes

Jobs and limits

Notifications

CRM

Runtime configuration (systemplane)

Health and readiness

​Server and port

​JD integration

​Dynamic QR code hosting

​Midaz ledger binding

​Transaction and operation routes

​Jobs and limits

​Notifications

​CRM

​Runtime configuration (systemplane)

​Health and readiness

Server and port

JD integration

Dynamic QR code hosting

Midaz ledger binding

Transaction and operation routes

Jobs and limits

Notifications

CRM

Runtime configuration (systemplane)

Health and readiness