Variáveis de ambiente

O Pix Direto, via JD conecta seu ledger diretamente ao arranjo Pix através do gateway DICT e SPI da JD. A equipe de DevOps define seu comportamento através de variáveis de ambiente no momento do deploy. Para alterar uma variável, reinicie o serviço. Esta página cobre as variáveis distintivas deste rail. Para os parâmetros de datastore, multi-tenancy, streaming, telemetria e autenticação que todos os serviços Go da Lerian compartilham, 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, e nunca faça commit dele. Esta página lista apenas nomes de variáveis e comportamento. Ela não imprime nenhum valor de segredo.

Servidor e porta

O serviço escuta no endereço em SERVER_ADDRESS (padrão :8080). As probes de liveness, readiness e version se vinculam a essa mesma porta. Consulte Servidor para os parâmetros de servidor compartilhados e Portas de rede padrão.

Integração com a JD

Credenciais e endpoints para a API da JD protegida por OAuth e sua superfície Pix (JDPI).

Variável	Padrão / Obrigatória	Descrição
`JD_BASE_URL`	Obrigatória	URL base da API da JD.
`JD_CLIENT_ID`	Obrigatória	OAuth client ID para a API da JD.
`JD_SECRET`	🔒 Obrigatória	OAuth client secret para a API da JD.
`JD_GRANT_TYPE`	`client_credentials`	Tipo de grant OAuth usado contra a JD.
`JD_BANK_ID`	Obrigatória	Seu identificador de instituição na JD.
`JD_USE_SERVICE_SEGMENTS`	`false`	Roteia chamadas através dos service segments da JD quando `true`.
`JD_PIX_URL`	Obrigatória	URL base da API Pix (JDPI) da JD.
`JD_PIX_CLIENT_ID`	Obrigatória	OAuth client ID para a API Pix da JD.
`JD_PIX_CLIENT_SECRET`	🔒 Obrigatória	OAuth client secret para a API Pix da JD.
`JDPI_MAX_RETRIES`	`2`	Tentativas de retry em uma chamada JDPI falha.
`JDPI_RETRY_BASE_DELAY_MS`	`100`	Atraso base de backoff em milissegundos entre retries JDPI.

Hospedagem de QR code dinâmico

O rail hospeda payloads de QR dinâmico assinados (JWS) e o JWK set usado para verificá-los. O plugin serve esses documentos sob o host em QRCODE_PUBLIC_BASE_URL. Defina um host simples (FQDN) sem esquema de URL, porque a JDPI rejeita um esquema.

Variável	Padrão / Obrigatória	Descrição
`QRCODE_PUBLIC_BASE_URL`	Obrigatória	Host sem esquema (FQDN) onde o plugin serve os payloads de QR dinâmico e o JWK set.
`QRCODE_PAYLOAD_PATH`	`v1/qrcodes/payload`	Segmento de path onde o plugin expõe os payloads de QR assinados.
`QRCODE_JWK_PATH`	`v1/qrcodes/jwks`	Segmento de path onde o plugin expõe o JWK set.
`QRCODE_JWS_CONTENT_TYPE`	`application/jose`	`Content-Type` retornado para o payload assinado.
`QRCODE_JWKS_CONTENT_TYPE`	`application/jwk-set+json`	`Content-Type` retornado para o JWK set.

Vínculo com o ledger Midaz

Qual organização, ledger, asset e conta externa do Midaz este rail usa para contabilizar movimentos Pix, além dos endpoints do serviço de ledger e das credenciais machine-to-machine.

Variável	Padrão / Obrigatória	Descrição
`MIDAZ_ORGANIZATION_ID`	Obrigatória	UUID da organização Midaz que detém o ledger Pix.
`MIDAZ_LEDGER_ID`	Obrigatória	UUID do ledger Midaz para contabilizações Pix.
`MIDAZ_ASSET_ID`	`1`	Asset (moeda) contabilizado para operações Pix.
`MIDAZ_EXTERNAL_ID`	Obrigatória	Conta externa usada como contraparte de liquidação Pix.
`MIDAZ_URL_ONBOARDING`	Obrigatória	URL do serviço de onboarding do Midaz.
`MIDAZ_URL_TRANSACTION`	Obrigatória	URL do serviço de transações do Midaz.
`MIDAZ_AUTH_ADDRESS`	—	URL do Access Manager para tokens M2M do Midaz.
`MIDAZ_CLIENT_ID`	—	OAuth client ID para M2M do Midaz.
`MIDAZ_CLIENT_SECRET`	🔒 —	OAuth client secret para M2M do Midaz.
`MIDAZ_TIMEOUT`	`30000`	Timeout de requisição Midaz em milissegundos.

Rotas de transação e operação

O plugin mapeia os fluxos Pix de cash-in, cash-out, estorno e intra-PSP em rotas nomeadas de transação e operação do Midaz. Defina um valor por fluxo para que o plugin contabilize cada evento Pix na rota correta.

Variável	Padrão / Obrigatória	Descrição
`TRANSACTION_ROUTE_CASHIN` · `TRANSACTION_ROUTE_CASHIN_QRCODE` · `TRANSACTION_ROUTE_CASHIN_REVERSAL`	Obrigatória	IDs de transaction-route para a família de cash-in (padrão, QR code, estorno).
`TRANSACTION_ROUTE_CASHOUT` · `TRANSACTION_ROUTE_CASHOUT_REVERSAL`	Obrigatória	IDs de transaction-route para a família de cash-out.
`TRANSACTION_ROUTE_INTRAPSP` · `TRANSACTION_ROUTE_INTRAPSP_REVERSAL`	Obrigatória	IDs de transaction-route para transferências intra-PSP e seus estornos.
`OPERATION_ROUTE_CASHIN_*`	Obrigatória	IDs de operation-route para cada leg de cash-in (crédito, débito, QR code, externa, variantes de estorno).
`OPERATION_ROUTE_CASHOUT_*`	Obrigatória	IDs de operation-route para cada leg de cash-out (crédito, débito, externa, variantes de estorno).

OPERATION_ROUTE_CASHIN_* e OPERATION_ROUTE_CASHOUT_* representam exatamente doze variáveis concretas de mapeamento de rota por leg (oito de cash-in, quatro de cash-out). Cada uma mapeia um leg do pipeline para um ID de operation-route do Midaz. Defina cada uma explicitamente:Cash-in (8): OPERATION_ROUTE_CASHIN_CREDIT, OPERATION_ROUTE_CASHIN_CREDIT_QRCODE, OPERATION_ROUTE_CASHIN_CREDIT_REVERSAL, OPERATION_ROUTE_CASHIN_DEBIT, OPERATION_ROUTE_CASHIN_DEBIT_QRCODE_EXTERNAL, OPERATION_ROUTE_CASHIN_DEBIT_REVERSAL_EXTERNAL, OPERATION_ROUTE_CASHIN_REVERSAL_CREDIT, OPERATION_ROUTE_CASHIN_REVERSAL_DEBITCash-out (4): OPERATION_ROUTE_CASHOUT_CREDIT_EXTERNAL, OPERATION_ROUTE_CASHOUT_CREDIT_REVERSAL, OPERATION_ROUTE_CASHOUT_DEBIT, OPERATION_ROUTE_CASHOUT_DEBIT_REVERSAL_EXTERNAL

Jobs e limites

Variável	Padrão / Obrigatória	Descrição
`JOBS_CRON`	`/10 * * * *`	Expressão cron para o job de reconciliação/housekeeping.
`JOBS_CRON_TRANSACTIONS`	`/10 * * * *`	Expressão cron para o job de processamento de transações.
`JOBS_RECONCILE_STUCK_THRESHOLD_SEC`	`80`	Idade em segundos após a qual um cash-out pendente é sinalizado como travado.
`TRANSACTION_LIMIT_DAILY_PERIOD_INIT` · `TRANSACTION_LIMIT_DAILY_PERIOD_END`	—	Início e fim da janela diária usada para a contabilização de limite de transação.
`MAX_PAGINATION_LIMIT` · `MAX_PAGINATION_MONTH_DATE_RANGE`	`100` · `3`	Limites superiores para o tamanho de página de listagem e o intervalo de datas.

Notificações

Notificações opcionais ao cliente final para eventos Pix. Deixe os blocos de provider não definidos para desabilitar aquele canal.

Variável	Padrão / Obrigatória	Descrição
`SENDGRID_API_KEY`	🔒 —	Chave de API do SendGrid para notificações por email.
`SENDGRID_FROM_EMAIL`	—	Endereço remetente para notificações por email.
`SENDGRID_FROM_TEMPLATE`	—	ID do template do SendGrid usado para o corpo da mensagem.
`TWILIO_ACCOUNT_SID`	🔒 —	SID de conta do Twilio para notificações por SMS.
`TWILIO_AUTH_TOKEN`	🔒 —	Auth token do Twilio para notificações por SMS.
`TWILIO_PHONE_NUMBER`	—	Número de telefone remetente para notificações por SMS.

CRM

Variável	Padrão / Obrigatória	Descrição
`CRM_URL`	—	URL do serviço CRM para consultas de contraparte.
`CRM_CLIENT_ID`	—	OAuth client ID para M2M do CRM.
`CRM_CLIENT_SECRET`	🔒 —	OAuth client secret para M2M do CRM.

Configuração de runtime (systemplane)

Este rail monta a API de administração do systemplane em sua porta principal, controlada por SYSTEMPLANE_ENABLED.

Variável	Padrão / Obrigatória	Descrição
`SYSTEMPLANE_ENABLED`	`false`	Habilita a API de administração de configuração de runtime do systemplane.

Quando habilitado, o serviço expõe um plano autenticado para ler e gravar a configuração de runtime. Consulte Systemplane para a API, os namespaces e as permissões necessárias.

Saúde e prontidão

O rail expõe GET /health (liveness) e GET /readyz (readiness) na porta principal, além de /metrics e /version. Quando você habilita a multi-tenancy (MULTI_TENANT_ENABLED=true), o rail adiciona uma probe por tenant protegida por auth em GET /readyz/tenant/{id}. Consulte Saúde e prontidão para o formato da resposta e o comportamento de startup/drain.

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

Variáveis de ambiente

Servidor e porta

Integração com a JD

Hospedagem de QR code dinâmico

Vínculo com o ledger Midaz

Rotas de transação e operação

Jobs e limites

Notificações

CRM

Configuração de runtime (systemplane)

Saúde e prontidão

​Servidor e porta

​Integração com a JD

​Hospedagem de QR code dinâmico

​Vínculo com o ledger Midaz

​Rotas de transação e operação

​Jobs e limites

​Notificações

​CRM

​Configuração de runtime (systemplane)

​Saúde e prontidão

Servidor e porta

Integração com a JD

Hospedagem de QR code dinâmico

Vínculo com o ledger Midaz

Rotas de transação e operação

Jobs e limites

Notificações

CRM

Configuração de runtime (systemplane)

Saúde e prontidão