Saltar al contenido principal
El Plugin Pix Indirecto (BTG) se conecta a múltiples servicios de Lerian y proveedores externos para procesar pagos Pix. La configuración implica conectar el plugin a cada servicio y preparar los datos que esos servicios necesitan para operar. El plugin opera en dos capas principales — una Application que expone la API Pix y procesa la lógica de negocio, y un conjunto de Workers que manejan webhooks de entrada de BTG, entrega de eventos de salida a su sistema y conciliación DICT con BACEN. Ambas capas comparten la misma configuración base (licencia, Midaz, CRM, BTG) pero tienen sus propias configuraciones específicas de servicio.

​
Prerrequisitos

Antes de comenzar, asegúrese de tener:
  • Su ISPB (Identificador do Sistema de Pagamentos Brasileiro) — el identificador de 8 dígitos derivado del CNPJ de su institución
  • Acceso a sus instancias de Midaz y CRM (desplegadas y en ejecución)
  • Acceso a los servicios del proveedor BTG (BTG proporciona las credenciales)
# ISPB de su institución (8 dígitos)
PIX_ISPB=12345678

​
1. Licencia

El plugin es una solución enterprise y requiere una licencia válida para operar. Lerian proporciona la clave de licencia durante el onboarding. 
# Clave de licencia proporcionada por Lerian
LICENSE_KEY=

# IDs de organización autorizados (separados por coma)
ORGANIZATION_IDS=
Documentación relacionada: Licencia Lerian

​
2. Access Manager (opcional)

Access Manager gestiona la autenticación del plugin. Cuando está habilitado, valida todas las solicitudes de entrada antes de que lleguen a la API del plugin. 
# Requerir autenticación para todas las solicitudes del plugin (true/false)
PLUGIN_AUTH_ENABLED=false

# URL del servicio Access Manager
PLUGIN_AUTH_ADDRESS=
Cuando PLUGIN_AUTH_ENABLED=true, el plugin valida el header Authorization de cada solicitud para asegurar que:
  • El token pertenece a un usuario o aplicación autorizada
  • El token otorga acceso al endpoint y método de API solicitados
Solo necesita proporcionar credenciales de cliente (CLIENT_ID / CLIENT_SECRET) para los servicios Midaz, CRM y Fee si esos servicios también tienen autenticación de Access Manager habilitada.
Documentación relacionada: Access Manager

​
3. Midaz

Midaz es el Ledger principal para todas las transacciones Pix que el plugin procesa. El plugin registra cada operación de cash-in, cash-out y devolución en Midaz como una transacción de partida doble.

​
Conexión

# ID de su organización en Midaz
MIDAZ_ORGANIZATION_ID=

# ID de su Ledger en Midaz
MIDAZ_LEDGER_ID=

# URL del módulo de Transacciones de Midaz
MIDAZ_TRANSACTION_URL=

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

# Credenciales de la API de Midaz (requeridas si Midaz tiene autenticación habilitada)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=

​
Requisitos de asset

Configure un asset en su organización y Ledger con estas propiedades:
PropiedadValor
Typecurrency
CodeBRL
Vincule todas las cuentas a su Ledger usando el asset BRL. El plugin rechaza operaciones en cuentas que no coinciden con esta configuración.

​
Creación de cuentas

Antes de usar el plugin, cree una cuenta en Midaz para cada cliente bajo su ISPB. Use el endpoint Create an Account para configurar las cuentas. Cada cuenta debe:
  • Pertenecer a su organización y Ledger configurados
  • Usar el asset BRL

​
Header X-Account-Id

Muchas operaciones Pix requieren el header X-Account-Id para identificar qué cuenta está realizando la acción. Este ID corresponde al ID de la cuenta en el Ledger de Midaz. Cuando usted llama a un endpoint del plugin, el valor de X-Account-Id indica al plugin:
  • Qué cuenta usar para operaciones en el ledger
  • Qué datos de cliente buscar en el CRM
  • Qué saldo validar y actualizar

​
Cómo el plugin usa el ID de cuenta

El plugin usa el ID de cuenta de forma diferente según el tipo de operación:
Tipo de flujoCómo el plugin usa el ID de cuenta
No transaccional (ej.: creación de claves o QR codes)Busca datos de cliente y cuenta bancaria en el CRM
Transaccional (ej.: pagos, devoluciones)Busca datos de cliente para iniciación de pago
Valida datos de cuenta para autorización de pago recibido
Ejecuta la transacción en el Ledger

​
Compliance de cuenta

El plugin no aplica restricciones de nivel de negocio en cuentas, como cuentas bloqueadas o suspendidas. Su aplicación es responsable de validar el estado de la cuenta antes de llamar al plugin. Para evitar liquidaciones Pix en una cuenta específica, bloquéela directamente en Midaz. El plugin recibe un rechazo cuando intenta registrar la transacción. Documentación relacionada:

​
4. CRM

El CRM almacena información de clientes (holders) y sus cuentas bancarias asociadas. Cada cuenta en Midaz debe tener un holder y una alias account correspondientes en el CRM para realizar operaciones Pix. El plugin consulta datos del CRM para:
  • Registrar y validar claves Pix
  • Construir mensajes de pago para BACEN
  • Autorizar transacciones recibidas
  • Procesar flujos de devolución y disputa

​
Conexión

# URL base del CRM
PLUGIN_CRM_BASE_URL=

# Credenciales de la API del CRM (requeridas si el CRM tiene autenticación habilitada)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=

​
Holders

Los datos de holder representan al cliente que es dueño de la cuenta. Cree cada holder en el CRM antes de ejecutar cualquier operación Pix para ese cliente.

​
Campos obligatorios

CampoRequisitoEjemplo
nameMáximo 120 caracteresMaria Silva Santos
documentPara NATURAL_PERSON, un CPF con 11 dígitos; para LEGAL_PERSON, un CNPJ con 14 dígitos (solo números)12345678900
typeTipo de persona (valores enum del CRM)NATURAL_PERSON

​
Campos opcionales

CampoCuándo usar
legalPerson.tradeNameAl asociar un nombre comercial con los datos de la clave
addresses.primaryRequerido para creación de cobro con vencimiento
Documentación relacionada: Crear un holder

​
Alias accounts

Las alias accounts vinculan una cuenta de Midaz a sus datos bancarios. Cada alias account debe incluir la información bancaria que el ecosistema Pix requiere para el procesamiento de transacciones.

​
Campos obligatorios

CampoRequisitoEjemplo
accountIdID de cuenta en Midaz (UUID)3c90c3cc-0d44-4b50-8888-8dd25736052a
bankingDetails.branchExactamente 4 dígitos0001
bankingDetails.account1 a 20 dígitos123456789
bankingDetails.typeTipo de cuenta (ver tabla abajo)CACC
bankingDetails.openingDateFormato AAAA-MM-DD2024-01-15
El campo bankingDetails.branch debe contener exactamente 4 dígitos. Rellene con ceros a la izquierda si es necesario. Por ejemplo, si el número de sucursal es 1, regístrelo como 0001. El plugin solo puede validar la cuenta en el CRM cuando el código de sucursal sigue este formato.

​
Tipos de cuenta soportados

CódigoDescripción
CACCCuenta corriente
SLRYCuenta de salario
SVGSCuenta de ahorro
TRANCuenta de transacción
Documentación relacionada: Crear una alias account

​
5. Proveedor BTG

BTG es el participante directo que conecta su institución a la infraestructura Pix de BACEN. BTG proporciona las credenciales directamente cuando su institución se registra para integración indirecta con BACEN.

​
Conexión

# URL base de la API de BTG
BTG_BASE_URL=

# Credenciales de la API de BTG
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=

​
mTLS (seguridad de webhook)

Mutual TLS (mTLS) agrega una capa extra de seguridad al validar el certificado de BTG en las solicitudes de webhook. Esto asegura que los webhooks recibidos realmente se originan en BTG. 
# Habilitar validación mTLS (true/false)
# Use 'true' en producción, 'false' para desarrollo local
MTLS_ENABLED=false

# Tiempo de caché del certificado antes de actualizar
# Formato: duración Go (ej.: 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# Endpoint de BTG que proporciona el certificado público para validación de firma
BTG_CERTIFICATE_URL=

# Timeout para solicitudes de obtención del certificado
# Formato: duración Go (ej.: 10s, 30s)
MTLS_HTTP_TIMEOUT=10s
Siempre habilite mTLS en ambientes de producción. Deshabilítelo solo durante el desarrollo local.

​
6. Servicio de tarifas (opcional)

Habilite el cálculo de tarifas para cobrar y distribuir tarifas automáticamente en pagos recibidos. Esto es opcional — si no lo configura, el plugin procesa transacciones sin cálculo de tarifas.

​
Conexión

# Método de cálculo de tarifa (actualmente solo 'segment' es soportado)
CASHIN_FEE_CALCULATION_TYPE=

# URL del servicio de tarifas
FEE_SERVICE_URL=

# Timeout de solicitud en milisegundos
FEE_SERVICE_TIMEOUT=5000

# Credenciales de la API del servicio de tarifas (requeridas si el servicio tiene autenticación habilitada)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=

​
Cómo funciona

Cuando usted define CASHIN_FEE_CALCULATION_TYPE=segment, el plugin:
  1. Obtiene el segmento asociado a la cuenta receptora
  2. Calcula las tarifas aplicables antes de procesar la transacción en Midaz
  3. Distribuye el pago recibido según las reglas de paquete vinculadas a ese segmento

​
Pasos de configuración

  1. Cree segmentos en Midaz — Defina los segmentos de cuenta que determinan las reglas de tarifa
  2. Configure paquetes en Fee Engine — Vincule cada segmento a sus reglas de cálculo de tarifa
  3. Asigne segmentos a las cuentas — Cree o actualice cuentas en Midaz con el ID de segmento apropiado
Documentación relacionada:

​
7. Conciliación DICT (VSync)

VSync concilia sus datos DICT locales con BACEN procesando todos los eventos relacionados con claves del día. Esto asegura que su estado local se mantenga consistente con los registros autoritativos de BACEN. 
# Ventana de bloqueo de escritura (formato 24 horas, UTC)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Rango de red permitido para servicios de conciliación
RECONCILIATION_INTERNAL_CIDR=
Durante la conciliación, la base de datos bloquea temporalmente operaciones de escritura para evitar inconsistencias de datos con BACEN. Planifique la ventana de bloqueo de escritura durante períodos de bajo tráfico.
El rango CIDR restringe qué redes pueden activar la conciliación. El plugin rechaza automáticamente solicitudes de fuera de este rango.

​
8. Seguridad interna de webhooks

El plugin usa un canal de comunicación interno entre los servicios Worker y Application. Firmas HMAC-SHA256 protegen este canal para evitar manipulación y ataques de replay. 
# Secreto compartido para firmar solicitudes internas (Worker -> Application)
# Debe tener al menos 32 caracteres
# Genere uno con: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validar firmas en webhooks internos recibidos (true/false)
# Siempre use 'true' en producción
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Edad máxima (en segundos) para timestamps de solicitud antes del rechazo
# Predeterminado: 300 (5 minutos)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300
Use exactamente el mismo valor de INTERNAL_WEBHOOK_SECRET en los servicios Application y Worker. Una incompatibilidad hace que el plugin rechace todos los webhooks internos.

​
9. Capas de workers

El plugin opera con tres capas de workers, cada una manejando una parte diferente del ciclo de vida del Pix. Todos los workers se ejecutan como servicios separados junto a la aplicación principal.

​
Worker de entrada

El worker de entrada recibe notificaciones de webhook de BTG y las reenvía a su aplicación para procesamiento. 
# URL donde la aplicación recibe webhooks internos
WEBHOOK_INBOUND_BASE_URL=

# Secreto compartido para firmar solicitudes (debe coincidir con el INTERNAL_WEBHOOK_SECRET de la aplicación)
INTERNAL_WEBHOOK_SECRET=

​
Worker de salida

El worker de salida envía notificaciones de eventos del plugin a su aplicación vía webhooks. Así es como su sistema se mantiene informado sobre eventos Pix (transferencias, devoluciones, reivindicaciones, disputas).

​
Prioridad de resolución de URL

El plugin resuelve URLs de webhook en este orden, usando la primera coincidencia:
  1. URL de entidad — Una URL específica para el tipo de evento (ej.: WEBHOOK_DICT_CLAIM_URL)
  2. URL de flujo — Una URL para la categoría más amplia (ej.: WEBHOOK_DICT_URL)
  3. URL predeterminada — La URL de fallback (WEBHOOK_DEFAULT_URL)
# URL de fallback predeterminada
WEBHOOK_DEFAULT_URL=

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

# Eventos de devolución
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Eventos de transferencia
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=
Puede comenzar solo con WEBHOOK_DEFAULT_URL para recibir todos los eventos en un único endpoint, y gradualmente dividir en URLs específicas por entidad a medida que su sistema evoluciona.
Para una inmersión profunda en tipos de eventos de webhook, payloads, comportamiento de reintento y buenas prácticas, vea la guía de Webhooks.

​
Worker de conciliación

El worker de conciliación necesita las mismas credenciales de la capa Application para estos servicios:
  • CRM — URL y credenciales
  • BTG — URL y credenciales
  • Midaz — ID de organización
Consulte las secciones correspondientes arriba para detalles de cada configuración. Puede restringir cuándo opera el worker configurando una ventana de tiempo específica. Esto es especialmente útil para programar tareas de conciliación durante horarios de bajo tráfico. El plugin soporta ventanas de tiempo que cruzan la medianoche. 
# Hora de inicio en formato HH:MM (24 horas). Ejemplo: "23:00" para las 11 PM
RECONCILIATION_START_TIME=

# Hora de fin en formato HH:MM (24 horas). Ejemplo: "05:00" para las 5 AM
RECONCILIATION_END_TIME=
Si deja ambos campos vacíos, el worker se ejecuta sin restricciones de horario — 24/7.

​
Próximos pasos

Con el plugin completamente configurado, está listo para comenzar a operar Pix. Explore estos temas para profundizar: