Variáveis de ambiente

O Pix Indireto via BTG alcança o arranjo Pix pelo BTG como participante direto. Ele é entregue em vários componentes: uma API, mais os workers de conciliação, de agendamento e de webhooks de entrada e de saída. O DevOps define as variáveis de ambiente de cada componente no deploy. Para mudar uma variável, você reinicia aquele componente. Esta página cobre as variáveis específicas deste trilho. Para os controles de multi-tenancy, streaming, telemetria e autenticação compartilhados por todos os serviços Go da Lerian, veja Fundamentos de configuração BYOC.

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

Este trilho não monta a systemplane admin API. As variáveis de datastore dele usam o prefixo DB_* em vez do formato compartilhado POSTGRES_*. Veja Datastores abaixo.

Componentes e portas

O componente de API escuta em SERVER_PORT (padrão 4014). SERVER_ADDRESS deriva dele. Os workers de conciliação, de agendamento e de webhooks usam cada um um WORKER_PORT para as próprias health probes. Cada worker traz os próprios controles de ajuste (tamanhos de lote, intervalos de consulta, concorrência e circuit breakers) no arquivo .env.example dele. Veja Portas de rede padrão.

Integração com o BTG e mTLS

Essas variáveis guardam as credenciais e as configurações de TLS mútuo da conexão com o BTG.

Variável	Padrão / Obrigatório	Descrição
`BTG_BASE_URL`	Obrigatório	URL base da API do BTG.
`BTG_CERTIFICATE_URL`	Obrigatório	Endpoint de onde o certificado de cliente é buscado para o mTLS.
`BTG_CLIENT_ID`	Obrigatório	Client ID OAuth da API do BTG.
`BTG_CLIENT_SECRET`	🔒 Obrigatório	Client secret OAuth da API do BTG.
`BTG_WEBHOOK_SECRET`	🔒 Obrigatório	Segredo usado para validar as assinaturas dos webhooks recebidos do BTG.
`BTG_WEBHOOK_VALIDATION_ENABLED`	`true`	Verifica as assinaturas dos webhooks do BTG. Deixe `true` em produção.
`MTLS_ENABLED`	`false`	Habilita o TLS mútuo na conexão com o BTG. Habilite em produção.
`MTLS_CERTIFICATE_TTL`	`24h`	Por quanto tempo um certificado de cliente buscado fica em cache antes da renovação.
`MTLS_HTTP_TIMEOUT`	`10s`	Timeout da chamada HTTP que busca o certificado.

Datastores

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

Variável	Padrão / Obrigatório	Descrição
`DB_HOST` · `DB_PORT`	Obrigatório	Host e porta do PostgreSQL primário.
`DB_USER` · `DB_PASSWORD`	🔒 Obrigatório	Credenciais do PostgreSQL primário.
`DB_NAME`	Obrigatório	Nome do banco 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 opcional com a réplica de leitura (mesmo formato do primário).
`REPLICATION_USER` · `REPLICATION_PASSWORD`	🔒 —	Credenciais do papel de replicação por streaming.
`MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME`	🔒 Obrigatório	Conexão com o MongoDB. `MONGO_URI` define o esquema da 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. Todas se combinam em uma única string de conexão — elas não são alternativas entre URI e campos separados. A senha é um segredo.
`MONGO_TLS`	`false`	Habilita o TLS para o MongoDB.
`REDIS_HOST` · `REDIS_PORT` · `REDIS_PASSWORD`	🔒 —	Endpoint do Redis/Valkey e senha de autenticação.
`REDIS_TLS` · `REDIS_CA_CERT`	`false` · —	Habilita o TLS para o Redis e fornece um CA PEM codificado em base64.

Midaz, CRM e Fees

Variável	Padrão / Obrigatório	Descrição
`MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL`	Obrigatório	URLs dos serviços de onboarding e de transação do Midaz.
`MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID`	Obrigatório	UUIDs da organização e do ledger do Midaz para os lançamentos de Pix.
`MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET`	🔒 —	Credenciais OAuth para o M2M do Midaz.
`PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET`	🔒 —	URL do serviço de 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 da 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 interno de webhooks. Eles também executam fluxos de Pix recorrentes e agendados.

Variável	Padrão / Obrigatório	Descrição
`INTERNAL_WEBHOOK_SECRET`	🔒 Obrigatório	Segredo HMAC compartilhado entre a API e os workers para assinar os webhooks internos.
`INTERNAL_WEBHOOK_VALIDATION_ENABLED`	`true`	Verifica as assinaturas dos webhooks internos.
`INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE`	—	Desvio de relógio permitido ao validar os timestamps dos webhooks internos.
`WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES`	`10485760` (10 MB) · `3`	Limite do payload dos webhooks recebidos e teto de novas tentativas.
`RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS`	`1` · `720h` · `150ms` · `3`	Controles de agendamento do Pix recorrente e de tratamento das respostas.
`SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS`	`6` · `2` · `180` · `60`	Janela e limites de execução dos pagamentos agendados.
`RECONCILIATION_INTERNAL_CIDR`	—	Faixa CIDR confiável para as chamadas internas de conciliação.

Escopo do Pix e do ledger

Variável	Padrão / Obrigatório	Descrição
`PIX_ISPB`	Obrigatório	O ISPB (código do participante) sob o qual este deploy opera.
`ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END`	—	Janela diária durante a qual as escritas de lançamentos no ledger ficam bloqueadas.
`ORGANIZATION_IDS`	Obrigatório em produção	UUIDs de organizações do Midaz no escopo do licenciamento, separados por vírgula.
`GOOGLE_APPLICATION_CREDENTIALS`	🔒 —	Caminho para um arquivo de credenciais de conta de serviço do Google, ao rodar com dependências gerenciadas na GCP.

Health e readiness

Cada componente expõe GET /health (liveness) e GET /readyz (readiness) na porta dele. Veja Health e readiness para o formato da resposta e o comportamento de inicialização e drenagem.

​Componentes e portas

​Integração com o BTG e mTLS

​Datastores

​Midaz, CRM e Fees

​Webhooks internos e agendamento

​Escopo do Pix e do ledger

​Health e readiness

Componentes e portas

Integração com o BTG e mTLS

Datastores

Midaz, CRM e Fees

Webhooks internos e agendamento

Escopo do Pix e do ledger

Health e readiness