Environment variables

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, streaming, telemetry, and authentication knobs that every Lerian Go service shares, see BYOC configuration essentials.

These variables describe a BYOC deployment. On Lerian Cloud, you do not set them.

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.

Connections without TLS

Variable	Default / Required	Description
`ALLOW_INSECURE_TLS`	`false`	Set `true` to let the rail use `http://` addresses, in every environment. It covers `MIDAZ_URL_TRANSACTION`, `PLUGIN_AUTH_HOST` for the outbound tokens, `COURIER_URL`, and the `delivery.endpointUrl` of each indirect participant. In multi-tenant mode, it also covers the Tenant Manager and the JD and JD Courier addresses of each tenant. For its effect on the datastores, see BYOC configuration essentials.

With true, Pix JD accepts http:// addresses for these connections in every environment, production included. Traffic on an http:// connection is not encrypted, and it carries credentials or Pix data. Pix JD logs a warning at startup when the value is true. Keep the value false when every connection serves https.

JD integration

Credentials, endpoints, retries, and time limits 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_USE_SERVICE_SEGMENTS`	`false`	How the rail builds JD addresses. Set `true` when JD gives you a gateway address, where each JD service has its own path segment after `JD_BASE_URL`. Keep `false` when JD gives you the direct address, where every path starts with `<JD_BASE_URL>/jdpi/`. Ask JD which address type you have.
`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.
`JDPI_CALL_TIMEOUT_MS`	`30000`	Time limit of one JDPI HTTP attempt, in milliseconds.
`JDPI_TOTAL_TIMEOUT_MS`	`50000`	Time limit of one whole JDPI call from the API, in milliseconds: the token, every attempt, and every wait between attempts.

The two timeouts apply in both deployment modes. A value of 0 or less gives the default. Keep JDPI_TOTAL_TIMEOUT_MS below the timeout of your ingress. Then, on a client request, a JD that does not answer gets 504 PIX-1051 from the rail, not a timeout from the proxy.

Your own ISPB is not an environment variable. It comes from the systemplane key tenancy/jd_integration_binding, field ispb. There is no environment fallback.While that key is empty, the rail starts and answers its health probe. It refuses every payment on every money route with 409 PIX-0092. Write the key and the next request passes, with no restart. For the steps, see Setting up the rail.

Payment-order signing

The key that signs each outbound payment order. They are optional: you need them only when your JD environment requires signed orders. The API reads these variables. The worker does not.

Variable	Default / Required	Description
`JD_PAYMENT_SIGNING_PRIVATE_KEY`	🔒 —	PEM of the private key that signs the payment order.
`JD_PAYMENT_SIGNING_CERTIFICATE`	—	PEM of the certificate registered in JDPI Cabine for that key.
`JD_PAYMENT_SIGNING_ALGORITHM`	`ECDSA_P256_SHA256`	`ECDSA_P256_SHA256`, `ECDSA_P384_SHA384`, or `RSA_PKCS1_SHA256`.

Leave all three empty and the rail sends unsigned orders. Set only some of them, or a value that is not usable, and the rail refuses each payment to another institution with 409 PIX-0136 before it calls JD. For the key, the certificate, and JDPI Cabine, see Payment-order signing.

Dynamic QR code hosting

The rail hosts signed (JWS) dynamic-QR payloads and the JWK set that verifies them. It serves those documents under the host in QRCODE_PUBLIC_BASE_URL. The QR codes reference section gives the public route shapes, the host form without a scheme, and the 77-character payload-URL limit from BACEN. The variables below set the parts that this deployment controls.

Variable	Default / Required	Description
`QRCODE_PUBLIC_BASE_URL`	Required	Host (FQDN) without a scheme, where the plugin serves dynamic-QR payloads and the JWK set.
`QRCODE_PAYLOAD_PATH`	`qr`	Path segment where the plugin serves signed QR payloads. Each extra character uses the same 77-character limit as the host.
`QRCODE_JWK_PATH`	`v1/qrcodes/jwks`	Path segment where the plugin serves the JWK set.
`QRCODE_JWS_CONTENT_TYPE`	`application/jose`	`Content-Type` of the signed payload.
`QRCODE_JWKS_CONTENT_TYPE`	`application/jwk-set+json`	`Content-Type` of the JWK set.

Do not change QRCODE_PAYLOAD_PATH after go-live. A printed or displayed QR code carries the old URL, and nothing redirects it.

Midaz ledger connection

The ledger service endpoints and the machine-to-machine credentials.

Variable	Default / Required	Description
`MIDAZ_URL_ONBOARDING`	Required	Midaz onboarding service URL.
`MIDAZ_URL_TRANSACTION`	Required	Midaz transaction service URL.
`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.
`MIDAZ_FEE_MODE`	`auto`	The Midaz transaction API that the rail posts on. `auto` reads the ledger version and uses the API that applies Midaz fees when the ledger has it (Midaz 4.1 or later). `legacy` always uses the earlier API. `native` always uses the API that applies fees. Any other value stops the startup.
`MIDAZ_FEE_MODE_REFRESH`	`5m`	How often `auto` reads the ledger version again, as a Go duration. A failed read keeps the last mode.

There is no separate Access Manager address for Midaz. The rail mints its outbound Midaz token against the same Access Manager it validates inbound bearers with, PLUGIN_AUTH_HOST. See BYOC configuration essentials.

The ledger identity is not an environment variable. Four values tell the rail where it posts. All four come from the systemplane, in both deployment modes:

Value	Systemplane source
the Midaz organization	`tenancy/jd_integration_binding`, field `organizationId`
the Midaz ledger	`tenancy/jd_integration_binding`, field `ledgerId`
the posting asset, as its code (for example `BRL`)	`tenant_policy/midaz.asset_id`
the external clearing account, as its alias (for example `@external/BRL`)	`tenant_policy/midaz.external_id`

The two tenant_policy keys start empty. Until you write both of them, the rail refuses every posting, refund, and inbound credit with 409 PIX-0106. For the steps, see Setting up the rail.

The rail no longer reads MIDAZ_ORGANIZATION_ID, MIDAZ_LEDGER_ID, MIDAZ_ASSET_ID, and MIDAZ_EXTERNAL_ID. A value left in one of them gives one startup warning and has no effect.

Accounting routes

The rail books each Pix flow onto a pair of Midaz operation routes, one credit leg and one debit leg. There are eleven profiles. The route identifiers are not environment variables. They live in the systemplane keys tenant_policy/routing.<profile>.operation_credit_route and tenant_policy/routing.<profile>.operation_debit_route. There is no environment fallback. Each profile also has an optional transaction-route key, tenant_policy/routing.<profile>.transaction_route. The rail sends its value as the route of every posting of that profile. A Midaz ledger that validates routes refuses a posting without one. The rail then answers PIX-4011. When the key is empty, the posting carries no transaction route.

The TRANSACTION_ROUTE_* and OPERATION_ROUTE_* variables no longer exist. A leftover value gives one startup warning and has no effect. A missing leg of one of the six payment profiles refuses every payment flow with 409 PIX-0105. A missing MED or Pix Automático leg refuses only that flow. When one flow fails and the others work, look here first.

For the profiles, the exact key names, and how to write them, see Setting up the rail.

Jobs

Variable	Default / Required	Description
`JOBS_CRON`	`/10 * * * *`	Cron expression that sets how often the worker runs its periodic jobs.
`JOBS_RECONCILE_STUCK_THRESHOLD_SEC`	`80`	Age in seconds after which the rail reports a pending cash-out as stuck.

The daily window for transaction limits is not an environment variable. It lives in the systemplane keys tenant_policy/transaction_limits.daily_period_init and tenant_policy/transaction_limits.daily_period_end, in both deployment modes. Each key takes a clock hour from 0 to 23. The rail ignores the old TRANSACTION_LIMIT_DAILY_PERIOD_INIT and TRANSACTION_LIMIT_DAILY_PERIOD_END variables.

Pix Automático

JD’s Pix Automático has two optional steps that stay off until your institution turns them on. The debit itself always runs.

Variable	Default / Required	Description
`PIX_AUTOMATICO_BLOQUEAR_ENABLED`	`false`	Set `true` to accept the hold (bloqueio) that JD places on the payer’s balance before a Pix Automático debit.
`PIX_AUTOMATICO_ESTORNO_ENABLED`	`false`	Set `true` to accept the reversal (estorno) of a Pix Automático debit.

Turn each one on only after your institution agrees with JD to use that step. The rail reads both at startup, so a change needs a restart.

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

Courier ownership map

Some institutions share one ISPB between two core systems. JD Courier keeps an ownership map that tells which core holds each account. The rail asks that map in one case only. The payee of an outbound Pix names the paying participant’s own ISPB, and you declare that ISPB as shared.

Variable	Default / Required	Description
`COURIER_URL`	—	Base URL of the Courier process that runs the `admin` role. Only that role answers the ownership lookup.
`COURIER_CLIENT_ID`	—	The Courier client ID.
`COURIER_CLIENT_SECRET`	🔒 —	The Courier client secret.

Pix JD exchanges COURIER_CLIENT_ID and COURIER_CLIENT_SECRET with Access Manager for a token, and sends that token on each call to JD Courier. You declare a shared ISPB in the systemplane. The key tenant_policy/onus.shared_ispb_gate_enabled covers your default organization, and its default is false. An organization in the organization catalog uses its sharedIspbGate field. While the declaration is false, the rail does not ask the map. When the declaration is true, these refusals apply to an outbound Pix to an account at your own ISPB:

Condition	Response
The map gives the account to another core, or to no core	`422 PIX-0129`
`COURIER_URL` is empty, or the Courier does not give an answer	`503 PIX-0130`. You can retry
The Courier answers, but the rail cannot use the answer. A Courier process in a role other than `admin` gives this result	`502 PIX-0131`
The payee’s branch or account on record cannot form a lookup	`422 PIX-0132`

The rail refuses before it reserves a balance, so a refusal moves no money. Three systemplane keys set the time limits of the lookup. They apply in both deployment modes:

Systemplane key	Default	Range	What it limits
`tenant_policy/courier.lookup.timeout_ms`	`2000`	100–30000	one attempt, in milliseconds
`tenant_policy/courier.lookup.max_retries`	`1`	0–3	the retries after the first attempt
`tenant_policy/courier.lookup.total_budget_ms`	`4500`	100–60000	all attempts and the waits between them, in milliseconds

Claims on the Courier

See Connecting an engine. When the Courier is configured, the worker claims on the Courier the Pix Automático recurrences that the rail accepted as the payer’s institution. It sends up to 100 claims on each pass. When a claim fails, the worker sends it again on a later pass. The worker does not send again a claim that the Courier refuses with a conflict. The worker reads the Courier settings from the same place as the API. Before the Courier starts to receive your Pix, call the Courier ownership route (POST /v1/pix-automatico/courier-ownership). It claims the recurrences that already exist, and it declares the debit blocks and the schedules of the payments in progress. Call it again after the Courier starts to receive your Pix, to declare the legs that opened between the two calls. The route also claims again the recurrences that the Courier refused before. heldElsewhere in the answer lists the keys that the Courier refused with a conflict. An operator resolves each one.

Indirect participants

Only relevant if this deployment settles Pix on behalf of other institutions.

Variable	Default / Required	Description
`INDIRECTS_DELIVERY_ENCRYPTION_KEY`	🔒 Required to host indirect participants	AES-256 key that encrypts each indirect participant’s delivery secret at rest. Exactly 64 hex characters (32 bytes), from `openssl rand -hex 32`. No default.

Without this key, every indirect-participant registration is refused with 409 PIX-0107 — and refused before any write, so no plaintext secret is ever stored. An absent, blank, or malformed value all produce the same refusal: there is no default and no degradation to storing the secret in the clear. The 409 means “provision it”, not “try again”: its retryable sibling is 503 PIX-0123, which is what a key that could not be read answers.The rail starts without it. Startup logs a warning and the process comes up healthy, so the symptom arrives on the first registration, not on deploy. Read at startup, so a change needs a restart.See Hosting indirect participants for the onboarding this key unlocks.

Runtime configuration (systemplane)

This rail mounts the systemplane admin API on its main port. SYSTEMPLANE_ENABLED turns it on.

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

When you enable it, the service exposes an authenticated plane to read and write runtime configuration. See Systemplane for the API, namespaces, and required permissions. The rail reads several values only from that plane, in both deployment modes. A deployment that leaves them unset starts healthy and refuses money:

Systemplane key	What it carries	Unset
`tenancy/jd_integration_binding`	your own ISPB and your default Midaz organization and ledger, as a JSON string	`409 PIX-0092` on every money route
`tenant_policy/midaz.asset_id`, `tenant_policy/midaz.external_id`	the posting asset and the external clearing account	`409 PIX-0106` on every posting
`tenant_policy/routing.<profile>.operation_{credit,debit}_route`	the accounting route legs	`409 PIX-0105` on every payment flow when a leg of the six payment profiles is missing, and on that flow only for MED and Pix Automático. A devolução that you send posts on `out` while `refund_sent` is empty
`tenant_policy/routing.<profile>.transaction_route`	the optional transaction route of each profile	`PIX-4011` only when the ledger validates routes
`tenant_policy/transaction_limits.daily_period_{init,end}`	the daily limit window	limit accounting has no window
`plugin-br-pix-jd.indirects/enabled`	whether this tenant hosts indirect participants	indirect resolution stays off
`tenant_policy/organizations`	the catalog of additional organizations and ledgers this tenant posts for, as a JSON string	the rail posts only into the default organization and ledger. See Multi-organization and ledgers

With SYSTEMPLANE_ENABLED=false, the service does not mount the /system route group. Every configuration write then answers 404. A money path that cannot read its configuration answers the retryable 503 PIX-0051, not a provisioning refusal. The write permission is systemplane:write. Without it, the writes answer 403.

Setting up the rail shows each of these keys, the exact body of each write, and how to confirm it.

Permission declaration

At startup, the service can publish its permission declaration to the Access Manager.

Variable	Default / Required	Description
`IDP_DECLARATION_ENABLED`	`false`	Set `true` to publish the permission declaration at startup.
`IDP_HOST`	—	Absolute `http` or `https` URL of the Access Manager Identity service.
`IDP_M2M_CLIENT_ID`	—	The client ID that the service publishes with.
`IDP_M2M_CLIENT_SECRET`	🔒 —	The client secret that the service publishes with.

With IDP_DECLARATION_ENABLED=true, the service does not start when one of the other three variables is empty, when IDP_HOST is not valid, or when PLUGIN_AUTH_ENABLED is not true. When the Access Manager refuses the publication or does not answer, the service still starts.

Upgrade from an earlier version

Do the steps for each version that you pass on the way to the version that you install. To 1.2.1. The rail no longer reads MULTI_TENANT_ALLOW_INSECURE_HTTP. In multi-tenant mode with an http:// Tenant Manager, set ALLOW_INSECURE_TLS=true on the API and on the worker before the upgrade. Otherwise the service does not start. If your deployment already sets ALLOW_INSECURE_TLS=true, Pix JD 1.2.1 and later also accept http:// addresses for the connections in Connections without TLS, in every environment. To 1.2.0. On a self-hosted deployment, before the upgrade, make sure that the Pix roles in the Access Manager have the permission courier-ownership (action post), and give the application that COURIER_CLIENT_ID names the ownership:write permission in JD Courier. The Courier ownership route of this version needs courier-ownership, and it answers 403 without it. On a single-tenant deployment, also set the CRM_* variables, and with JD Courier the COURIER_* variables, on the worker. See Claims on the Courier. To 1.1.1. No step is required. The three payment-order signing variables are new and optional. Set them only if JD requires signed payment orders for your institution. See Payment-order signing. To 1.1.0. Before the upgrade, make sure that the Pix roles in the Access Manager have the permission entries-lookup (action get). The key lookup route of this version needs it, and it answers 403 without it. To 1.0.0, from the earlier Pix plugin.

Before the upgrade, write tenant_policy/midaz.asset_id and tenant_policy/midaz.external_id. Use the values from MIDAZ_ASSET_ID and MIDAZ_EXTERNAL_ID. Without them, the upgraded rail refuses every posting with 409 PIX-0106.
Read tenancy/jd_integration_binding back. Make sure that organizationId and ledgerId name the organization and the ledger that this deployment posts into. The rail reads them on every call.
Before you upgrade, set MIDAZ_FEE_MODE=legacy on the API and on the worker. The default is auto. Change the value to auto only after both of these are true:
- No pod of the earlier release serves any tenant.
- You reviewed your fee packages. A fee package with no transaction route can charge a fee on every Pix flow.
Add a refundSent entry to the organization catalog only after no pod of the earlier release serves the tenant.
With event streaming on, the service does not start while its outbox holds undelivered events in an earlier event format. Deliver those events with the build that wrote them before you upgrade.
After the upgrade, remove the four MIDAZ_* identity variables from your environment.

Health and readiness

The rail exposes GET /health (liveness) and GET /readyz (readiness) on the main port, plus /metrics and /version. See Health and readiness for the response shape.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Environment variables

Server and port

Connections without TLS

JD integration

Payment-order signing

Dynamic QR code hosting

Midaz ledger connection

Accounting routes

Jobs

Pix Automático

Notifications

CRM

Courier ownership map

Claims on the Courier

Indirect participants

Runtime configuration (systemplane)

Permission declaration

Upgrade from an earlier version

Health and readiness

​Server and port

​Connections without TLS

​JD integration

​Payment-order signing

​Dynamic QR code hosting

​Midaz ledger connection

​Accounting routes

​Jobs

​Pix Automático

​Notifications

​CRM

​Courier ownership map

​Claims on the Courier

​Indirect participants

​Runtime configuration (systemplane)

​Permission declaration

​Upgrade from an earlier version

​Health and readiness

Server and port

Connections without TLS

JD integration

Payment-order signing

Dynamic QR code hosting

Midaz ledger connection

Accounting routes

Jobs

Pix Automático

Notifications

CRM

Courier ownership map

Claims on the Courier

Indirect participants

Runtime configuration (systemplane)

Permission declaration

Upgrade from an earlier version

Health and readiness