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 y la conciliación de DICT con BACEN. 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 dígitos 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 digits)
PIX_ISPB=12345678

PIX_ISPB también se usa para detectar las transferencias intra-PSP (P2P): cuando el ISPB de destino de una transferencia coincide con este valor, el plugin la liquida internamente en lugar de enrutarla a BTG, y de todos modos la reporta a BACEN. Consulta Transferencias intra-PSP.

1. Licencia

El plugin es una solución enterprise y 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 todas las solicitudes entrantes antes de que lleguen a la API del plugin.

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

# Access Manager service URL
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

Solo necesitas entregar credenciales de cliente (CLIENT_ID / CLIENT_SECRET) para los servicios de Midaz, CRM y comisiones si esos servicios también tienen habilitada la autenticación con Access Manager.

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 if Midaz has authentication enabled)
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 no aplica restricciones de cuenta en el nivel de negocio, como cuentas bloqueadas o suspendidas. Tu aplicación debe validar el estado de la cuenta antes de llamar al plugin. 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 if CRM has authentication enabled)
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 dígitos (solo números)	`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 dígitos	`123456789`
`bankingDetails.type`	Tipo de cuenta (consulta la tabla siguiente)	`CACC`
`bankingDetails.openingDate`	Formato YYYY-MM-DD	`2024-01-15`

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.

Tipos de cuenta admitidos

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

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.

# 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 for signature validation
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.

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 if the fee service has authentication enabled)
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. Así tu estado local se mantiene consistente con los registros de referencia de BACEN.

# Write block window (24-hour format, UTC)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Allowed network range for reconciliation services
RECONCILIATION_INTERNAL_CIDR=

Durante la conciliación, la base de datos bloquea temporalmente las operaciones de escritura para evitar inconsistencias de datos con BACEN. Planifica la ventana de bloqueo de escritura en periodos de bajo tráfico.

El rango CIDR restringe qué redes pueden disparar la conciliación. El plugin rechaza de forma automática las solicitudes que vienen de fuera de ese rango.

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 sidecar de Valkey incluido, así que una instalación estándar no requiere configuración adicional.

# Connection (always used)
REDIS_HOST=<release>-valkey: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

En los despliegues con Helm, el REDIS_HOST predeterminado apunta al sidecar de Valkey incluido (<release-name>-valkey:6379). No hace falta configuración adicional de Redis a menos que te conectes a una instancia externa.

Conexión (siempre se usa)

Var	Tipo	Predeterminado	Descripción
`REDIS_HOST`	string (host:port, CSV)	`<release>-valkey:6379` (Helm chart)	Dirección o direcciones de Redis. El valor predeterminado apunta al Valkey incluido (`<release-name>-valkey:6379`). 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	`""`	Ruta de las credenciales de GCP (se lee con CredentialsBase64FromEnvValue) 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 tres capas de workers, y cada una atiende una parte distinta del ciclo de vida de Pix. Todos los workers se ejecutan como servicios separados junto a la aplicación principal.

Worker de entrada

El worker de entrada recibe las notificaciones de webhook de BTG y las reenvía a tu aplicación para su procesamiento.

# URL where the application receives 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_EVENT_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=

Puedes empezar solo con WEBHOOK_DEFAULT_URL para recibir todos los eventos en un único endpoint, y después separar de a poco en URL específicas por entidad a medida que tu sistema evoluciona.

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

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.

Los endpoints de cashout y de devolución de Pix Indirecto admiten idempotencia con el header de solicitud X-Idempotency, con TTL configurable mediante X-TTL. Para estrategias de reintento y detalles de implementación, consulta Reintentos e idempotencia.

10. Observabilidad (OpenTelemetry)

El plugin viene con instrumentación completa de OpenTelemetry (trazas, métricas y logs) en las capas Aplicación y Worker. El plugin traza cada flujo 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_LIBRARY_NAME=github.com/LerianStudio/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

Los exportadores inseguros (en texto plano) se rechazan fuera de los entornos de desarrollo. En staging o producción, usa un endpoint https://, o acepta el riesgo de forma explícita con el permiso de OTEL inseguro de lib-commons solo cuando controlas por completo la ruta de red hacia 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

Los valores admitidos son TRANSFER e INSTANT_PAYMENT_REFUND. Consulta MED 2.0 — Recuperación de fondos para los detalles.

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

​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

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