Variables de entorno

Pix Indirecto vía BTG llega al arreglo Pix a través de BTG como participante directo. Se distribuye como varios componentes: una API, más los workers de conciliación, de programación y de webhooks entrantes y salientes. DevOps define las variables de entorno de cada componente en el momento del despliegue. Para cambiar una variable, reinicias ese componente. Esta página cubre las variables distintivas de este riel. Para los ajustes de streaming, telemetría y autenticación compartidos por todos los servicios Go de Lerian, consulta Aspectos esenciales de configuración BYOC.

En las tablas siguientes, la columna Predeterminado / Obligatorio muestra el valor predeterminado. Un calificador en negrita (por ejemplo Obligatorio) marca las variables que debes definir. — significa que no hay valor predeterminado. 🔒 marca un secreto. Inyecta cada secreto en el momento del despliegue desde tu almacén de secretos. Nunca incluyas un secreto en un commit. Esta página solo lista nombres de variables y su comportamiento. No imprime valores de secretos.

Este riel no monta la API de administración de systemplane. Sus variables de datastore usan el prefijo DB_* en lugar de la forma compartida POSTGRES_*. Consulta Datastores más abajo.

Componentes y puertos

El componente de API escucha en SERVER_ADDRESS (por ejemplo :4014). Los workers de conciliación, de programación y de webhooks enlazan cada uno un WORKER_PORT para sus sondas de salud. Consulta Puertos de red predeterminados.

Integración con BTG y mTLS

Estas variables guardan las credenciales de BTG y la configuración de TLS mutuo en ambas direcciones: el certificado de cliente que el plugin presenta a BTG y la verificación del certificado que BTG presenta en los webhooks entrantes.

Variable	Predeterminado / Obligatorio	Descripción
`BTG_BASE_URL`	Obligatorio	URL base de la API de BTG.
`BTG_CERTIFICATE_URL`	Obligatorio cuando `MTLS_ENABLED=true`	URL del certificado público de BTG. La API lo compara con el certificado que BTG presenta en los webhooks entrantes.
`BTG_CLIENT_ID`	Obligatorio	Client ID de OAuth para la API de BTG.
`BTG_CLIENT_SECRET`	🔒 Obligatorio	Client secret de OAuth para la API de BTG.
`BTG_WEBHOOK_SECRET`	🔒 Obligatorio cuando la validación está habilitada	Secreto usado para validar las firmas de los webhooks entrantes de BTG.
`BTG_WEBHOOK_VALIDATION_ENABLED`	`false`	Verifica las firmas de los webhooks de BTG. Defínelo en `true` en producción.
`MTLS_ENABLED`	`false`	Verifica el certificado que BTG presenta en los webhooks entrantes. Habilítalo en producción.
`MTLS_CERTIFICATE_HEADER`	`X-Client-Cert`	Header en el que tu ingress reenvía el certificado que presentó BTG. Tu ingress debe definir este header a partir del handshake TLS y sobrescribir cualquier valor que envíe quien llama.
`MTLS_CERTIFICATE_TTL`	`24h`	Cuánto tiempo se guarda en cache el certificado obtenido de BTG antes de renovarlo.
`MTLS_HTTP_TIMEOUT`	`10s`	Timeout de la llamada HTTP que obtiene el certificado.
`BTG_OUTBOUND_MTLS_ENABLED`	`false`	Presenta un certificado de cliente en las llamadas a BTG.
`CLIENT_TLS_CERT_FILE` · `CLIENT_TLS_KEY_FILE`	🔒 Obligatorio cuando el mTLS saliente está habilitado	Rutas del certificado de cliente y de la clave privada en PEM.
`CLIENT_TLS_CA_FILE`	—	Paquete PEM opcional que verifica el certificado del servidor de BTG.

Datastores

Este riel usa el prefijo DB_* para los datastores, no la forma compartida POSTGRES_*. Se conecta a un PostgreSQL primario, a una réplica de lectura aparte, a MongoDB y a Redis.

Variable	Predeterminado / Obligatorio	Descripción
`DB_HOST` · `DB_PORT`	Obligatorio	Host y puerto del PostgreSQL primario.
`DB_USER` · `DB_PASSWORD`	🔒 Obligatorio	Credenciales del PostgreSQL primario.
`DB_NAME`	Obligatorio	Nombre de la base de datos primaria.
`DB_SSL_MODE`	—	Modo TLS de libpq. Defínelo de forma explícita. Usa `require` o uno más estricto en producción.
`DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD`	🔒 —	Conexión opcional a la réplica de lectura (misma forma que la primaria).
`MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME`	🔒 Obligatorio	Conexión a MongoDB. `MONGO_URI` define el esquema de conexión (`mongodb` o `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD` y `MONGO_NAME` aportan el host, las credenciales y la base de datos. Todas se combinan en una sola cadena de conexión. No son alternativas entre URI y valores discretos. La contraseña es un secreto.
`MONGO_TLS`	`false`	Habilita TLS hacia MongoDB.
`REDIS_HOST` · `REDIS_PASSWORD`	🔒 —	Endpoint `host:port` de Redis/Valkey y contraseña de autenticación.
`REDIS_TLS` · `REDIS_CA_CERT`	`false` · —	Habilita TLS hacia Redis y entrega una CA en PEM codificada en base64.
`DEPLOYMENT_MODE`	`local`	`local`, `byoc` o `saas`. Con `saas`, un componente no arranca si un datastore que usa no tiene TLS. PostgreSQL exige `DB_SSL_MODE` igual a `require`, `verify-ca` o `verify-full`. Redis exige `REDIS_TLS=true`. MongoDB exige `MONGO_TLS=true`.

Midaz, CRM y Fees

Variable	Predeterminado / Obligatorio	Descripción
`MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL`	Obligatorio	URL de los servicios de onboarding y de transacciones de Midaz.
`MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID`	Obligatorio	UUID de la organización y del ledger de Midaz para los registros Pix.
`MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET`	🔒 Obligatorio	Credenciales OAuth para Midaz M2M.
`MIDAZ_COUNTERPARTY_ACCOUNT_ALIAS`	`@external/BRL`	Cuenta de Midaz que los registros de cash-out Pix acreditan.
`MIDAZ_CASHOUT_TRANSACTION_ROUTE` · `MIDAZ_CASHOUT_SOURCE_OPERATION_ROUTE` · `MIDAZ_CASHOUT_DESTINATION_OPERATION_ROUTE`	—	Ruta de transacción, ruta de operación de débito y ruta de operación de crédito de Midaz para los registros de cash-out Pix. Si un valor está vacío, el plugin no envía ruta para él.
`MIDAZ_CASHOUT_REFUND_TRANSACTION_ROUTE`	—	Ruta de transacción de Midaz para una devolución que envía un array `operations`, o que devuelve el monto total de un cash-in con comisiones. Si está vacía, el plugin usa `MIDAZ_CASHOUT_TRANSACTION_ROUTE`.
`PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET`	🔒 Obligatorio	URL del servicio CRM y credenciales OAuth.
`FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET`	🔒 Obligatorio cuando `CASHIN_FEE_CALCULATION_TYPE=segment`	URL del servicio Fees Engine y credenciales OAuth.
`FEE_SERVICE_TIMEOUT`	`5000`	Timeout de las solicitudes de comisiones, en milisegundos.
`CASHIN_FEE_CALCULATION_TYPE`	—	Defínelo en `segment` para calcular las comisiones de cash-in según el segmento de la cuenta. Déjalo vacío para no cobrar comisiones de cash-in.

Webhooks internos y programación

La API y los workers intercambian eventos por un canal interno de webhooks. También ejecutan flujos Pix recurrentes y programados.

Variable	Predeterminado / Obligatorio	Descripción
`INTERNAL_WEBHOOK_SECRET`	🔒 Obligatorio	Secreto HMAC compartido entre la API y los workers para firmar los webhooks internos. Al menos 32 caracteres.
`INTERNAL_WEBHOOK_VALIDATION_ENABLED`	`false`	Verifica las firmas de los webhooks internos. Defínelo en `true` en producción.
`INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE`	`300`	Desfase de reloj permitido, en segundos, al validar las marcas de tiempo de los webhooks internos.
`WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES`	`10485760` (10 MB) · `3`	Límite del payload de los webhooks entrantes y tope de reintentos.
`RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS`	`1` · `720h` · `150ms` · `3`	Ajustes de programación y de manejo de respuestas del Pix recurrente.
`SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS`	`6` · `2` · `180` · `60`	Ventana de ejecución y límites de los pagos programados.
`RECONCILIATION_INTERNAL_CIDR`	—	Rango de red de tu servicio interno de conciliación.

Ámbito de Pix y del ledger

Variable	Predeterminado / Obligatorio	Descripción
`PIX_ISPB`	Obligatorio	El ISPB (código de participante) con el que opera este despliegue: 8 caracteres, dígitos o letras mayúsculas.
`ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END`	—	Ventana diaria (`HH:MM`, hora de São Paulo) durante la cual la API bloquea la creación, la actualización y la eliminación de claves Pix.
`ORGANIZATION_IDS`	Obligatorio en producción	UUID de organizaciones de Midaz, separados por comas, dentro del ámbito de licenciamiento.
`GOOGLE_APPLICATION_CREDENTIALS`	🔒 —	Credenciales de cuenta de servicio de Google (una ruta de archivo o el contenido JSON) para la autenticación IAM de GCP en Redis.

Access Manager

Estas variables se aplican al componente de la API. Para PLUGIN_AUTH_ENABLED y PLUGIN_AUTH_ADDRESS, consulta Aspectos esenciales de configuración BYOC.

Variable	Predeterminado / Obligatorio	Descripción
`TRUSTED_PROXIES`	—	Rangos CIDR, separados por comas, de los proxies que se conectan directamente a la API. La API resuelve la dirección de quien llama a través de ellos y la envía al Access Manager para la lista de IP permitidas. Si la variable no está definida, la API no envía la dirección de quien llama.
`DECLARATION_ENABLED`	`false`	Define `true` para publicar la declaración de permisos del plugin en el Access Manager al iniciar.
`PLUGIN_IDENTITY_HOST`	—	URL absoluta `http` o `https` del servicio Identity del Access Manager.
`M2M_CLIENT_ID` · `M2M_CLIENT_SECRET`	🔒 —	Las credenciales de cliente con las que la API publica la declaración.

Con DECLARATION_ENABLED=true, la API no inicia cuando PLUGIN_IDENTITY_HOST, M2M_CLIENT_ID o M2M_CLIENT_SECRET está vacío. Tampoco inicia cuando PLUGIN_AUTH_ENABLED no es true, o cuando PLUGIN_IDENTITY_HOST o PLUGIN_AUTH_ADDRESS no es una URL absoluta http o https.

Verificación de fraude en Pix entrante

Estas variables configuran la verificación de fraude en Pix entrante en el componente de la API. Cuando ANTIFRAUD_HOOK_ENABLED es false, la API ignora las demás variables de esta tabla.

Variable	Predeterminado / Obligatorio	Descripción
`ANTIFRAUD_HOOK_ENABLED`	`false`	Define `true` para consultar tu endpoint de decisión antes de que la API acepte un Pix entrante o una devolución entrante.
`ANTIFRAUD_HOOK_URL`	Obligatorio cuando está activada	URL de tu endpoint de decisión. Debe usar `https`, a menos que `ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK=true`.
`ANTIFRAUD_HOOK_TIMEOUT_MS`	`500`	Cuánto tiempo espera la API una decisión, en milisegundos. El mínimo es `100`.
`ANTIFRAUD_HOOK_FALLBACK_DECISION`	—	`APPROVE` o `REJECT`: la decisión que la API aplica cuando no recibe una decisión.
`ANTIFRAUD_HOOK_FALLBACK_MAX_APPROVE_AMOUNT`	—	Cuando la API no recibe una decisión, aprueba un monto hasta este valor y rechaza un monto mayor. Define exactamente una de las dos variables de fallback.
`ANTIFRAUD_HOOK_HMAC_SECRET`	🔒 Obligatorio cuando está activada	Secreto que firma cada solicitud con HMAC-SHA256. Al menos 32 caracteres.
`ANTIFRAUD_HOOK_AUTH_HEADER_NAME` · `ANTIFRAUD_HOOK_AUTH_HEADER_VALUE`	🔒 —	Un header que la API agrega a cada solicitud. Define ambos o ninguno.
`ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK`	`false`	Define `true` para permitir una URL `http` y un endpoint en una red privada.
`ANTIFRAUD_HOOK_CB_ENABLED`	`true`	Circuit breaker para las llamadas a tu endpoint. Mientras el circuit breaker está abierto, la API aplica el fallback sin hacer la llamada.
`ANTIFRAUD_HOOK_CB_FAILURE_THRESHOLD` · `ANTIFRAUD_HOOK_CB_TIMEOUT` · `ANTIFRAUD_HOOK_CB_MAX_REQUESTS` · `ANTIFRAUD_HOOK_CB_INTERVAL`	`5` · `30s` · `3` · `60s`	Fallas consecutivas que abren el circuit breaker, cuánto tiempo permanece abierto, llamadas de prueba después de eso y el período que reinicia el conteo de fallas. Un intervalo de `0` nunca lo reinicia.
`ANTIFRAUD_HOOK_PREWARM_ENABLED`	`true`	Envía un `GET` sin firma a la URL del endpoint cada 60 segundos para mantener una conexión abierta.

Eventos de negocio

Estas variables configuran los eventos de Pix BTG en el componente de la API. Cuando STREAMING_ENABLED es false, la API ignora las demás variables de esta tabla.

Variable	Predeterminado / Obligatorio	Descripción
`STREAMING_ENABLED`	`false`	Define `true` para publicar eventos de negocio.
`STREAMING_BROKERS`	Obligatorio cuando está activado	Brokers Kafka de bootstrap, como una lista `host:port` separada por comas.
`STREAMING_CLOUDEVENTS_SOURCE`	`plugin-br-pix-indirect-btg`	El `ce-source` de cada evento. También da nombre al tópico `lerian.streaming.<source>`.
`STREAMING_TENANT_ID`	`default`	El `ce-tenantid` de cada evento: de 1 a 256 letras ASCII, dígitos, `-` o `_`, que empieza con una letra o un dígito.
`STREAMING_CLIENT_ID`	—	ID de cliente Kafka.
`STREAMING_TLS_ENABLED` · `STREAMING_TLS_CA_CERT`	`false` · —	TLS con los brokers y una CA PEM codificada en base64. Sin una CA, la API usa el almacén de confianza del sistema.
`STREAMING_SASL_MECHANISM` · `STREAMING_SASL_USERNAME` · `STREAMING_SASL_PASSWORD`	🔒 —	Autenticación SASL con los brokers: `PLAIN`, `SCRAM-SHA-256` o `SCRAM-SHA-512`. Un mecanismo vacío desactiva SASL.
`STREAMING_SASL_ALLOW_PLAINTEXT`	`false`	Permite SASL sin TLS. Úsalo solo en desarrollo local.
`STREAMING_CB_FAILURE_RATIO` · `STREAMING_CB_MIN_REQUESTS` · `STREAMING_CB_TIMEOUT_S`	`0.5` · `10` · `30`	Circuit breaker para los brokers. Mientras está abierto, los eventos con fallback al outbox van al outbox.
`STREAMING_CLOSE_TIMEOUT_S`	`30`	Tiempo máximo, en segundos, para vaciar los eventos al apagar.
`STREAMING_TOPIC_AUTO_PROVISION` · `STREAMING_TOPIC_PARTITIONS` · `STREAMING_TOPIC_REPLICATION_FACTOR`	`true` · `-1` · `-1`	Crea los tópicos al iniciar. `-1` usa el valor predeterminado del broker. Define `false` cuando creas los tópicos por adelantado.
`STREAMING_OUTBOX_RETENTION_PUBLISHED_H` · `STREAMING_OUTBOX_RETENTION_INVALID_H`	`72` · `720`	Horas que se conservan los registros publicados e inválidos del outbox. `0` desactiva su eliminación.

Health y readiness

Cada componente expone GET /health (liveness) y GET /readyz (readiness) en su puerto. Consulta Health y readiness para conocer la forma de la respuesta. Con STREAMING_ENABLED=true, el readiness de la API también informa la dependencia streaming.

Introducción

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Variables de entorno

Componentes y puertos

Integración con BTG y mTLS

Datastores

Midaz, CRM y Fees

Webhooks internos y programación

Ámbito de Pix y del ledger

Access Manager

Verificación de fraude en Pix entrante

Eventos de negocio

Health y readiness

​Componentes y puertos

​Integración con BTG y mTLS

​Datastores

​Midaz, CRM y Fees

​Webhooks internos y programación

​Ámbito de Pix y del ledger

​Access Manager

​Verificación de fraude en Pix entrante

​Eventos de negocio

​Health y readiness

Componentes y puertos

Integración con BTG y mTLS

Datastores

Midaz, CRM y Fees

Webhooks internos y programación

Ámbito de Pix y del ledger

Access Manager

Verificación de fraude en Pix entrante

Eventos de negocio

Health y readiness