Pular para o conteúdo principal
O Plugin Pix Indireto (BTG) se conecta a múltiplos serviços da Lerian e provedores externos para processar pagamentos Pix. A configuração envolve conectar o plugin a cada serviço e preparar os dados que esses serviços precisam para operar. O plugin opera em duas camadas principais — uma Application que expõe a API Pix e processa a lógica de negócios, e um conjunto de Workers que tratam webhooks de entrada do BTG, entrega de eventos de saída para o seu sistema e conciliação DICT com o BACEN. Ambas as camadas compartilham a mesma configuração base (licença, Midaz, CRM, BTG), mas possuem configurações específicas de cada serviço.

​
Pré-requisitos

Antes de começar, certifique-se de que você tem:
  • Seu ISPB (Identificador do Sistema de Pagamentos Brasileiro) — o identificador de 8 dígitos derivado do CNPJ da sua instituição
  • Acesso às suas instâncias de Midaz e CRM (implantadas e em execução)
  • Acesso aos serviços do provedor BTG (o BTG fornece as credenciais)
# ISPB da sua instituição (8 dígitos)
PIX_ISPB=12345678

​
1. Licença

O plugin é uma solução enterprise e requer uma licença válida para operar. A Lerian fornece a chave de licença durante o onboarding. 
# Chave de licença fornecida pela Lerian
LICENSE_KEY=

# IDs de organização autorizados (separados por vírgula)
ORGANIZATION_IDS=
Documentação relacionada: Licença Lerian

​
2. Access Manager (opcional)

O Access Manager gerencia a autenticação do plugin. Quando habilitado, ele valida todas as requisições de entrada antes que cheguem à API do plugin. 
# Exigir autenticação para todas as requisições do plugin (true/false)
PLUGIN_AUTH_ENABLED=false

# URL do serviço Access Manager
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 concede acesso ao endpoint e método da API requisitados
Você só precisa fornecer credenciais de cliente (CLIENT_ID / CLIENT_SECRET) para os serviços Midaz, CRM e Fee se esses serviços também tiverem autenticação via Access Manager habilitada.
Documentação relacionada: Access Manager

​
3. Midaz

O Midaz é o ledger principal para todas as transações Pix que o plugin processa. O plugin registra cada operação de cash-in, cash-out e devolução no Midaz como uma transação de partida dobrada.

​
Conexão

# ID da sua organização no Midaz
MIDAZ_ORGANIZATION_ID=

# ID do seu ledger no Midaz
MIDAZ_LEDGER_ID=

# URL do módulo de Transações do Midaz
MIDAZ_TRANSACTION_URL=

# URL do módulo de Onboarding do Midaz
MIDAZ_ONBOARDING_URL=

# Credenciais da API do Midaz (obrigatórias se o Midaz tiver autenticação habilitada)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=

​
Requisitos de asset

Configure um asset na sua organização e ledger com estas propriedades:
PropriedadeValor
Typecurrency
CodeBRL
Vincule todas as contas ao seu ledger usando o asset BRL. O plugin rejeita operações em contas que não correspondem a esta configuração.

​
Criação de 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 configurar as contas. Cada conta deve:
  • Pertencer à organização e ao ledger configurados
  • Usar o asset BRL

​
Header X-Account-Id

Muitas operações Pix exigem o header X-Account-Id para identificar qual conta está realizando a ação. Este ID corresponde ao ID da conta no ledger do Midaz. Quando você chama um endpoint do plugin, o valor de X-Account-Id indica ao plugin:
  • Qual conta usar para operações no 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 forma diferente dependendo do tipo de operação:
Tipo de fluxoComo o plugin usa o ID da conta
Não transacional (ex.: criação de chaves ou QR codes)Busca dados de cliente e conta bancária no CRM
Transacional (ex.: pagamentos, devoluções)Busca dados de cliente para iniciação de pagamento
Valida dados da conta para autorização de pagamento recebido
Executa a transação no ledger

​
Compliance de conta

O plugin não aplica restrições de nível de negócio em contas, como contas bloqueadas ou suspensas. Sua aplicação é responsável por validar o status da conta antes de chamar o plugin. Para impedir liquidações Pix em uma conta específica, bloqueie-a diretamente no Midaz. O plugin recebe uma rejeição quando tenta registrar a transação. Documentação relacionada:

​
4. CRM

O CRM armazena informações de clientes (holders) e suas contas bancárias associadas. Cada conta no Midaz deve ter um holder e uma alias account correspondentes no CRM para realizar operações Pix. O plugin consulta dados do CRM para:
  • Registrar e validar chaves Pix
  • Construir mensagens de pagamento para o BACEN
  • Autorizar transações recebidas
  • Processar fluxos de devolução e disputa

​
Conexão

# URL base do CRM
PLUGIN_CRM_BASE_URL=

# Credenciais da API do CRM (obrigatórias se o CRM tiver autenticação habilitada)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=

​
Holders

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

​
Campos obrigatórios

CampoRequisitoExemplo
nameMáximo de 120 caracteresMaria Silva Santos
documentPara NATURAL_PERSON, um CPF com 11 dígitos; para LEGAL_PERSON, um CNPJ com 14 dígitos (apenas números)12345678900
typeTipo de pessoa (valores enum do CRM)NATURAL_PERSON

​
Campos opcionais

CampoQuando usar
legalPerson.tradeNameQuando associar um nome fantasia aos dados da chave
addresses.primaryObrigatório para criação de cobrança com vencimento
Documentação relacionada: Criar um holder

​
Alias accounts

As alias accounts vinculam uma conta do Midaz aos seus dados bancários. Cada alias account deve incluir as informações bancárias que o ecossistema Pix exige para processamento de transações.

​
Campos obrigatórios

CampoRequisitoExemplo
accountIdID da conta no Midaz (UUID)3c90c3cc-0d44-4b50-8888-8dd25736052a
bankingDetails.branchExatamente 4 dígitos0001
bankingDetails.account1 a 20 dígitos123456789
bankingDetails.typeTipo de conta (veja tabela abaixo)CACC
bankingDetails.openingDateFormato AAAA-MM-DD2024-01-15
O campo bankingDetails.branch deve conter exatamente 4 dígitos. Preencha com zeros à esquerda se necessário. Por exemplo, se o número da agência é 1, registre como 0001. O plugin só consegue validar a conta no CRM quando o código da agência segue este formato.

​
Tipos de conta suportados

CódigoDescrição
CACCConta corrente
SLRYConta salário
SVGSConta poupança
TRANConta de transação
Documentação relacionada: Criar uma alias account

​
5. Provedor BTG

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

​
Conexão

# URL base da API do BTG
BTG_BASE_URL=

# Credenciais da API do BTG
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=

​
mTLS (segurança de webhook)

O Mutual TLS (mTLS) adiciona uma camada extra de segurança ao validar o certificado do BTG nas requisições de webhook. Isso garante que os webhooks recebidos realmente se originam do BTG. 
# Habilitar validação mTLS (true/false)
# Use 'true' em produção, 'false' para desenvolvimento local
MTLS_ENABLED=false

# Tempo de cache do certificado antes de atualizar
# Formato: duração Go (ex.: 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# Endpoint do BTG que fornece o certificado público para validação de assinatura
BTG_CERTIFICATE_URL=

# Timeout para requisições de busca do certificado
# Formato: duração Go (ex.: 10s, 30s)
MTLS_HTTP_TIMEOUT=10s
Sempre habilite o mTLS em ambientes de produção. Desabilite-o apenas durante o desenvolvimento local.

​
6. Serviço de tarifas (opcional)

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

​
Conexão

# Método de cálculo de tarifa (atualmente apenas 'segment' é suportado)
CASHIN_FEE_CALCULATION_TYPE=

# URL do serviço de tarifas
FEE_SERVICE_URL=

# Timeout da requisição em milissegundos
FEE_SERVICE_TIMEOUT=5000

# Credenciais da API do serviço de tarifas (obrigatórias se o serviço tiver autenticação habilitada)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=

​
Como funciona

Quando você define CASHIN_FEE_CALCULATION_TYPE=segment, o plugin:
  1. Busca o segmento associado à conta recebedora
  2. Calcula as tarifas aplicáveis antes de processar a transação no Midaz
  3. Distribui o pagamento recebido de acordo com as regras de pacote vinculadas a esse segmento

​
Passos de configuração

  1. Crie segmentos no Midaz — Defina os segmentos de conta que determinam as regras de tarifa
  2. Configure pacotes no Fee Engine — Vincule cada segmento às suas regras de cálculo de tarifa
  3. Atribua segmentos às contas — Crie ou atualize contas no Midaz com o ID de segmento apropriado
Documentação relacionada:

​
7. Conciliação DICT (VSync)

O VSync concilia seus dados DICT locais com o BACEN processando todos os eventos relacionados a chaves do dia. Isso garante que seu estado local permaneça consistente com os registros autoritativos do BACEN. 
# Janela de bloqueio de escrita (formato 24 horas, UTC)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Faixa de rede permitida para serviços de conciliação
RECONCILIATION_INTERNAL_CIDR=
Durante a conciliação, o banco de dados bloqueia temporariamente operações de escrita para evitar inconsistências de dados com o BACEN. Planeje a janela de bloqueio de escrita durante períodos de baixo tráfego.
A faixa CIDR restringe quais redes podem acionar a conciliação. O plugin rejeita automaticamente requisições de fora dessa faixa.

​
8. Segurança interna de webhooks

O plugin usa um canal de comunicação interno entre os serviços Worker e Application. Assinaturas HMAC-SHA256 protegem este canal para evitar adulteração e ataques de replay. 
# Segredo compartilhado para assinar requisições internas (Worker -> Application)
# Deve ter pelo menos 32 caracteres
# Gere um com: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validar assinaturas em webhooks internos recebidos (true/false)
# Sempre use 'true' em produção
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Idade máxima (em segundos) para timestamps de requisição antes da rejeição
# Padrão: 300 (5 minutos)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300
Use exatamente o mesmo valor de INTERNAL_WEBHOOK_SECRET nos serviços Application e Worker. Uma incompatibilidade faz o plugin rejeitar todos os webhooks internos.

​
9. Camadas de workers

O plugin opera com três camadas de workers, cada uma tratando uma parte diferente do ciclo de vida do Pix. Todos os workers executam como serviços separados junto à aplicação principal.

​
Worker de entrada

O worker de entrada recebe notificações de webhook do BTG e as encaminha para sua aplicação para processamento. 
# URL onde a aplicação recebe webhooks internos
WEBHOOK_INBOUND_BASE_URL=

# Segredo compartilhado para assinar requisições (deve corresponder ao INTERNAL_WEBHOOK_SECRET da aplicação)
INTERNAL_WEBHOOK_SECRET=

​
Worker de saída

O worker de saída envia notificações de eventos do plugin para sua aplicação via webhooks. É assim que seu sistema se mantém informado sobre eventos Pix (transferências, devoluções, reivindicações, disputas).

​
Prioridade de resolução de URL

O plugin resolve URLs de webhook nesta ordem, usando a primeira correspondência:
  1. URL da entidade — Uma URL específica para o tipo de evento (ex.: WEBHOOK_DICT_CLAIM_URL)
  2. URL do fluxo — Uma URL para a categoria mais ampla (ex.: WEBHOOK_DICT_URL)
  3. URL padrão — A URL de fallback (WEBHOOK_DEFAULT_URL)
# URL de fallback padrão
WEBHOOK_DEFAULT_URL=

# Eventos relacionados ao DICT
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# Eventos de devolução
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Eventos de transferência
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=
Você pode começar apenas com WEBHOOK_DEFAULT_URL para receber todos os eventos em um único endpoint, e gradualmente dividir em URLs específicas por entidade conforme seu sistema evolui.
Para um mergulho profundo em tipos de eventos de webhook, payloads, comportamento de retentativa 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
Consulte as seções correspondentes acima para detalhes de cada configuração. Você pode restringir quando o worker opera configurando uma janela de tempo específica. Isso é especialmente útil para agendar tarefas de conciliação durante horários de baixo tráfego. O plugin suporta janelas de tempo que cruzam a meia-noite. 
# Horário de início no formato HH:MM (24 horas). Exemplo: "23:00" para 23h
RECONCILIATION_START_TIME=

# Horário de término no formato HH:MM (24 horas). Exemplo: "05:00" para 5h
RECONCILIATION_END_TIME=
Se você deixar ambos os campos vazios, o worker executa sem restrições de horário — 24/7.

​
Próximos passos

Com o plugin totalmente configurado, você está pronto para começar a operar o Pix. Explore estes tópicos para aprofundar: