Variáveis de ambiente

O Pix Indireto via BTG alcança o arranjo Pix através da BTG como participante direto. Ele é entregue como vários componentes: uma API, mais os workers de reconciliação, agenda e webhooks de entrada e saída. A equipe de DevOps define as variáveis de ambiente de cada componente no momento do deploy. Para alterar uma variável, você reinicia aquele componente. Esta página cobre as variáveis distintivas deste rail. Para os parâmetros de multi-tenancy, streaming, telemetria e autenticação compartilhados entre todos os serviços Go da Lerian, consulte a referência de configuração BYOC.

Nas tabelas abaixo, a coluna Padrão / Obrigatória mostra o valor padrão. Um qualificador em negrito (por exemplo Obrigatória) marca variáveis que você deve definir. — significa que não há padrão. 🔒 marca um segredo. Injete cada segredo no momento do deploy a partir do seu secret store. Nunca faça commit de um segredo. Esta página lista apenas nomes de variáveis e comportamento. Ela não imprime nenhum valor de segredo.

Este rail não monta a API de administração do systemplane. Suas variáveis de datastore usam um prefixo DB_* em vez do formato compartilhado POSTGRES_* — consulte Datastores abaixo.

Componentes e portas

O componente de API escuta em SERVER_PORT (padrão 4014). SERVER_ADDRESS deriva dele. Os workers de reconciliação, agenda e webhook cada um se vincula a um WORKER_PORT para suas probes de saúde. Cada worker carrega seus próprios parâmetros de tuning —tamanhos de batch, intervalos de polling, concorrência e circuit breakers— em seu arquivo .env.example. Consulte Portas de rede padrão.

Integração com a BTG e mTLS

Estas variáveis contêm as credenciais e as configurações de TLS mútuo para a conexão com a BTG.

Variável	Padrão / Obrigatória	Descrição
`BTG_BASE_URL`	Obrigatória	URL base da API da BTG.
`BTG_CERTIFICATE_URL`	Obrigatória	Endpoint a partir do qual o certificado de cliente é obtido para mTLS.
`BTG_CLIENT_ID`	Obrigatória	OAuth client ID para a API da BTG.
`BTG_CLIENT_SECRET`	🔒 Obrigatória	OAuth client secret para a API da BTG.
`BTG_WEBHOOK_SECRET`	🔒 Obrigatória	Segredo usado para validar assinaturas de webhook de entrada da BTG.
`BTG_WEBHOOK_VALIDATION_ENABLED`	`true`	Verifica assinaturas de webhook da BTG. Mantenha `true` em produção.
`MTLS_ENABLED`	`false`	Habilita TLS mútuo na conexão com a BTG. Habilite em produção.
`MTLS_CERTIFICATE_TTL`	`24h`	Por quanto tempo um certificado de cliente obtido fica cacheado antes do refresh.
`MTLS_HTTP_TIMEOUT`	`10s`	Timeout para a chamada HTTP de obtenção do certificado.

Datastores

Este rail usa um prefixo DB_* para os datastores, não o formato compartilhado POSTGRES_*. Ele se conecta a um PostgreSQL primário, uma réplica de leitura separada, MongoDB e Redis.

Variável	Padrão / Obrigatória	Descrição
`DB_HOST` · `DB_PORT`	Obrigatória	Host e porta do PostgreSQL primário.
`DB_USER` · `DB_PASSWORD`	🔒 Obrigatória	Credenciais do PostgreSQL primário.
`DB_NAME`	Obrigatória	Nome do banco de dados primário.
`DB_SSL_MODE`	`disable`	Modo TLS do libpq. Use `require` ou mais forte em produção.
`DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD`	🔒 —	Conexão de réplica de leitura opcional (mesmo formato do primário).
`REPLICATION_USER` · `REPLICATION_PASSWORD`	🔒 —	Credenciais para a role de replicação por streaming.
`MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME`	🔒 Obrigatória	Conexão MongoDB. `MONGO_URI` define o esquema de conexão (`mongodb` ou `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD` e `MONGO_NAME` fornecem o host, as credenciais e o banco de dados. Todas se combinam em uma única string de conexão — não são alternativas de URI versus partes discretas. A senha é um segredo.
`MONGO_TLS`	`false`	Habilita TLS para o MongoDB.
`REDIS_HOST` · `REDIS_PORT` · `REDIS_PASSWORD`	🔒 —	Endpoint do Redis/Valkey e senha de auth.
`REDIS_TLS` · `REDIS_CA_CERT`	`false` · —	Habilita TLS para o Redis e fornece um CA PEM codificado em base64.

Midaz, CRM e Fees

Variável	Padrão / Obrigatória	Descrição
`MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL`	Obrigatória	URLs dos serviços de onboarding e de transações do Midaz.
`MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID`	Obrigatória	UUIDs de organização e de ledger do Midaz para contabilizações Pix.
`MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET`	🔒 —	Credenciais OAuth para M2M do Midaz.
`PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET`	🔒 —	URL do serviço CRM e credenciais OAuth.
`FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET`	🔒 —	URL do serviço Fees Engine e credenciais OAuth.
`FEE_SERVICE_TIMEOUT`	—	Timeout de requisição de tarifa.
`CASHIN_FEE_CALCULATION_TYPE`	—	Como as tarifas de cash-in são calculadas.

Webhooks internos e agendamento

A API e os workers trocam eventos por um canal de webhook interno. Eles também rodam fluxos Pix recorrentes e agendados.

Variável	Padrão / Obrigatória	Descrição
`INTERNAL_WEBHOOK_SECRET`	🔒 Obrigatória	Segredo HMAC compartilhado entre a API e os workers para a assinatura de webhooks internos.
`INTERNAL_WEBHOOK_VALIDATION_ENABLED`	`true`	Verifica assinaturas de webhook interno.
`INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE`	—	Desvio de relógio permitido ao validar timestamps de webhook interno.
`WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES`	`10485760` (10 MB) · `3`	Limite de payload de webhook de entrada e teto de retries.
`RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS`	`1` · `720h` · `150ms` · `3`	Parâmetros de agendamento e de tratamento de reply do Pix recorrente.
`SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS`	`6` · `2` · `180` · `60`	Janela de execução de pagamento agendado e seus limites.
`RECONCILIATION_INTERNAL_CIDR`	—	Faixa de CIDR confiável para chamadas internas de reconciliação.

Escopo Pix e de ledger

Variável	Padrão / Obrigatória	Descrição
`PIX_ISPB`	Obrigatória	O ISPB (código de participante) sob o qual este deployment opera.
`ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END`	—	Janela diária durante a qual escritas de entradas no ledger são bloqueadas.
`ORGANIZATION_IDS`	Obrigatória em produção	UUIDs de organização Midaz no escopo de licenciamento, separados por vírgula.
`GOOGLE_APPLICATION_CREDENTIALS`	🔒 —	Caminho para um arquivo de credenciais de service account do Google, ao rodar contra dependências gerenciadas pelo GCP.

Saúde e prontidão

Cada componente expõe GET /health (liveness) e GET /readyz (readiness) em sua porta. Consulte Saúde e prontidão para o formato da resposta e o comportamento de startup e drain.

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

Variáveis de ambiente

Componentes e portas

Integração com a BTG e mTLS

Datastores

Midaz, CRM e Fees

Webhooks internos e agendamento

Escopo Pix e de ledger

Saúde e prontidão

​Componentes e portas

​Integração com a BTG e mTLS

​Datastores

​Midaz, CRM e Fees

​Webhooks internos e agendamento

​Escopo Pix e de ledger

​Saúde e prontidão

Componentes e portas

Integração com a BTG e mTLS

Datastores

Midaz, CRM e Fees

Webhooks internos e agendamento

Escopo Pix e de ledger

Saúde e prontidão