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 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_ADDRESS (por exemplo :4014). Os workers de conciliação, de agendamento e de webhooks usam cada um um WORKER_PORT para as próprias health probes. Veja Portas de rede padrão.

Integração com o BTG e mTLS

Essas variáveis guardam as credenciais do BTG e as configurações de TLS mútuo nas duas direções: o certificado de cliente que o plugin apresenta ao BTG e a verificação do certificado que o BTG apresenta nos webhooks recebidos.

Variável	Padrão / Obrigatório	Descrição
`BTG_BASE_URL`	Obrigatório	URL base da API do BTG.
`BTG_CERTIFICATE_URL`	Obrigatório quando `MTLS_ENABLED=true`	URL do certificado público do BTG. A API o compara com o certificado que o BTG apresenta nos webhooks recebidos.
`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 quando a validação está habilitada	Segredo usado para validar as assinaturas dos webhooks recebidos do BTG.
`BTG_WEBHOOK_VALIDATION_ENABLED`	`false`	Verifica as assinaturas dos webhooks do BTG. Defina `true` em produção.
`MTLS_ENABLED`	`false`	Verifica o certificado que o BTG apresenta nos webhooks recebidos. Habilite em produção.
`MTLS_CERTIFICATE_HEADER`	`X-Client-Cert`	Header em que o seu ingress repassa o certificado apresentado pelo BTG. O seu ingress deve definir esse header a partir do handshake TLS e sobrescrever qualquer valor que o chamador enviar.
`MTLS_CERTIFICATE_TTL`	`24h`	Por quanto tempo o certificado buscado do BTG fica em cache antes da renovação.
`MTLS_HTTP_TIMEOUT`	`10s`	Timeout da chamada HTTP que busca o certificado.
`BTG_OUTBOUND_MTLS_ENABLED`	`false`	Apresenta um certificado de cliente nas chamadas ao BTG.
`CLIENT_TLS_CERT_FILE` · `CLIENT_TLS_KEY_FILE`	🔒 Obrigatório quando o mTLS de saída está habilitado	Caminhos do certificado de cliente e da chave privada em PEM.
`CLIENT_TLS_CA_FILE`	—	Pacote PEM opcional que verifica o certificado do servidor do BTG.

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`	—	Modo TLS do libpq. Defina explicitamente. 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).
`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_PASSWORD`	🔒 —	Endpoint `host:port` 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.
`DEPLOYMENT_MODE`	`local`	`local`, `byoc` ou `saas`. Com `saas`, um componente não inicia se um datastore que ele usa não tem TLS. O PostgreSQL exige `DB_SSL_MODE` igual a `require`, `verify-ca` ou `verify-full`. O Redis exige `REDIS_TLS=true`. O MongoDB exige `MONGO_TLS=true`.

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`	🔒 Obrigatório	Credenciais OAuth para o M2M do Midaz.
`MIDAZ_COUNTERPARTY_ACCOUNT_ALIAS`	`@external/BRL`	Conta do Midaz que os lançamentos de cash-out Pix creditam.
`MIDAZ_CASHOUT_TRANSACTION_ROUTE` · `MIDAZ_CASHOUT_SOURCE_OPERATION_ROUTE` · `MIDAZ_CASHOUT_DESTINATION_OPERATION_ROUTE`	—	Rota de transação, rota de operação de débito e rota de operação de crédito do Midaz para os lançamentos de cash-out Pix. Se um valor está vazio, o plugin não envia rota para ele.
`MIDAZ_CASHOUT_REFUND_TRANSACTION_ROUTE`	—	Rota de transação do Midaz para uma devolução que envia um array `operations`, ou que devolve o valor total de um cash-in com tarifas. Se está vazia, o plugin usa `MIDAZ_CASHOUT_TRANSACTION_ROUTE`.
`PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET`	🔒 Obrigatório	URL do serviço de CRM e credenciais OAuth.
`FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET`	🔒 Obrigatório quando `CASHIN_FEE_CALCULATION_TYPE=segment`	URL do serviço Fees Engine e credenciais OAuth.
`FEE_SERVICE_TIMEOUT`	`5000`	Timeout da requisição de tarifa, em milissegundos.
`CASHIN_FEE_CALCULATION_TYPE`	—	Defina `segment` para calcular as tarifas de cash-in pelo segmento da conta. Deixe vazio para não cobrar tarifas de cash-in.

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. Pelo menos 32 caracteres.
`INTERNAL_WEBHOOK_VALIDATION_ENABLED`	`false`	Verifica as assinaturas dos webhooks internos. Defina `true` em produção.
`INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE`	`300`	Desvio de relógio permitido, em segundos, 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 de rede do seu serviço interno 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: 8 caracteres, dígitos ou letras maiúsculas.
`ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END`	—	Janela diária (`HH:MM`, horário de São Paulo) durante a qual a API bloqueia a criação, a atualização e a exclusão de chaves Pix.
`ORGANIZATION_IDS`	Obrigatório em produção	UUIDs de organizações do Midaz no escopo do licenciamento, separados por vírgula.
`GOOGLE_APPLICATION_CREDENTIALS`	🔒 —	Credenciais de conta de serviço do Google (um caminho de arquivo ou o conteúdo JSON) para a autenticação IAM da GCP no Redis.

Access Manager

Estas variáveis se aplicam ao componente da API. Para PLUGIN_AUTH_ENABLED e PLUGIN_AUTH_ADDRESS, veja Fundamentos de configuração BYOC.

Variável	Padrão / Obrigatório	Descrição
`TRUSTED_PROXIES`	—	Faixas CIDR, separadas por vírgula, dos proxies que se conectam direto à API. A API resolve o endereço de quem chama por meio deles e o envia ao Access Manager para a lista de IPs permitidos. Se a variável não estiver definida, a API não envia o endereço de quem chama.
`DECLARATION_ENABLED`	`false`	Defina `true` para publicar a declaração de permissões do plugin no Access Manager na inicialização.
`PLUGIN_IDENTITY_HOST`	—	URL absoluta `http` ou `https` do serviço Identity do Access Manager.
`M2M_CLIENT_ID` · `M2M_CLIENT_SECRET`	🔒 —	As credenciais de cliente com que a API publica a declaração.

Com DECLARATION_ENABLED=true, a API não inicia quando PLUGIN_IDENTITY_HOST, M2M_CLIENT_ID ou M2M_CLIENT_SECRET está vazio. Ela também não inicia quando PLUGIN_AUTH_ENABLED não é true, ou quando PLUGIN_IDENTITY_HOST ou PLUGIN_AUTH_ADDRESS não é uma URL absoluta http ou https.

Verificação de fraude em Pix recebido

Estas variáveis configuram a verificação de fraude em Pix recebido no componente da API. Quando ANTIFRAUD_HOOK_ENABLED é false, a API ignora as outras variáveis desta tabela.

Variável	Padrão / Obrigatório	Descrição
`ANTIFRAUD_HOOK_ENABLED`	`false`	Defina `true` para consultar o seu endpoint de decisão antes de a API aceitar um Pix recebido ou uma devolução recebida.
`ANTIFRAUD_HOOK_URL`	Obrigatório quando ativada	URL do seu endpoint de decisão. Ela deve usar `https`, a menos que `ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK=true`.
`ANTIFRAUD_HOOK_TIMEOUT_MS`	`500`	Quanto tempo a API espera por uma decisão, em milissegundos. O mínimo é `100`.
`ANTIFRAUD_HOOK_FALLBACK_DECISION`	—	`APPROVE` ou `REJECT`: a decisão que a API aplica quando não recebe uma decisão.
`ANTIFRAUD_HOOK_FALLBACK_MAX_APPROVE_AMOUNT`	—	Quando a API não recebe uma decisão, ela aprova um valor até este limite e rejeita um valor maior. Defina exatamente uma das duas variáveis de fallback.
`ANTIFRAUD_HOOK_HMAC_SECRET`	🔒 Obrigatório quando ativada	Segredo que assina cada requisição com HMAC-SHA256. Pelo menos 32 caracteres.
`ANTIFRAUD_HOOK_AUTH_HEADER_NAME` · `ANTIFRAUD_HOOK_AUTH_HEADER_VALUE`	🔒 —	Um header que a API adiciona a cada requisição. Defina os dois ou nenhum.
`ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK`	`false`	Defina `true` para permitir uma URL `http` e um endpoint em uma rede privada.
`ANTIFRAUD_HOOK_CB_ENABLED`	`true`	Circuit breaker para as chamadas ao seu endpoint. Enquanto o circuit breaker está aberto, a API aplica o fallback sem fazer a chamada.
`ANTIFRAUD_HOOK_CB_FAILURE_THRESHOLD` · `ANTIFRAUD_HOOK_CB_TIMEOUT` · `ANTIFRAUD_HOOK_CB_MAX_REQUESTS` · `ANTIFRAUD_HOOK_CB_INTERVAL`	`5` · `30s` · `3` · `60s`	Falhas consecutivas que abrem o circuit breaker, quanto tempo ele fica aberto, chamadas de teste depois disso e o período que zera a contagem de falhas. Um intervalo de `0` nunca a zera.
`ANTIFRAUD_HOOK_PREWARM_ENABLED`	`true`	Envia um `GET` sem assinatura à URL do endpoint a cada 60 segundos para manter uma conexão aberta.

Eventos de negócio

Estas variáveis configuram os eventos do Pix BTG no componente da API. Quando STREAMING_ENABLED é false, a API ignora as outras variáveis desta tabela.

Variável	Padrão / Obrigatório	Descrição
`STREAMING_ENABLED`	`false`	Defina `true` para publicar eventos de negócio.
`STREAMING_BROKERS`	Obrigatório quando ativado	Brokers Kafka de bootstrap, em uma lista `host:port` separada por vírgulas.
`STREAMING_CLOUDEVENTS_SOURCE`	`plugin-br-pix-indirect-btg`	O `ce-source` de cada evento. Ele também dá nome ao tópico `lerian.streaming.<source>`.
`STREAMING_TENANT_ID`	`default`	O `ce-tenantid` de cada evento: de 1 a 256 letras ASCII, dígitos, `-` ou `_`, começando por uma letra ou um dígito.
`STREAMING_CLIENT_ID`	—	ID de cliente Kafka.
`STREAMING_TLS_ENABLED` · `STREAMING_TLS_CA_CERT`	`false` · —	TLS com os brokers e uma CA PEM codificada em base64. Sem uma CA, a API usa o repositório de confiança do sistema.
`STREAMING_SASL_MECHANISM` · `STREAMING_SASL_USERNAME` · `STREAMING_SASL_PASSWORD`	🔒 —	Autenticação SASL com os brokers: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Um mecanismo vazio desliga o SASL.
`STREAMING_SASL_ALLOW_PLAINTEXT`	`false`	Permite SASL sem TLS. Use apenas em desenvolvimento local.
`STREAMING_CB_FAILURE_RATIO` · `STREAMING_CB_MIN_REQUESTS` · `STREAMING_CB_TIMEOUT_S`	`0.5` · `10` · `30`	Circuit breaker para os brokers. Enquanto ele está aberto, os eventos com fallback para o outbox vão para o outbox.
`STREAMING_CLOSE_TIMEOUT_S`	`30`	Tempo máximo, em segundos, para descarregar os eventos no desligamento.
`STREAMING_TOPIC_AUTO_PROVISION` · `STREAMING_TOPIC_PARTITIONS` · `STREAMING_TOPIC_REPLICATION_FACTOR`	`true` · `-1` · `-1`	Cria os tópicos na inicialização. `-1` usa o padrão do broker. Defina `false` quando você cria os tópicos com antecedência.
`STREAMING_OUTBOX_RETENTION_PUBLISHED_H` · `STREAMING_OUTBOX_RETENTION_INVALID_H`	`72` · `720`	Horas para manter os registros publicados e inválidos do outbox. `0` desliga a exclusão deles.

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. Com STREAMING_ENABLED=true, o readiness da API também informa a dependência streaming.

Introdução

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Variáveis de ambiente

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

Access Manager

Verificação de fraude em Pix recebido

Eventos de negócio

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

​Access Manager

​Verificação de fraude em Pix recebido

​Eventos de negócio

​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

Access Manager

Verificação de fraude em Pix recebido

Eventos de negócio

Health e readiness