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.

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.

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. 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).

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

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