O Plugin Pix Indireto (BTG) conecta a vários serviços da Lerian e a provedores externos para processar pagamentos Pix. Para configurá-lo, você define a conexão do plugin com cada serviço e prepara os dados de que esses serviços precisam. O plugin roda em duas camadas principais. A Application expõe a API do Pix e processa a lógica de negócio. Os Workers tratam os webhooks recebidos do BTG, a entrega de eventos ao seu sistema, a conciliação do DICT com o BACEN e os pagamentos agendados. As duas camadas compartilham a mesma configuração de base (licença, Midaz, CRM, BTG), mas têm as próprias configurações específicas de serviço.

Pré-requisitos

Antes de começar, confirme que você tem:

O seu ISPB (Identificador do Sistema de Pagamentos Brasileiro): o identificador de 8 caracteres derivado do CNPJ da sua instituição
Acesso às suas instâncias do Midaz e do CRM (com deploy feito e rodando)
Acesso aos serviços do provedor BTG (o BTG fornece as credenciais)

# Your institution's ISPB (8 characters: digits or uppercase letters)
PIX_ISPB=12345678

O plugin usa o PIX_ISPB para gerar e verificar os IDs end-to-end. Já as transferências intra-PSP (P2P) ele detecta pela conta alias do pagador: veja Transferências intra-PSP.

1. Licença

O plugin exige uma licença válida para operar. A Lerian fornece a chave de licença durante o onboarding.

# License key provided by Lerian
LICENSE_KEY=

# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=

Documentação relacionada: Licença da Lerian

2. Access Manager (opcional)

O Access Manager cuida da autenticação do plugin. Quando está habilitado, ele valida as requisições recebidas antes de elas chegarem à API do plugin.

# Require authentication for plugin requests (true/false)
PLUGIN_AUTH_ENABLED=false

# Access Manager service URL (required: the plugin also gets its Midaz, CRM, and Fee tokens here)
PLUGIN_AUTH_ADDRESS=

Quando PLUGIN_AUTH_ENABLED=true, o plugin valida o header Authorization de cada requisição para garantir que:

O token pertence a um usuário ou aplicação autorizada
O token dá acesso ao endpoint e ao método da API solicitados

As credenciais de cliente (CLIENT_ID / CLIENT_SECRET) do Midaz e do CRM são obrigatórias mesmo quando PLUGIN_AUTH_ENABLED=false. As credenciais de tarifas são obrigatórias quando CASHIN_FEE_CALCULATION_TYPE=segment.

Documentação relacionada: Access Manager

3. Midaz

O Midaz é o ledger central de todas as transações Pix que o plugin processa. O plugin lança cada operação de cash-in, cash-out e devolução no Midaz como uma transação por partidas dobradas.

Conexão

# Your organization ID in Midaz
MIDAZ_ORGANIZATION_ID=

# Your ledger ID in Midaz
MIDAZ_LEDGER_ID=

# Midaz Transaction module URL
MIDAZ_TRANSACTION_URL=

# Midaz Onboarding module URL
MIDAZ_ONBOARDING_URL=

# Midaz API credentials (required)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=

Requisitos de ativo

Configure um ativo na sua organização e no seu ledger com estas propriedades:

Propriedade	Valor
Tipo	`currency`
Código	`BRL`

Vincule todas as contas ao seu ledger usando o ativo BRL. O plugin rejeita operações em contas que não seguem essa configuração.

Configuração das contas

Antes de usar o plugin, crie uma conta no Midaz para cada cliente sob o seu ISPB. Use o endpoint Create an Account para criar as contas. Cada conta deve:

Pertencer à organização e ao ledger que você configurou
Usar o ativo BRL

Header X-Account-Id

Muitas operações Pix exigem o header X-Account-Id para identificar qual conta executa a ação. Esse ID corresponde ao ID da conta no ledger do Midaz. Quando você chama um endpoint do plugin, o valor de X-Account-Id diz ao plugin:

Qual conta usar nas operações do ledger
Quais dados de cliente buscar no CRM
Qual saldo validar e atualizar

Como o plugin usa o ID da conta

O plugin usa o ID da conta de formas diferentes conforme o tipo de operação:

Tipo de fluxo	Como o plugin usa o ID da conta
Não transacional (por exemplo, criação de chaves ou QR codes)	Busca os dados do cliente e da conta bancária no CRM
Transacional (por exemplo, pagamentos, devoluções)	Busca os dados do cliente para iniciar o pagamento
	Valida os dados da conta para autorizar o pagamento recebido
	Executa a transação no ledger

Conformidade das contas

O plugin verifica o status da conta no Midaz. Ele recusa uma iniciação de transferência, um cash-out ou uma devolução de uma conta BLOCKED. Ele também recusa um Pix recebido para uma conta que não está ACTIVE. Para impedir liquidações Pix em uma conta específica, bloqueie a conta direto no Midaz. O plugin recebe uma rejeição quando tenta lançar a transação. Documentação relacionada:

4. CRM

O CRM guarda as informações do cliente (titular) e as contas bancárias associadas a ele. Cada conta do Midaz deve ter um titular e uma conta alias correspondentes no CRM para executar operações Pix. O plugin consulta os dados do CRM para:

Registrar e validar chaves Pix
Montar as mensagens de pagamento para o BACEN
Autorizar as transações recebidas
Processar os workflows de devolução e de disputa

Conexão

# CRM base URL
PLUGIN_CRM_BASE_URL=

# CRM API credentials (required)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=

Titulares

Os dados do titular representam o cliente dono da conta. Crie cada titular no CRM antes de executar qualquer operação Pix para esse cliente.

Campos obrigatórios

Campo	Requisito	Exemplo
`name`	No máximo 120 caracteres	`Maria Silva Santos`
`document`	Para `NATURAL_PERSON`, um CPF com 11 dígitos; para `LEGAL_PERSON`, um CNPJ com 14 caracteres, numérico ou alfanumérico	`12345678900`
`type`	Tipo de pessoa (valores de enum do CRM)	`NATURAL_PERSON`

Campos opcionais

Campo	Quando usar
`legalPerson.tradeName`	Quando você associa um nome fantasia aos dados da chave
`addresses.primary`	Obrigatório para criar uma cobrança com vencimento

Documentação relacionada: Criar um titular

Contas alias

As contas alias ligam uma conta do Midaz aos dados bancários dela. Cada conta alias deve incluir as informações bancárias que o ecossistema Pix exige para processar transações.

Campos obrigatórios

Campo	Requisito	Exemplo
`accountId`	ID da conta no Midaz (UUID)	`3c90c3cc-0d44-4b50-8888-8dd25736052a`
`bankingDetails.branch`	Exatamente 4 dígitos	`0001`
`bankingDetails.account`	De 1 a 20 letras maiúsculas ou dígitos, com o dígito verificador	`123456789`
`bankingDetails.type`	Tipo de conta (veja a tabela abaixo)	`CACC`
`bankingDetails.openingDate`	Formato YYYY-MM-DD	`2024-01-15`
`bankingDetails.bankId`	O ISPB da instituição que mantém a conta. Obrigatório para enviar um Pix	`12345678`

O campo bankingDetails.branch deve conter exatamente 4 dígitos. Complete com zeros à esquerda se necessário. Por exemplo, se o número da agência é 1, registre como 0001. O plugin consegue validar a conta no CRM apenas quando o código da agência segue esse formato.

Quando o dígito verificador é uma letra, o DICT o recebe como 0: uma conta guardada como AB1234567X é registrada no DICT como AB12345670. Mantenha o valor original no CRM.

Tipos de conta aceitos

Código	Descrição
`CACC`	Conta corrente
`SLRY`	Conta salário
`SVGS`	Conta poupança
`TRAN`	Conta transacional
`OTHR`	Outra

Você não pode registrar nem reivindicar uma chave Pix para uma conta SLRY. O plugin retorna PIX-0129. Documentação relacionada: Criar uma conta alias

5. Provedor BTG

O BTG é o participante direto que conecta sua instituição à infraestrutura do Pix no BACEN. O BTG fornece as credenciais diretamente quando sua instituição contrata a integração indireta com o BACEN.

Conexão

# BTG API base URL
BTG_BASE_URL=

# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=

mTLS (segurança dos webhooks)

O TLS mútuo (mTLS) valida o certificado do BTG nas requisições de webhook. Ele confirma que os webhooks recebidos vêm do BTG. O seu ingress repassa o certificado que o BTG apresenta no header MTLS_CERTIFICATE_HEADER (padrão X-Client-Cert).

# Enable mTLS validation (true/false)
# Use 'true' in production, 'false' for local development
MTLS_ENABLED=false

# How long to cache the certificate before refreshing
# Format: Go duration (e.g., 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# BTG endpoint that provides the public certificate (required when MTLS_ENABLED=true)
BTG_CERTIFICATE_URL=

# Timeout for certificate fetch requests
# Format: Go duration (e.g., 10s, 30s)
MTLS_HTTP_TIMEOUT=10s

Sempre habilite o mTLS em ambientes de produção. Desabilite apenas durante o desenvolvimento local.

Para apresentar um certificado de cliente nas chamadas do próprio plugin ao BTG, defina BTG_OUTBOUND_MTLS_ENABLED=true com CLIENT_TLS_CERT_FILE e CLIENT_TLS_KEY_FILE. Veja Variáveis de ambiente.

6. Serviço de tarifas (opcional)

Habilite o cálculo de tarifas para cobrar e distribuir tarifas automaticamente nos pagamentos recebidos. Isso é opcional. Se você não configurar, o plugin processa as transações sem cálculo de tarifas.

Conexão

# Fee calculation method (currently only 'segment' is supported)
CASHIN_FEE_CALCULATION_TYPE=

# Fee service URL
FEE_SERVICE_URL=

# Request timeout in milliseconds
FEE_SERVICE_TIMEOUT=5000

# Fee service API credentials (required when CASHIN_FEE_CALCULATION_TYPE=segment)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=

Como funciona

Quando você define CASHIN_FEE_CALCULATION_TYPE=segment, o plugin:

Busca o segmento associado à conta que recebe
Calcula as tarifas aplicáveis antes de processar a transação no Midaz
Distribui o pagamento recebido conforme as regras de pacote ligadas a esse segmento

Passos de configuração

Crie segmentos no Midaz: defina os segmentos de conta que determinam as regras de tarifa
Configure pacotes no Fees Engine: ligue cada segmento às regras de cálculo de tarifa dele
Atribua segmentos às contas: crie ou atualize contas do Midaz com o ID de segmento adequado

Documentação relacionada:

Conciliação do DICT (VSync)

O VSync concilia seus dados locais do DICT com o BACEN processando todos os eventos do dia relacionados a chaves. Ele mantém seu estado local consistente com os registros oficiais do BACEN.

# Write block window (24-hour format, America/Sao_Paulo time)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Network allowed to write Pix keys during the window
RECONCILIATION_INTERNAL_CIDR=

Durante a janela, a API rejeita as requisições de criação, atualização e exclusão de chaves Pix para evitar inconsistências de dados com o BACEN. Planeje a janela de bloqueio de escrita para períodos de baixo tráfego.

Configuração do cache Redis

O VSync usa o Redis para fazer cache dos vínculos do BTG/DICT e dos titulares do CRM durante a conciliação. Nos deploys com Helm, o REDIS_HOST padrão aponta para o Valkey embutido, então uma instalação padrão não exige configuração extra.

# Connection (always used)
REDIS_HOST=<valkey-host>:6379
REDIS_MASTER_NAME=
REDIS_DB=0
REDIS_PROTOCOL=3

# Connection pool and retries (always used)
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2
REDIS_MAX_RETRIES=3
REDIS_MIN_RETRY_BACKOFF=8
REDIS_MAX_RETRY_BACKOFF=512

# Authentication (optional — only used if set)
REDIS_PASSWORD=

# TLS (optional — only used if REDIS_TLS=true)
REDIS_TLS=false
REDIS_CA_CERT=

# GCP IAM authentication (optional — only used if REDIS_USE_GCP_IAM=true)
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
REDIS_TOKEN_LIFETIME=60
REDIS_TOKEN_REFRESH_DURATION=45

# VSync cache TTLs (always used)
CACHE_BTG_ENTRY_TTL=30m
CACHE_CRM_HOLDER_TTL=30m

Conexão (sempre usada)

Var	Tipo	Padrão	Descrição
`REDIS_HOST`	string (host:porta, CSV)	Valkey embutido (Helm chart)	Endereço(s) do Redis. Vários endereços separados por vírgula definem a topologia Sentinel/Cluster.
`REDIS_MASTER_NAME`	string	`""`	Nome do master no Sentinel. Vazio = standalone (conexão direta).
`REDIS_DB`	int	`0`	Número do banco lógico do Redis.
`REDIS_PROTOCOL`	int	`3`	Versão do protocolo RESP (2 ou 3).

Pool de conexões e novas tentativas (sempre usados)

Var	Tipo	Padrão	Descrição
`REDIS_POOL_SIZE`	int	`10`	Número máximo de conexões no pool.
`REDIS_MIN_IDLE_CONNS`	int	`0`	Número mínimo de conexões ociosas mantidas prontas.
`REDIS_READ_TIMEOUT`	int (segundos)	`3`	Timeout da operação de leitura.
`REDIS_WRITE_TIMEOUT`	int (segundos)	`3`	Timeout da operação de escrita.
`REDIS_DIAL_TIMEOUT`	int (segundos)	`5`	Timeout para estabelecer a conexão inicial.
`REDIS_POOL_TIMEOUT`	int (segundos)	`2`	Timeout de espera por uma conexão livre do pool.
`REDIS_MAX_RETRIES`	int	`3`	Número máximo de novas tentativas para um comando com falha.
`REDIS_MIN_RETRY_BACKOFF`	int (milissegundos)	`8`	Atraso mínimo entre as novas tentativas.
`REDIS_MAX_RETRY_BACKOFF`	int (segundos)	`512`	Atraso máximo entre as novas tentativas. Nota: armazenado em segundos no código (unidade diferente da do mínimo).

Autenticação (opcional, usada apenas se definida)

Var	Tipo	Padrão	Descrição
`REDIS_PASSWORD`	string (segredo)	`""`	Senha do Redis. Vazio = sem autenticação por senha.

TLS (opcional, usado apenas se `REDIS_TLS=true`)

Var	Tipo	Padrão	Descrição
`REDIS_TLS`	bool	`false`	Habilita o TLS. Obrigatório `true` em `DEPLOYMENT_MODE=saas` (validado na inicialização).
`REDIS_CA_CERT`	string (PEM base64)	`""`	Certificado da CA (base64) para validar o servidor quando o TLS está ativo.

Autenticação IAM da GCP (opcional, usada apenas se `REDIS_USE_GCP_IAM=true`)

Var	Tipo	Padrão	Descrição
`REDIS_USE_GCP_IAM`	bool	`false`	Habilita a autenticação IAM da GCP (Memorystore) em vez de senha.
`REDIS_SERVICE_ACCOUNT`	string	`""`	Conta de serviço da GCP que gera o token de acesso.
`GOOGLE_APPLICATION_CREDENTIALS`	string	`""`	Credenciais da GCP (um caminho de arquivo ou o conteúdo JSON) para gerar o token.
`REDIS_TOKEN_LIFETIME`	int (minutos)	`60`	Tempo de vida do token IAM gerado.
`REDIS_TOKEN_REFRESH_DURATION`	int (minutos)	`45`	Intervalo de renovação do token (deve ser menor que o tempo de vida).

TTLs do cache do VSync (sempre usados)

Var	Tipo	Padrão	Descrição
`CACHE_BTG_ENTRY_TTL`	duração Go	`30m`	TTL de cache dos vínculos do BTG/DICT no Redis. Valor negativo volta ao padrão.
`CACHE_CRM_HOLDER_TTL`	duração Go	`30m`	TTL de cache dos titulares do CRM no Redis. Valor negativo volta ao padrão.

8. Segurança dos webhooks internos

O plugin usa um canal de comunicação interno entre os serviços Worker e Application. As assinaturas HMAC-SHA256 protegem esse canal contra adulteração e ataques de replay.

# Shared secret for signing internal requests (Worker -> Application)
# Must be at least 32 characters
# Generate one with: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validate signatures on incoming internal webhooks (true/false)
# Always use 'true' in production
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Maximum age (in seconds) for request timestamps before rejection
# Default: 300 (5 minutes)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300

Use exatamente o mesmo valor de INTERNAL_WEBHOOK_SECRET nos serviços Application e Worker. Uma divergência faz o plugin rejeitar todos os webhooks internos.

9. Camadas de worker

O plugin opera com quatro workers, cada um cuidando de uma parte diferente do ciclo de vida do Pix. Cada worker roda como um serviço separado ao lado da aplicação principal.

Worker de entrada

A Application recebe as notificações de webhook do BTG e as armazena. Depois, o worker de entrada entrega cada notificação aos endpoints internos da Application para processamento.

# Application URL for internal webhooks
WEBHOOK_INBOUND_BASE_URL=

# Shared secret for signing requests (must match the application's INTERNAL_WEBHOOK_SECRET)
INTERNAL_WEBHOOK_SECRET=

Worker de saída

O worker de saída envia as notificações de evento do plugin para a sua aplicação por webhooks. É assim que o seu sistema fica informado sobre os eventos Pix (transferências, devoluções, reivindicações, disputas).

Prioridade de resolução de URL

O plugin resolve as URLs de webhook nesta ordem, usando a primeira que corresponder:

URL de entidade: uma URL específica do tipo de evento (por exemplo, WEBHOOK_DICT_CLAIM_URL)
URL de fluxo: uma URL para a categoria mais ampla (por exemplo, WEBHOOK_DICT_URL)
URL padrão: a URL de fallback (WEBHOOK_DEFAULT_URL)

# Default fallback URL
WEBHOOK_DEFAULT_URL=

# DICT-related events
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# MED 2.0 Funds Recovery events (DICT flow)
# These route under the DICT flow and fall back to WEBHOOK_DICT_URL,
# then WEBHOOK_DEFAULT_URL, if no entity-specific URL is set.
WEBHOOK_DICT_FUNDS_RECOVERY_URL=
WEBHOOK_DICT_FUNDS_RECOVERY_EVENTS_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=

Cada entidade precisa da própria variável WEBHOOK_<FLOW>_<ENTITY>_*. Veja Webhooks. Para tipos de evento de webhook, payloads, comportamento de novas tentativas e boas práticas, veja o guia de Webhooks.

Worker de conciliação

O worker de conciliação precisa das mesmas credenciais da camada Application para estes serviços:

CRM: URL e credenciais
BTG: URL e credenciais
Midaz: ID da organização

Ele também chama a API da Application com as próprias credenciais de cliente: PLUGIN_PIX_BTG_BASE_URL, PLUGIN_PIX_BTG_CLIENT_ID e PLUGIN_PIX_BTG_CLIENT_SECRET, com o endpoint de token em PLUGIN_AUTH_URL. Veja as seções correspondentes acima para detalhes de cada configuração. Você pode restringir quando o worker opera configurando uma janela de horário específica. Isso ajuda a agendar as tarefas de conciliação fora do horário de pico. O plugin aceita janelas de horário que atravessam a meia-noite.

# Start time in HH:MM format (24-hour, BRT). Example: "23:00" for 11 PM BRT
RECONCILIATION_START_TIME=

# End time in HH:MM format (24-hour, BRT). Example: "05:00" for 5 AM BRT
RECONCILIATION_END_TIME=

Se você deixar os dois campos vazios, o worker roda sem restrição de horário (24/7).

O worker sempre interpreta a janela de conciliação no fuso America/Sao_Paulo (BRT), qualquer que seja o relógio do contêiner ou a variável TZ. O worker embute os dados de fuso horário da IANA. A janela continua alinhada com o bloqueio de escrita do DICT do BACEN, mesmo em imagens mínimas ou distroless. Você não precisa definir TZ.

Worker de agendamento

O worker de agendamento executa os pagamentos Pix agendados quando vencem. Ele vem desligado por padrão. Ele chama a API da Application com as mesmas variáveis de credenciais de cliente do worker de conciliação.

# Turn the worker on (default false)
SCHEDULE_WORKER_ENABLED=true

# Application API URL
SCHEDULE_APP_BASE_URL=

# Token endpoint and the worker's client credentials
PLUGIN_AUTH_URL=
PLUGIN_PIX_BTG_CLIENT_ID=
PLUGIN_PIX_BTG_CLIENT_SECRET=

Os endpoints de cashout e de devolução do Pix Indireto aceitam idempotência pelo header de requisição X-Idempotency. O plugin guarda uma resposta reutilizável por IDEMPOTENCY_RESPONSE_TTL segundos (padrão 86400, 24 horas). Para estratégias de nova tentativa e detalhes de implementação, veja Novas tentativas e idempotência.

10. Observabilidade (OpenTelemetry)

O plugin vem com instrumentação OpenTelemetry (traces, métricas e logs) nas camadas Application e Worker. O plugin rastreia os fluxos Pix de ponta a ponta: transferências (cash-in e cash-out), devoluções, webhooks de entrada e de saída, conciliação do DICT e liquidação intra-PSP. Você pode seguir um único pagamento pelas chamadas ao plugin, ao Midaz, ao CRM e ao BTG. A telemetria vem desabilitada por padrão. Habilite e aponte o exporter OTLP para o seu collector:

# Master switch — telemetry is off until this is true
ENABLE_TELEMETRY=true

# Resource attributes that identify this service in your backend
OTEL_RESOURCE_SERVICE_NAME=plugin-br-pix-indirect-btg
OTEL_RESOURCE_SERVICE_VERSION=${VERSION}
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=${ENV_NAME}

# OTLP collector endpoint (gRPC, default port 4317)
OTEL_EXPORTER_OTLP_ENDPOINT_PORT=4317
OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:${OTEL_EXPORTER_OTLP_ENDPOINT_PORT}

Quando ENABLE_TELEMETRY=true, OTEL_EXPORTER_OTLP_ENDPOINT é obrigatório. Defina as mesmas variáveis do OTel na Application e em cada Worker para os traces se correlacionarem entre os serviços.

Exporter: gRPC e TLS

O plugin exporta traces, métricas e logs por OTLP/gRPC. O esquema do endpoint controla a segurança do transporte:

Valor do endpoint	Transporte	Segurança
`https://collector:4317`	gRPC sobre TLS	Seguro (recomendado para produção)
`http://collector:4317`	gRPC, texto puro	Inseguro (inferido automaticamente)
`collector:4317` (`host:port` puro)	gRPC, texto puro	Inseguro (inferido automaticamente)

Quando OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT é production ou prod, o plugin se recusa a iniciar com um exporter inseguro. Use um endpoint https://, ou defina ALLOW_INSECURE_OTEL com uma justificativa curta apenas quando você controla totalmente o caminho de rede até o collector.

Exemplo: endpoint do collector

Aponte o plugin para qualquer collector compatível com OTLP (o OpenTelemetry Collector, Grafana LGTM/Alloy etc.) que escute na porta gRPC:

# Local / development (plaintext gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Production (TLS gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317

O collector então distribui a telemetria para os seus backends de tracing, métricas e logs.

11. Health e readiness

A Application e os Workers expõem uma probe de readiness em /readyz (ao lado das verificações padrão de liveness). Aponte a probe de readiness do seu orquestrador para esse endpoint para o tráfego ser roteado apenas quando o serviço e as dependências dele estiverem prontos.

Propósito da transferência (MED 2.0)

O endpoint de cashout aceita um header opcional X-Purpose que identifica o propósito da transação, usado nas transferências de devolução do MED 2.0. Quando omitido, o padrão é TRANSFER.

# Example: a MED 2.0 refund transfer
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND

Para os valores aceitos, veja Transferências.

Próximos passos

Com o plugin configurado, você pode começar a operar o Pix.

Webhooks: tipos de evento, payloads, novas tentativas e boas práticas
MED 2.0: Recuperação de Fundos: recuperação de fraude entre contas e o header X-Purpose
Operações de devolução: devoluções parciais distribuídas e desbloqueio
Transferências intra-PSP: liquidação P2P interna e reporte TRCK002
Domínios principais: DICT: entender a gestão de chaves Pix
Domínios principais: transações: fluxos e ciclo de vida das transações
Domínios principais: QR Codes: geração de QR code estático e dinâmico
Referência da API: documentação completa da API para as operações de DICT, reivindicações, transações, QR Codes e MED

​Pré-requisitos

​1. Licença

​2. Access Manager (opcional)

​3. Midaz

​Conexão

​Requisitos de ativo

​Configuração das contas

​Header X-Account-Id

​Como o plugin usa o ID da conta

​Conformidade das contas

​4. CRM

​Conexão

​Titulares

​Campos obrigatórios

​Campos opcionais

​Contas alias

​Campos obrigatórios

​Tipos de conta aceitos

​5. Provedor BTG

​Conexão

​mTLS (segurança dos webhooks)

​6. Serviço de tarifas (opcional)

​Conexão

​Como funciona

​Passos de configuração

​ Conciliação do DICT (VSync)

​Configuração do cache Redis

​Conexão (sempre usada)

​Pool de conexões e novas tentativas (sempre usados)

​Autenticação (opcional, usada apenas se definida)

​TLS (opcional, usado apenas se REDIS_TLS=true)

​Autenticação IAM da GCP (opcional, usada apenas se REDIS_USE_GCP_IAM=true)

​TTLs do cache do VSync (sempre usados)

​8. Segurança dos webhooks internos

​9. Camadas de worker

​Worker de entrada

​Worker de saída

​Prioridade de resolução de URL

​Worker de conciliação

​Worker de agendamento

​10. Observabilidade (OpenTelemetry)

​Exporter: gRPC e TLS

​Exemplo: endpoint do collector

​11. Health e readiness

​Propósito da transferência (MED 2.0)

​Próximos passos

Pré-requisitos

1. Licença

2. Access Manager (opcional)

3. Midaz

Conexão

Requisitos de ativo

Configuração das contas

Header X-Account-Id

Como o plugin usa o ID da conta

Conformidade das contas

4. CRM

Conexão

Titulares

Campos obrigatórios

Campos opcionais

Contas alias

Campos obrigatórios

Tipos de conta aceitos

5. Provedor BTG

Conexão

mTLS (segurança dos webhooks)

6. Serviço de tarifas (opcional)

Conexão

Como funciona

Passos de configuração

Conciliação do DICT (VSync)

Configuração do cache Redis

Conexão (sempre usada)

Pool de conexões e novas tentativas (sempre usados)

Autenticação (opcional, usada apenas se definida)

TLS (opcional, usado apenas se `REDIS_TLS=true`)

Autenticação IAM da GCP (opcional, usada apenas se `REDIS_USE_GCP_IAM=true`)

TTLs do cache do VSync (sempre usados)

8. Segurança dos webhooks internos

9. Camadas de worker

Worker de entrada

Worker de saída

Prioridade de resolução de URL

Worker de conciliação

Worker de agendamento

10. Observabilidade (OpenTelemetry)

Exporter: gRPC e TLS

Exemplo: endpoint do collector

11. Health e readiness

Propósito da transferência (MED 2.0)

Próximos passos