Environment variables

DevOps sets these variables at deploy time. A change requires a service restart. Runtime and business settings live in Configuration. In the tables below, the Default / Required column shows the default value. A bold qualifier (for example Required, Required in production, Required if enabled) marks a variable you must set. — means no default.

Infrastructure configuration

This section is for DevOps teams. DevOps sets these variables at deploy time. A change takes effect only after a service restart.

Application

Variable	Default / Required	Description
`ENV_NAME`	`development`	Environment (`development`, `staging`, `production`)
`DEPLOYMENT_MODE`	`byoc`	`byoc` (Bring Your Own Cloud) or `saas`. With `saas`, the plugin refuses to start unless PostgreSQL, Redis, MongoDB, RabbitMQ, and the streaming broker use TLS.
`SERVER_ADDRESS`	`:8080`	HTTP server address and port
`HTTP_BODY_LIMIT_BYTES`	`1048576`	Maximum HTTP request body size in bytes
`ALLOW_PRIVATE_UPSTREAMS`	`false`	⚠️ Allow outbound adapters (CRM, Fees, JD, Midaz) to resolve to RFC1918/loopback IPs. Default `false` is fail-closed: production blocks DNS pivoting into private space. Enable in dev or in-cluster BYOC where upstreams legitimately live on private IPs. Refused in production. Cloud metadata endpoints stay blocked regardless of this flag.
`REQUIRE_UPSTREAM_HTTPS`	`false`	Refuse plain `http://` CRM and Fees Engine base URLs. Production already refuses them; use this in staging, homologation, and BYOC deployments that carry real client data.

TLS

Variable	Default / Required	Description
`SERVER_TLS_CERT_FILE`	—	Path to TLS certificate file. Must be set together with `SERVER_TLS_KEY_FILE`.
`SERVER_TLS_KEY_FILE`	—	Path to TLS private key file. Must be set together with `SERVER_TLS_CERT_FILE`.
`TLS_TERMINATED_UPSTREAM`	`false`	Set to `true` when TLS is terminated by a load balancer or reverse proxy.

Proxy headers

Set these when the service runs behind a load balancer or reverse proxy. They let the service read the real client IP for rate limiting and audit logs.

Variable	Default / Required	Description
`SERVER_PROXY_HEADER`	—	HTTP header carrying the real client IP (e.g. `X-Forwarded-For`, `X-Real-IP`). Empty disables proxy header parsing.
`SERVER_TRUSTED_PROXIES`	Required if proxy header set	Comma-separated list of trusted proxy IPs/CIDRs. Required when `SERVER_PROXY_HEADER` is set to prevent IP spoofing.

Authentication

This plugin delegates authorization to Access Manager. Configure the connection with the variables below.

Variable	Default / Required	Description
`PLUGIN_AUTH_ENABLED`	`false` · `true` required in production	Enable authorization via Access Manager. The service refuses to start in production with `false`.
`PLUGIN_AUTH_ADDRESS`	Required if enabled	URL of the Access Manager auth service. Must use HTTPS in production. CRM and Fees Engine M2M tokens also come from this address.

When PLUGIN_AUTH_ENABLED=true, PLUGIN_AUTH_ADDRESS must use HTTPS in production environments. The service rejects an HTTP address at startup.

Organization scope

Variable	Default / Required	Description
`ORGANIZATION_ID`	Required with JD polling	Midaz organization UUID injected into background-worker context (TED IN poller, reconciliation). Required when `JD_POLLING_ENABLED=true`. HTTP requests always carry the organization in the `X-Organization-Id` header instead.
`ORGANIZATION_IDS`	Required in production	Comma-separated list of Midaz organization UUIDs in the licensing scope. The license gateway validates `LICENSE_KEY` against these at startup. Also referenced under License.

# Organization injected into background workers (required when JD polling is enabled)
ORGANIZATION_ID=<your-midaz-organization-uuid>
# Licensing scope validated against LICENSE_KEY in production
ORGANIZATION_IDS=<your-midaz-organization-uuid>

PostgreSQL

Variable	Default / Required	Description
`POSTGRES_HOST`	`localhost` · Required	Primary PostgreSQL host.
`POSTGRES_PORT`	`5432`	Primary PostgreSQL port.
`POSTGRES_USER`	`plugin-br-bank-transfer` · Required	Database user.
`POSTGRES_PASSWORD`	Required in production	Database password.
`POSTGRES_DB`	`plugin-br-bank-transfer` · Required	Database name.
`POSTGRES_SSLMODE`	`require`	SSL mode. In production, must be `require`, `verify-ca`, or `verify-full`.
`POSTGRES_MAX_OPEN_CONNS`	`25`	Maximum open connections.
`POSTGRES_MAX_IDLE_CONNS`	`5`	Maximum idle connections.
`POSTGRES_CONN_MAX_LIFETIME_MINS`	`30`	Connection max lifetime in minutes.
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	`5`	Connection max idle time in minutes.
`POSTGRES_CONNECT_TIMEOUT_SEC`	`10`	Connection timeout in seconds.

PostgreSQL replica

Configure a read replica for query offloading. All fields fall back to primary values when unset.

Variable	Default / Required	Description
`POSTGRES_REPLICA_HOST`	—	Replica host. Unset = no replica.
`POSTGRES_REPLICA_PORT`	—	Replica port.
`POSTGRES_REPLICA_USER`	—	Replica user.
`POSTGRES_REPLICA_PASSWORD`	—	Replica password.
`POSTGRES_REPLICA_DB`	—	Replica database name.
`POSTGRES_REPLICA_SSLMODE`	—	Replica SSL mode. Same production rule as `POSTGRES_SSLMODE`.

MongoDB

The service uses MongoDB to persist transfer audit events. It does not start without a valid MongoDB connection.

Variable	Default / Required	Description
`MONGO_ENABLED`	`true`	Enable MongoDB connection. Must be `true`.
`MONGO_URI`	Required	MongoDB connection string (e.g. `mongodb://user:pass@host:27017`). In production, must include credentials and TLS (`tls=true` or `mongodb+srv`).
`MONGO_DATABASE`	Required	MongoDB database name.
`MONGO_MAX_POOL_SIZE`	`25`	Maximum connection pool size.
`MONGO_SERVER_SELECTION_TIMEOUT_MS`	`3000`	Server selection timeout in milliseconds.
`MONGO_HEARTBEAT_INTERVAL_MS`	`10000`	Heartbeat interval in milliseconds.
`MONGO_TLS_CA_CERT`	—	Base64-encoded CA certificate for MongoDB TLS. Use when MongoDB requires TLS with a custom CA (e.g. Atlas, private instances with self-signed certs).

Redis

Variable	Default / Required	Description
`REDIS_HOST`	`localhost:6379` · Required	Redis host and port.
`REDIS_MASTER_NAME`	—	Redis Sentinel master name (if using Sentinel).
`REDIS_PASSWORD`	—	Redis password (if auth enabled).
`REDIS_DB`	`0`	Redis database number.
`REDIS_PROTOCOL`	`3`	Redis protocol version (2 or 3).
`REDIS_TLS`	`false`	Enable TLS for Redis connections.
`REDIS_CA_CERT`	—	CA certificate for Redis TLS.
`REDIS_POOL_SIZE`	`10`	Connection pool size.
`REDIS_MIN_IDLE_CONNS`	`2`	Minimum idle connections.
`REDIS_READ_TIMEOUT_MS`	`3000`	Read timeout in milliseconds.
`REDIS_WRITE_TIMEOUT_MS`	`3000`	Write timeout in milliseconds.
`REDIS_DIAL_TIMEOUT_MS`	`5000`	Dial timeout in milliseconds.

Redis is a mandatory dependency. It caches idempotency keys and detects duplicates. If Redis is unavailable at startup, or becomes unreachable at runtime, the service reports as DOWN to the readiness probe. It then stops accepting requests.

JD SPB connection

The plugin validates the JD variables only when JD_BASE_URL is set.

Variable	Default / Required	Description
`JD_BASE_URL`	—	JD SPB API base URL.
`JD_SOAP_PATH`	`/soap`	JD SOAP endpoint path.
`JD_LEGACY_CODE`	Required	JD legacy system code (max 10 chars).
`JD_USER_CODE`	Required	JD user code (max 10 chars).
`JD_PASSWORD`	Required	JD password.
`JD_PRIVATE_KEY_PEM`	Required for `local_pem`	RSA private key PEM content (at least 3072 bits) for the XML signature, which uses PKCS#1 v1.5 with SHA-256.
`JD_PRIVATE_KEY_PEM_FILE`	—	Path to a file containing the RSA private key PEM. Alternative to inlining the key in `JD_PRIVATE_KEY_PEM`; read at startup.
`JD_PUBLIC_KEY_PEM`	Required for `external_provided`	Public key PEM that verifies the signatures your system provides. Required in `external_provided` mode while `jdspb.validate_external_signature` is on (default).
`JD_PRIVATE_KEY_KEYINFO`	Required when signing	Identifier of the signing key, in hex: a 40-character certificate thumbprint or a 64-character key identifier.
`JD_CERT_PEM`	—	Optional PEM-encoded X.509 certificate paired with the JD signing key. Used only by the cert-expiry metrics gauge, not the signing path; a malformed PEM is a startup error.
`JD_SIGNING_MODE`	`local_pem`	SOAP signing mode. `local_pem` signs locally with `JD_PRIVATE_KEY_PEM`. `external_provided` takes the signature your system sends to the process step. The plugin refuses `disabled` at startup while `JD_BASE_URL` is set.
`JD_EXTERNAL_SIGNER_URL`	—	In `external_provided` mode, the signing service that the plugin calls when a process request carries no signature.
`JD_EXTERNAL_SIGNER_AUTH_TOKEN`	—	Bearer token sent in the `Authorization` header for external-signer calls.
`JD_EXTERNAL_SIGNER_TIMEOUT_MS`	`5000`	Timeout (in milliseconds) for external-signer calls.
`JD_ALLOW_PRIVATE_NETWORK`	`false`	Allow the JD adapter to reach a private network address. Cloud metadata endpoints stay blocked.
`JD_SANDBOX_MODE`	`false`	Enable JD sandbox mode. Allowed only when `ENV_NAME` is `local`, `development`, or `test`.

JD polling

Variable	Default / Required	Description
`JD_POLLING_ENABLED`	`false`	Enable TED IN polling worker.
`JD_POLL_INTERVAL_SECONDS`	`60`	How often (in seconds) the plugin polls for incoming TEDs.
`JD_POLL_CYCLE_TIMEOUT_SECONDS`	`0`	Deadline for one poll cycle, 30 to 3600 seconds. `0` derives it from the interval.
`RECONCILIATION_CYCLE_TIMEOUT_SECONDS`	`0`	Deadline for one reconciliation sweep, 30 to 3600 seconds. `0` derives it from the worker interval.
`DEVOLUTION_SCAN_CYCLE_TIMEOUT_SECONDS`	`0`	Deadline for one devolution scan, 30 to 3600 seconds. `0` derives it from the scan interval.

JD_POLLING_ENABLED defaults to false for safer deployments. Set ORGANIZATION_ID before you enable it. Background workers inject that value into the context for downstream CRM and Midaz calls.

External services (Midaz)

Variable	Default / Required	Description
`MIDAZ_BASE_URL`	Required	Midaz base service URL.
`MIDAZ_TRANSACTION_URL`	Required	Midaz transaction service URL.
`MIDAZ_TIMEOUT_MS`	`3000`	Midaz request timeout in milliseconds.
`MIDAZ_MAX_RETRIES`	`3`	Retry attempts on Midaz failure.
`MIDAZ_AUTH_ENABLED`	`false`	Enable M2M authentication for Midaz.
`MIDAZ_AUTH_ADDRESS`	`PLUGIN_AUTH_ADDRESS`	Auth service URL for Midaz M2M tokens.
`MIDAZ_CLIENT_ID`	Required if enabled	OAuth client ID for Midaz M2M.
`MIDAZ_CLIENT_SECRET`	Required if enabled	OAuth client secret for Midaz M2M.
`MIDAZ_FEE_MODE`	`auto`	Who charges the fee of each transfer. `legacy`: plugin-fees, set up by the `FEES_*` variables below, with postings on the Midaz `/v1` API. `native`: the Midaz Fees Engine, from the fee packages of the ledger, with postings on `/v2`. `auto` reads the Midaz version, and uses `native` on Midaz 4.1.0 or later and `legacy` on an earlier version or when the first read fails. Bank Transfer does not start with any other value.
`MIDAZ_FEE_MODE_REFRESH`	`5m`	How often `auto` reads the Midaz version again, as a Go duration. The new read runs on the first transfer after this interval, and a failed read keeps the current mode. Bank Transfer does not start with a value of zero or less.

Bank Transfer asks Midaz to create a transaction metadata index for its correlation reads. This call needs the Midaz settings post permission, in both fee modes.

Under the default auto, Bank Transfer moves to native by itself as soon as it reads Midaz 4.1.0 or later. If your fee packages still live in plugin-fees, Midaz finds no package, and new transfers carry no fee. Set MIDAZ_FEE_MODE=legacy before you upgrade Midaz, then follow Migrate Bank Transfer fees to Midaz.

External services (CRM)

Variable	Default / Required	Description
`CRM_BASE_URL`	Required	CRM service URL. Must use HTTPS in production.
`CRM_TIMEOUT_MS`	`2000`	CRM request timeout in milliseconds.
`CRM_MAX_RETRIES`	`2`	Retry attempts on CRM failure.
`CRM_AUTH_ENABLED`	`false`	Enable M2M authentication for CRM.
`CRM_CLIENT_ID`	Required if enabled	OAuth client ID for CRM M2M.
`CRM_CLIENT_SECRET`	Required if enabled	OAuth client secret for CRM M2M.

External services (Fees)

These variables configure plugin-fees, and they apply only when the fee mode is legacy. BTF_FEE_ENABLED turns plugin-fees on. When false (default), the plugin builds no plugin-fees adapter, and every legacy transfer proceeds with fee 0 and no HTTP call. The other FEES_* variables take effect only when BTF_FEE_ENABLED=true. In native mode, BTF_FEE_ENABLED does not turn fees on or off: the Midaz fee package of the ledger does.

Variable	Default / Required	Description
`BTF_FEE_ENABLED`	`false`	Turns the plugin-fees integration on, in `legacy` mode only. When `false`, no plugin-fees adapter is built and every `legacy` transfer runs with fee 0 without HTTP calls. Set it to `true` to charge fees through plugin-fees. In `native` mode, enable or disable the Midaz fee package instead.
`FEES_BASE_URL`	Required if enabled	plugin-fees service URL. Must use HTTPS in production.
`FEES_TIMEOUT_MS`	`2000`	Fee request timeout in milliseconds.
`FEES_MAX_RETRIES`	`2`	Retry attempts on fee service failure.
`FEES_AUTH_ENABLED`	`false`	Enable M2M authentication for Fees.
`FEES_CLIENT_ID`	Required if enabled	OAuth client ID for Fees M2M.
`FEES_CLIENT_SECRET`	Required if enabled	OAuth client secret for Fees M2M.

RabbitMQ

When streaming is enabled, the plugin can fan out transfer lifecycle events to RabbitMQ for downstream consumers.

Variable	Default / Required	Description
`RABBITMQ_ENABLED`	`false`	Add RabbitMQ as a transfer lifecycle fan-out target. Publishing requires `STREAMING_ENABLED=true`.
`RABBITMQ_URL`	Required if enabled	AMQP connection URL. `amqp://` is allowed only when `ENV_NAME` is `development`, `dev`, `test`, `testing`, or `local`, or for a loopback host.
`RABBITMQ_HEALTH_CHECK_URL`	—	HTTP(S) URL of the RabbitMQ management health endpoint. Hostname must match `RABBITMQ_URL`; must use `https://` in production.
`RABBITMQ_EXCHANGE`	`bank_transfer.lifecycle`	Exchange name for lifecycle events.
`RABBITMQ_EVENT_SIGNING_SECRET`	—	HMAC secret for signing published events. Falls back to `WEBHOOK_BROKER_EVENT_SIGNING_SECRET`, then to `WEBHOOK_SIGNING_SECRET`. The secret in effect must have at least 32 characters.

Streaming outbox

The streaming subsystem publishes transfer events to the single application topic lerian.streaming.plugin-br-bank-transfer on a Redpanda/Kafka broker through a transactional outbox. You must enable it for outbound webhook delivery (WEBHOOK_ENABLED=true requires STREAMING_ENABLED=true). While streaming is off, the plugin discards events: turning it on later publishes only new events.

Variable	Default / Required	Description
`STREAMING_ENABLED`	`false`	Enable the streaming outbox subsystem. Required for webhook delivery.
`STREAMING_BROKERS`	Required if enabled	Comma-separated list of Kafka/Redpanda broker addresses.
`STREAMING_CLIENT_ID`	—	Client ID presented to the broker.
`STREAMING_CLOUDEVENTS_SOURCE`	`plugin-br-bank-transfer`	Optional override for the CloudEvents `source`. Leave it unset to use `plugin-br-bank-transfer`; if set, it must match that value exactly, even while streaming is disabled.
`STREAMING_OUTBOX_DISPATCH_INTERVAL_SECONDS`	`30`	Interval (in seconds) between outbox dispatch cycles. Must be > 0.
`STREAMING_CB_FAILURE_RATIO`	`0.5`	Circuit breaker failure ratio that trips the breaker (must be > 0 and ≤ 1).
`STREAMING_CB_MIN_REQUESTS`	`10`	Minimum requests in a window before the circuit breaker can trip.
`STREAMING_CB_TIMEOUT_S`	`30`	Circuit breaker recovery timeout in seconds.
`STREAMING_CLOSE_TIMEOUT_S`	`30`	Graceful shutdown timeout (in seconds) for the streaming producer.
`STREAMING_TLS_ENABLED`	`false`	Use TLS to the broker. Must be `true` when `DEPLOYMENT_MODE=saas`.
`STREAMING_TLS_CA_CERT`	—	CA certificate for the broker TLS connection.
`STREAMING_SASL_MECHANISM`, `STREAMING_SASL_USERNAME`, `STREAMING_SASL_PASSWORD`	—	SASL authentication to the broker.
`STREAMING_SASL_ALLOW_PLAINTEXT`	`false`	Allow SASL without TLS.

Webhook delivery

Outbound webhook delivery requires both RabbitMQ and the streaming outbox. The webhook worker consumes events from a RabbitMQ queue and delivers them to subscriber endpoints.

Variable	Default / Required	Description
`WEBHOOK_ENABLED`	`false`	Enable outbound webhook delivery. Requires `RABBITMQ_ENABLED=true` and `STREAMING_ENABLED=true`.
`WEBHOOK_SIGNING_SECRET`	—	Last fallback for the broker-event secret. It does not sign deliveries: each webhook registration signs with its own `signingSecret`.
`WEBHOOK_BROKER_EVENT_SIGNING_SECRET`	Required in production if enabled	HMAC secret for verifying broker events. Falls back to `WEBHOOK_SIGNING_SECRET`.
`WEBHOOK_QUEUE_NAME`	`transfer.webhook.delivery`	RabbitMQ queue name for webhook events.
`WEBHOOK_DLQ_NAME`	`transfer.webhook.dlq`	Dead-letter queue for failed webhook deliveries.
`WEBHOOK_DLX_EXCHANGE_NAME`	—	Dead-letter exchange name. When empty, the worker derives `<WEBHOOK_DLQ_NAME>.exchange`. Override to centralize the DLX across plugins.
`WEBHOOK_DLQ_MESSAGE_TTL_MS`	`0`	`x-message-ttl` on the DLQ in milliseconds. `0` defers to the library default (7 days). Topology changes require deleting the existing DLQ before redeploy.
`WEBHOOK_DLQ_MAX_LENGTH`	`0`	Maximum DLQ message count. `0` defers to the library default (10000).
`WEBHOOK_PREFETCH_COUNT`	`20`	RabbitMQ prefetch count.
`WEBHOOK_DELIVERY_CONCURRENCY`	`8`	Maximum concurrent webhook deliveries per worker.

Telemetry (OpenTelemetry)

Variable	Default / Required	Description
`ENABLE_TELEMETRY`	`false`	Enable OpenTelemetry tracing and metrics.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`localhost:4317`	OTel collector gRPC endpoint.
`OTEL_TRACES_SAMPLER_ARG`	—	Trace sampling ratio. A value in (0,1] applies as set. Unset, or a value of 0 or below, uses `0.1` in production and `1.0` elsewhere. A value above 1 counts as `1.0`.
`BTF_METRICS_PROMETHEUS_ENABLED`	`false`	Expose a dedicated Prometheus scrape endpoint for `btf.*` metrics. When `true`, the listener at `BTF_METRICS_PROMETHEUS_ADDRESS` is started.
`BTF_METRICS_PROMETHEUS_ADDRESS`	`127.0.0.1:9090`	Listen address for the Prometheus `/metrics` endpoint. Default binds to loopback so a misconfigured pod does not expose unauthenticated metrics to the cluster network. Override (e.g. `0.0.0.0:9090`) only behind a NetworkPolicy or sidecar.

License

Variable	Default / Required	Description
`LICENSE_KEY`	Required in production	License key. Required in production environments.
`LICENSE_SERVICE_ADDRESS`	—	License validation service URL. In production, must use HTTPS and a public host.
`ORGANIZATION_IDS`	Required in production	Same variable as in Organization scope. Comma-separated list of Midaz organization UUIDs in the licensing scope; the license gateway validates `LICENSE_KEY` against these at startup.

Encryption

Field-level encryption for sensitive data at rest. Each key must be a hex-encoded 32-byte AES-256 key (64 hex characters). Both keys are required in production. Outside production, an empty key disables encryption for that field.

Variable	Default / Required	Description
`JD_INCOMING_RAW_XML_ENCRYPTION_KEY`	—	AES-256 key for encrypting incoming JD XML payloads. Use a hex-encoded 32-byte key. Keep it stable across upgrades: a changed key makes the records that the previous key encrypted unreadable.
`RECIPIENT_DETAILS_ENCRYPTION_KEY`	—	AES-256 key for encrypting recipient details at rest. Use a hex-encoded 32-byte key. Keep it stable across upgrades: a changed key makes the records that the previous key encrypted unreadable.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Environment variables

Infrastructure configuration

Application

TLS

Proxy headers

Authentication

Organization scope

PostgreSQL

PostgreSQL replica

MongoDB

Redis

JD SPB connection

JD polling

External services (Midaz)

External services (CRM)

External services (Fees)

RabbitMQ

Streaming outbox

Webhook delivery

Telemetry (OpenTelemetry)

License

Encryption

​Infrastructure configuration

​Application

​TLS

​Proxy headers

​Authentication

​Organization scope

​PostgreSQL

​PostgreSQL replica

​MongoDB

​Redis

​JD SPB connection

​JD polling

​External services (Midaz)

​External services (CRM)

​External services (Fees)

​RabbitMQ

​Streaming outbox

​Webhook delivery

​Telemetry (OpenTelemetry)

​License

​Encryption

Infrastructure configuration

Application

TLS

Proxy headers

Authentication

Organization scope

PostgreSQL

PostgreSQL replica

MongoDB

Redis

JD SPB connection

JD polling

External services (Midaz)

External services (CRM)

External services (Fees)

RabbitMQ

Streaming outbox

Webhook delivery

Telemetry (OpenTelemetry)

License

Encryption