El Plugin Pix Indirecto (BTG) se conecta con varios servicios de Lerian y proveedores externos para procesar pagos Pix. Para configurarlo, defines la conexión del plugin con cada servicio y preparas los datos que esos servicios necesitan. El plugin se ejecuta en dos capas principales. La Aplicación expone la API de Pix y procesa la lógica de negocio. Los Workers atienden los webhooks entrantes de BTG, la entrega de eventos salientes a tu sistema, la conciliación de DICT con BACEN y los pagos programados. Ambas capas comparten la misma configuración base (licencia, Midaz, CRM, BTG), pero tienen sus propios ajustes específicos de servicio.

Prerrequisitos

Antes de empezar, confirma que tienes:

Tu ISPB (Identificador do Sistema de Pagamentos Brasileiro): el identificador de 8 caracteres derivado del CNPJ de tu institución
Acceso a tus instancias de Midaz y CRM (desplegadas y en ejecución)
Acceso a los servicios del proveedor BTG (BTG entrega las credenciales)

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

El plugin usa PIX_ISPB para generar y verificar los IDs end-to-end. Las transferencias intra-PSP (P2P) las detecta en cambio por la cuenta alias del pagador: consulta Transferencias intra-PSP.

1. Licencia

El plugin requiere una licencia válida para operar. Lerian entrega la clave de licencia durante el onboarding.

# License key provided by Lerian
LICENSE_KEY=

# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=

Documentación relacionada: La licencia de Lerian

2. Access Manager (opcional)

Access Manager atiende la autenticación del plugin. Cuando está habilitado, valida las solicitudes entrantes antes de que lleguen a la API del 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=

Cuando PLUGIN_AUTH_ENABLED=true, el plugin valida el header Authorization de cada solicitud para confirmar que:

El token pertenece a un usuario o una aplicación autorizados
El token concede acceso al endpoint y al método de la API solicitados

Las credenciales de cliente (CLIENT_ID / CLIENT_SECRET) de Midaz y del CRM son obligatorias incluso cuando PLUGIN_AUTH_ENABLED=false. Las credenciales de comisiones son obligatorias cuando CASHIN_FEE_CALCULATION_TYPE=segment.

Documentación relacionada: Access Manager

3. Midaz

Midaz es el ledger central de todas las transacciones Pix que procesa el plugin. 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

# 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 del activo

Configura un activo en tu organización y ledger con estas propiedades:

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

Vincula todas las cuentas a tu ledger con el activo BRL. El plugin rechaza las operaciones sobre cuentas que no cumplen esta configuración.

Configuración de cuentas

Antes de usar el plugin, crea una cuenta en Midaz para cada cliente bajo tu ISPB. Usa el endpoint Create an Account para configurar las cuentas. Cada cuenta debe:

Pertenecer a la organización y al ledger que configuraste
Usar el activo BRL

Header X-Account-Id

Muchas operaciones Pix requieren el header X-Account-Id para identificar qué cuenta ejecuta la acción. Este ID corresponde al ID de la cuenta del ledger de Midaz. Cuando llamas a un endpoint del plugin, el valor de X-Account-Id le indica al plugin:

Qué cuenta usar para las operaciones del ledger
Qué datos de cliente obtener del CRM
Qué saldo validar y actualizar

Cómo el plugin usa el ID de cuenta

El plugin usa el ID de cuenta de forma distinta según el tipo de operación:

Tipo de flujo	Cómo el plugin usa el ID de cuenta
No transaccional (por ejemplo, la creación de claves o de códigos QR)	Obtiene del CRM los datos del cliente y de la cuenta bancaria
Transaccional (por ejemplo, pagos, devoluciones)	Obtiene los datos del cliente para iniciar el pago
	Valida los datos de la cuenta para autorizar el pago entrante
	Ejecuta la transacción en el ledger

Cumplimiento de la cuenta

El plugin verifica el estado de la cuenta en Midaz. Rechaza una iniciación de transferencia, un cash-out o una devolución desde una cuenta BLOCKED. También rechaza un Pix entrante a una cuenta que no está ACTIVE. Para impedir liquidaciones Pix en una cuenta específica, bloquéala directamente en Midaz. El plugin recibe un rechazo cuando intenta registrar la transacción. Documentación relacionada:

4. CRM

El CRM guarda la información del cliente (titular) y sus cuentas bancarias asociadas. Cada cuenta de Midaz debe tener un titular y una cuenta alias correspondientes en el CRM para ejecutar operaciones Pix. El plugin consulta los datos del CRM para:

Registrar y validar las claves Pix
Construir los mensajes de pago para BACEN
Autorizar las transacciones entrantes
Procesar los workflows de devolución y de disputa

Conexión

# CRM base URL
PLUGIN_CRM_BASE_URL=

# CRM API credentials (required)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=

Titulares

Los datos del titular representan al cliente dueño de la cuenta. Crea cada titular en el CRM antes de ejecutar cualquier operación Pix para ese cliente.

Campos obligatorios

Campo	Requisito	Ejemplo
`name`	Máximo 120 caracteres	`Maria Silva Santos`
`document`	Para `NATURAL_PERSON`, un CPF de 11 dígitos; para `LEGAL_PERSON`, un CNPJ de 14 caracteres, numérico o alfanumérico	`12345678900`
`type`	Tipo de persona (valores enum del CRM)	`NATURAL_PERSON`

Campos opcionales

Campo	Cuándo usarlo
`legalPerson.tradeName`	Cuando asocias un nombre comercial a los datos de la clave
`addresses.primary`	Obligatorio para crear una cobranza con vencimiento

Documentación relacionada: Create a Holder

Cuentas alias

Las cuentas alias vinculan una cuenta de Midaz con sus datos bancarios. Cada cuenta alias debe incluir la información bancaria que el ecosistema Pix requiere para procesar transacciones.

Campos obligatorios

Campo	Requisito	Ejemplo
`accountId`	ID de la cuenta de Midaz (UUID)	`3c90c3cc-0d44-4b50-8888-8dd25736052a`
`bankingDetails.branch`	Exactamente 4 dígitos	`0001`
`bankingDetails.account`	De 1 a 20 letras mayúsculas o dígitos, con el dígito verificador	`123456789`
`bankingDetails.type`	Tipo de cuenta (consulta la tabla siguiente)	`CACC`
`bankingDetails.openingDate`	Formato YYYY-MM-DD	`2024-01-15`
`bankingDetails.bankId`	El ISPB de la institución que mantiene la cuenta. Obligatorio para enviar un Pix	`12345678`

El campo bankingDetails.branch debe contener exactamente 4 dígitos. Rellena con ceros a la izquierda si hace falta. Por ejemplo, si el número de sucursal es 1, regístralo como 0001. El plugin solo puede validar la cuenta en el CRM cuando el código de sucursal sigue este formato.

Cuando el dígito verificador es una letra, el DICT lo recibe como 0: una cuenta guardada como AB1234567X se registra en el DICT como AB12345670. Mantén el valor original en el CRM.

Tipos de cuenta admitidos

Código	Descripción
`CACC`	Cuenta corriente
`SLRY`	Cuenta de nómina
`SVGS`	Cuenta de ahorro
`TRAN`	Cuenta transaccional
`OTHR`	Otra

No puedes registrar ni reclamar una clave Pix para una cuenta SLRY. El plugin devuelve PIX-0129. Documentación relacionada: Create an Alias Account

5. Proveedor BTG

BTG es el participante directo que conecta tu institución con la infraestructura Pix de BACEN. BTG entrega las credenciales directamente cuando tu institución se suscribe a la integración indirecta con BACEN.

Conexión

# BTG API base URL
BTG_BASE_URL=

# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=

mTLS (seguridad de los webhooks)

El TLS mutuo (mTLS) valida el certificado de BTG en las solicitudes de webhook. Confirma que los webhooks entrantes se originan en BTG. Tu ingress reenvía el certificado que presenta BTG en el header MTLS_CERTIFICATE_HEADER (predeterminado 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

Habilita siempre mTLS en los entornos de producción. Deshabilítalo solo durante el desarrollo local.

Para presentar un certificado de cliente en las llamadas del propio plugin a BTG, define BTG_OUTBOUND_MTLS_ENABLED=true con CLIENT_TLS_CERT_FILE y CLIENT_TLS_KEY_FILE. Consulta Variables de entorno.

6. Servicio de comisiones (opcional)

Habilita el cálculo de comisiones para cobrar y distribuir comisiones de forma automática sobre los pagos entrantes. Es opcional. Si no lo configuras, el plugin procesa las transacciones sin cálculo de comisiones.

Conexión

# 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=

Cómo funciona

Cuando defines CASHIN_FEE_CALCULATION_TYPE=segment, el plugin:

Obtiene el segmento asociado a la cuenta receptora
Calcula las comisiones aplicables antes de procesar la transacción en Midaz
Distribuye el pago entrante según las reglas de paquete vinculadas a ese segmento

Pasos de configuración

Crea segmentos en Midaz: define los segmentos de cuenta que determinan las reglas de comisión
Configura paquetes en Fees Engine: vincula cada segmento con sus reglas de cálculo de comisiones
Asigna segmentos a las cuentas: crea o actualiza cuentas de Midaz con el ID de segmento correspondiente

Documentación relacionada:

Conciliación de DICT (VSync)

VSync concilia tus datos locales de DICT con BACEN al procesar todos los eventos del día relacionados con claves. Mantiene tu estado local consistente con los registros de referencia de 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 la ventana, la API rechaza las solicitudes de creación, actualización y eliminación de claves Pix para evitar inconsistencias de datos con BACEN. Planifica la ventana de bloqueo de escritura en periodos de bajo tráfico.

Configuración del cache de Redis

VSync usa Redis para guardar en cache las entradas de BTG/DICT y los titulares del CRM durante la conciliación. En los despliegues con Helm, el REDIS_HOST predeterminado apunta al Valkey incluido, así que una instalación estándar no requiere configuración adicional.

# 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

Conexión (siempre se usa)

Var	Tipo	Predeterminado	Descripción
`REDIS_HOST`	string (host:port, CSV)	Valkey incluido (Helm chart)	Dirección o direcciones de Redis. Varias direcciones separadas por coma definen una topología Sentinel o Cluster.
`REDIS_MASTER_NAME`	string	`""`	Nombre del master de Sentinel. Vacío = standalone (conexión directa).
`REDIS_DB`	int	`0`	Número de la base de datos lógica de Redis.
`REDIS_PROTOCOL`	int	`3`	Versión del protocolo RESP (2 o 3).

Pool de conexiones y reintentos (siempre se usa)

Var	Tipo	Predeterminado	Descripción
`REDIS_POOL_SIZE`	int	`10`	Máximo de conexiones en el pool.
`REDIS_MIN_IDLE_CONNS`	int	`0`	Mínimo de conexiones inactivas que se mantienen listas.
`REDIS_READ_TIMEOUT`	int (segundos)	`3`	Timeout de la operación de lectura.
`REDIS_WRITE_TIMEOUT`	int (segundos)	`3`	Timeout de la operación de escritura.
`REDIS_DIAL_TIMEOUT`	int (segundos)	`5`	Timeout para establecer la conexión inicial.
`REDIS_POOL_TIMEOUT`	int (segundos)	`2`	Timeout de espera por una conexión libre del pool.
`REDIS_MAX_RETRIES`	int	`3`	Máximo de reintentos de un comando fallido.
`REDIS_MIN_RETRY_BACKOFF`	int (milisegundos)	`8`	Espera mínima entre reintentos.
`REDIS_MAX_RETRY_BACKOFF`	int (segundos)	`512`	Espera máxima entre reintentos. Nota: en el código se guarda en segundos (unidad distinta de la del mínimo).

Autenticación (opcional, solo se usa si se define)

Var	Tipo	Predeterminado	Descripción
`REDIS_PASSWORD`	string (secreto)	`""`	Contraseña de Redis. Vacío = sin autenticación por contraseña.

TLS (opcional, solo se usa si `REDIS_TLS=true`)

Var	Tipo	Predeterminado	Descripción
`REDIS_TLS`	bool	`false`	Habilita TLS. Obligatorio en `true` con `DEPLOYMENT_MODE=saas` (se valida en el arranque).
`REDIS_CA_CERT`	string (PEM base64)	`""`	Certificado de CA (base64) para validar el servidor cuando TLS está activo.

Autenticación IAM de GCP (opcional, solo se usa si `REDIS_USE_GCP_IAM=true`)

Var	Tipo	Predeterminado	Descripción
`REDIS_USE_GCP_IAM`	bool	`false`	Habilita la autenticación IAM de GCP (Memorystore) en lugar de la contraseña.
`REDIS_SERVICE_ACCOUNT`	string	`""`	Cuenta de servicio de GCP que genera el token de acceso.
`GOOGLE_APPLICATION_CREDENTIALS`	string	`""`	Credenciales de GCP (una ruta de archivo o el contenido JSON) para generar el token.
`REDIS_TOKEN_LIFETIME`	int (minutos)	`60`	Duración del token IAM generado.
`REDIS_TOKEN_REFRESH_DURATION`	int (minutos)	`45`	Intervalo de actualización del token (debe ser menor que la duración).

TTL del cache de VSync (siempre se usa)

Var	Tipo	Predeterminado	Descripción
`CACHE_BTG_ENTRY_TTL`	Go duration	`30m`	TTL del cache de las entradas de BTG/DICT en Redis. Un valor negativo vuelve al predeterminado.
`CACHE_CRM_HOLDER_TTL`	Go duration	`30m`	TTL del cache de los titulares del CRM en Redis. Un valor negativo vuelve al predeterminado.

8. Seguridad de los webhooks internos

El plugin usa un canal de comunicación interno entre los servicios Worker y Aplicación. Las firmas HMAC-SHA256 protegen este canal para evitar manipulaciones y ataques de repetición.

# 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

Usa exactamente el mismo valor de INTERNAL_WEBHOOK_SECRET en los servicios Aplicación y Worker. Una discrepancia hace que el plugin rechace todos los webhooks internos.

9. Capas de workers

El plugin opera con cuatro workers, y cada uno atiende una parte distinta del ciclo de vida de Pix. Cada worker se ejecuta como un servicio separado junto a la aplicación principal.

Worker de entrada

La Aplicación recibe las notificaciones de webhook de BTG y las guarda. Después, el worker de entrada entrega cada notificación a los endpoints internos de la Aplicación para su procesamiento.

# 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 salida

El worker de salida envía notificaciones de evento desde el plugin hacia tu aplicación por webhooks. Así tu sistema se mantiene informado sobre los eventos Pix (transferencias, devoluciones, reclamaciones, disputas).

Prioridad de resolución de URL

El plugin resuelve las URL de webhook en este orden, y usa la primera que coincide:

URL de entidad: una URL específica del tipo de evento (por ejemplo, WEBHOOK_DICT_CLAIM_URL)
URL de flujo: una URL para la categoría más amplia (por ejemplo, WEBHOOK_DICT_URL)
URL predeterminada: la URL de respaldo (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 entidad necesita su propia variable WEBHOOK_<FLOW>_<ENTITY>_*. Consulta Webhooks. Para los tipos de evento de webhook, los payloads, el comportamiento de reintento y las mejores prácticas, consulta la guía de Webhooks.

Worker de conciliación

El worker de conciliación necesita las mismas credenciales que la capa Aplicación para estos servicios:

CRM: URL y credenciales
BTG: URL y credenciales
Midaz: ID de organización

También llama a la API de la Aplicación con sus propias credenciales de cliente: PLUGIN_PIX_BTG_BASE_URL, PLUGIN_PIX_BTG_CLIENT_ID y PLUGIN_PIX_BTG_CLIENT_SECRET, con el endpoint de token en PLUGIN_AUTH_URL. Consulta las secciones correspondientes de más arriba para conocer los detalles de cada configuración. Puedes restringir cuándo opera el worker si configuras una ventana de tiempo específica. Sirve para programar las tareas de conciliación en horas de baja demanda. El plugin admite ventanas de tiempo que cruzan la medianoche.

# 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=

Si dejas ambos campos vacíos, el worker se ejecuta sin restricciones de horario (24/7).

El worker siempre interpreta la ventana de conciliación en la zona horaria America/Sao_Paulo (BRT), sea cual sea el reloj del contenedor o la variable TZ. El worker incluye los datos de zonas horarias de IANA. La ventana se mantiene alineada con el bloqueo de escritura de DICT de BACEN, incluso en imágenes mínimas o distroless. No necesitas definir TZ.

Worker de programación

El worker de programación ejecuta los pagos Pix programados cuando vencen. Viene desactivado de forma predeterminada. Llama a la API de la Aplicación con las mismas variables de credenciales de cliente que el worker de conciliación.

# 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=

Los endpoints de cashout y de devolución de Pix Indirecto admiten idempotencia con el header de solicitud X-Idempotency. El plugin guarda una respuesta reutilizable durante IDEMPOTENCY_RESPONSE_TTL segundos (predeterminado 86400, 24 horas). Para estrategias de reintento y detalles de implementación, consulta Reintentos e idempotencia.

10. Observabilidad (OpenTelemetry)

El plugin viene con instrumentación de OpenTelemetry (trazas, métricas y logs) en las capas Aplicación y Worker. El plugin traza los flujos Pix de extremo a extremo: transferencias (cash-in y cash-out), devoluciones, webhooks entrantes y salientes, conciliación de DICT y liquidación intra-PSP. Puedes seguir un solo pago a través del plugin y de las llamadas a Midaz, al CRM y a BTG. La telemetría está deshabilitada de forma predeterminada. Habilítala y apunta el exportador OTLP a tu 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}

Cuando ENABLE_TELEMETRY=true, OTEL_EXPORTER_OTLP_ENDPOINT es obligatorio. Define las mismas variables de OTel en la Aplicación y en cada Worker para que las trazas se correlacionen entre servicios.

Exportador: gRPC y TLS

El plugin exporta trazas, métricas y logs por OTLP/gRPC. El esquema del endpoint controla la seguridad del transporte:

Valor del endpoint	Transporte	Seguridad
`https://collector:4317`	gRPC sobre TLS	Seguro (recomendado para producción)
`http://collector:4317`	gRPC, texto plano	Inseguro (se infiere de forma automática)
`collector:4317` (`host:port` simple)	gRPC, texto plano	Inseguro (se infiere de forma automática)

Cuando OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT es production o prod, el plugin se niega a arrancar con un exportador inseguro. Usa un endpoint https://, o define ALLOW_INSECURE_OTEL con una justificación breve solo cuando controlas por completo la ruta de red hasta el collector.

Ejemplo: endpoint del collector

Apunta el plugin a cualquier collector compatible con OTLP (el OpenTelemetry Collector, Grafana LGTM/Alloy, etc.) que escuche en el puerto 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

Después el collector distribuye la telemetría a tus backends de trazas, métricas y logs.

11. Health y readiness

La Aplicación y los Workers exponen una sonda de readiness en /readyz (junto con las verificaciones estándar de liveness). Apunta la sonda de readiness de tu orquestador a este endpoint para que el tráfico se enrute solo cuando el servicio y sus dependencias están listos.

Propósito de la transferencia (MED 2.0)

El endpoint de cashout acepta un header opcional X-Purpose que identifica el propósito de la transacción, usado en las transferencias de devolución de MED 2.0. Cuando se omite, el valor predeterminado es TRANSFER.

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

Para los valores admitidos, consulta Transferencias.

Próximos pasos

Con el plugin configurado, puedes empezar a operar Pix.

Webhooks: tipos de evento, payloads, reintentos y mejores prácticas
MED 2.0: Recuperación de fondos: recuperación de fraude entre cuentas y el header X-Purpose
Operaciones de devolución: devoluciones parciales distribuidas y desbloqueo
Transferencias intra-PSP: liquidación P2P interna y reporte TRCK002
Dominios principales: DICT: entender la gestión de claves Pix
Dominios principales: transacciones: flujos y ciclo de vida de las transacciones
Dominios principales: QR Codes: generación de códigos QR estáticos y dinámicos
Referencia de API: documentación completa de la API para DICT, reclamaciones, transacciones, QR Codes y operaciones MED

​Prerrequisitos

​1. Licencia

​2. Access Manager (opcional)

​3. Midaz

​Conexión

​Requisitos del activo

​Configuración de cuentas

​Header X-Account-Id

​Cómo el plugin usa el ID de cuenta

​Cumplimiento de la cuenta

​4. CRM

​Conexión

​Titulares

​Campos obligatorios

​Campos opcionales

​Cuentas alias

​Campos obligatorios

​Tipos de cuenta admitidos

​5. Proveedor BTG

​Conexión

​mTLS (seguridad de los webhooks)

​6. Servicio de comisiones (opcional)

​Conexión

​Cómo funciona

​Pasos de configuración

​ Conciliación de DICT (VSync)

​Configuración del cache de Redis

​Conexión (siempre se usa)

​Pool de conexiones y reintentos (siempre se usa)

​Autenticación (opcional, solo se usa si se define)

​TLS (opcional, solo se usa si REDIS_TLS=true)

​Autenticación IAM de GCP (opcional, solo se usa si REDIS_USE_GCP_IAM=true)

​TTL del cache de VSync (siempre se usa)

​8. Seguridad de los webhooks internos

​9. Capas de workers

​Worker de entrada

​Worker de salida

​Prioridad de resolución de URL

​Worker de conciliación

​Worker de programación

​10. Observabilidad (OpenTelemetry)

​Exportador: gRPC y TLS

​Ejemplo: endpoint del collector

​11. Health y readiness

​Propósito de la transferencia (MED 2.0)

​Próximos pasos

Prerrequisitos

1. Licencia

2. Access Manager (opcional)

3. Midaz

Conexión

Requisitos del activo

Configuración de cuentas

Header X-Account-Id

Cómo el plugin usa el ID de cuenta

Cumplimiento de la cuenta

4. CRM

Conexión

Titulares

Campos obligatorios

Campos opcionales

Cuentas alias

Campos obligatorios

Tipos de cuenta admitidos

5. Proveedor BTG

Conexión

mTLS (seguridad de los webhooks)

6. Servicio de comisiones (opcional)

Conexión

Cómo funciona

Pasos de configuración

Conciliación de DICT (VSync)

Configuración del cache de Redis

Conexión (siempre se usa)

Pool de conexiones y reintentos (siempre se usa)

Autenticación (opcional, solo se usa si se define)

TLS (opcional, solo se usa si `REDIS_TLS=true`)

Autenticación IAM de GCP (opcional, solo se usa si `REDIS_USE_GCP_IAM=true`)

TTL del cache de VSync (siempre se usa)

8. Seguridad de los webhooks internos

9. Capas de workers

Worker de entrada

Worker de salida

Prioridad de resolución de URL

Worker de conciliación

Worker de programación

10. Observabilidad (OpenTelemetry)

Exportador: gRPC y TLS

Ejemplo: endpoint del collector

11. Health y readiness

Propósito de la transferencia (MED 2.0)

Próximos pasos