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 workers de reconciliação, agenda e webhooks de entrada/saída — cada um configurado através de variáveis de ambiente definidas no momento do deploy pela equipe de DevOps; alterar uma exige a reinicialização daquele 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-o no momento do deploy a partir do seu secret store, nunca faça commit dele. 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 e carrega seus próprios parâmetros de tuning extensivos (tamanhos de batch, intervalos de polling, concorrência e circuit breakers) em seus respectivos arquivos .env.example. Consulte Portas de rede padrão.

Integração com a BTG e mTLS

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_* (não o formato compartilhado POSTGRES_*) para sua conexão PostgreSQL primária e uma réplica de leitura separada, além de 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 e 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`	—	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`	—	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`	—	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; a API também responde /ready. Consulte Saúde e prontidão para o formato da resposta e o comportamento de startup/drain.

Visão geral

Direto via JD

Indireto via BTG

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