Variables de entorno

Configura el riel Pix Indirecto vía BTG: mTLS con BTG, datastores DB_*, vínculos con Midaz y CRM, endpoints de webhook y componentes worker en el despliegue.

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 las variables de los workers, consulta la sección de capas de worker de Integración y, para el worker de salida, Webhooks. El worker de programación ejecuta Pix programados solo con SCHEDULE_WORKER_ENABLED=true. 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). El puerto principal sirve las rutas de la API, GET /health (una respuesta constante) y GET /version. Cada componente, workers incluidos, sirve el readiness y las métricas en HEALTH_PORT. Consulta Health y readiness y Puertos de red predeterminados.

Licencia

Cada componente verifica la licencia al iniciar. La API, el worker de conciliación, el worker de programación y los workers de webhooks entrantes y salientes no inician sin una licencia válida. Si el servicio de licencia no responde al iniciar, el componente sigue en pie, no listo, y sigue intentando.

Variable	Predeterminado / Obligatorio	Descripción
LICENSE_KEY	🔒 Obligatorio en cada componente, salvo que LICENSE_FILE_PATH esté definida	La clave de licencia de todo el despliegue. El componente obtiene con ella un archivo de licencia firmado y lo mantiene en memoria. Sin LICENSE_FILE_PATH, el componente no inicia con una clave vacía. Si la licencia se rechaza después del inicio, el componente drena y termina con estado 1.
LICENSE_FILE_PATH	Opcional	Ruta de un archivo de licencia firmado. Cuando está definida, el componente usa el archivo sin llamada de red e ignora LICENSE_KEY. Un archivo que el componente rechaza detiene el inicio.

Consulta La licencia de Lerian.

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. Debe ser una URL https.
BTG_CERTIFICATE_URL	Obligatorio cuando MTLS_ENABLED=true	URL del certificado público de BTG. Debe ser una URL https. 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	true	Verifica las firmas de los webhooks de BTG. Mantenlo 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	require	Modo TLS de libpq. 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 y CRM

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 el tramo externo de un registro de cash-out Pix acredita. Un registro intra-PSP no la acredita.
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. Un registro intra-PSP usa la ruta de transacción y la ruta de operación de débito, y sus tramos de crédito no llevan ruta de operación.
MIDAZ_CASHOUT_REFUND_TRANSACTION_ROUTE · MIDAZ_CASHOUT_REFUND_SOURCE_OPERATION_ROUTE · MIDAZ_CASHOUT_REFUND_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 una devolución de cash-out. Si un valor está vacío, el plugin usa la ruta de cash-out correspondiente. Los débitos de cuentas de comisión no llevan ruta. Una devolución intra-PSP no lleva ruta de operación de crédito.
MIDAZ_CASHIN_TRANSACTION_ROUTE · MIDAZ_CASHIN_DESTINATION_OPERATION_ROUTE	—	Ruta de transacción y ruta de operación de crédito de Midaz para los registros de cash-in Pix. Si un valor está vacío, el plugin no envía ruta para él. Los créditos de cuentas de comisión no llevan ruta.
MIDAZ_CASHIN_REFUND_TRANSACTION_ROUTE · MIDAZ_CASHIN_REFUND_DESTINATION_OPERATION_ROUTE	—	Ruta de transacción y ruta de operación de crédito de Midaz para los registros de una devolución que recibes. Si un valor está vacío, el plugin usa la ruta de cash-in correspondiente.
PLUGIN_CRM_CLIENT_ID · PLUGIN_CRM_CLIENT_SECRET	🔒 Obligatorio	Credenciales OAuth del CRM que sirve Midaz.
PLUGIN_CRM_BASE_URL	Opcional en la API con Midaz 4. Defínela en el worker de conciliación	URL del CRM que sirve Midaz. En la API con Midaz 4, un valor vacío hace que la API use MIDAZ_ONBOARDING_URL como CRM. Si la API no puede leer la versión de Midaz en esa URL, o si Midaz es 3.x, la API no inicia. Sin la URL, cada consulta al CRM falla.

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	true	Verifica las firmas de los webhooks internos. Mantenlo 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.
WEBHOOK_INBOUND_RETENTION	—	Worker de webhooks entrantes. Cuánto tiempo conserva el plugin los webhooks recibidos que ya terminaron: una duración como 2160h, o un número de segundos. Sin valor o 0 conserva todos los webhooks. Un valor negativo o malformado rechaza el arranque.
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_MAX_ATTEMPTS · SCHEDULE_MAX_FUTURE_DAYS · SCHEDULE_MIN_FUTURE_SECONDS	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.
REQUEST_TIMEOUT_SEC	60	API. El tiempo que puede durar cada solicitud de negocio, en segundos. Un valor 0 o menor significa 60. Cuando el límite termina, o la API no puede alcanzar una base de datos o un caché, y no aplica ningún error más específico, la API responde 503 PIX-0016. Después del débito en Midaz de un cash-out o de una devolución, el envío a BTG pasa de este límite, así que un timeout del cliente no demuestra que no se envió nada.
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. Cuando la defines, el plugin también inicia una conciliación completa de claves Pix solo dentro de la ventana.
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

Variable	Predeterminado / Obligatorio	Descripción
HEALTH_PORT	Obligatorio en cada worker	El puerto del listener de health, por ejemplo 8099 en la API. Sirve GET /health, GET /readyz, GET /metrics y GET /version. Un worker sin él falla al iniciar. La API sin él no tiene endpoint de readiness. Mantén este puerto interno.

Apunta la sonda de readiness de cada componente a su HEALTH_PORT.

Un componente no está listo hasta que se acepta una licencia. La API y el worker de conciliación también esperan a PostgreSQL (primario) y a Redis. Los workers de webhooks entrantes y salientes también esperan a PostgreSQL. El worker de programación también informa su propio loop. Después del inicio, una réplica de PostgreSQL o un MongoDB con fallo aparece como degraded y el pod sigue en rotación. Con STREAMING_ENABLED=true, la verificación streaming informa de la misma forma. Cada worker también informa su propio loop de trabajo como una verificación de liveness. Consulta Health y readiness para conocer la forma de la respuesta.