Skip to main content
El plugin Bank Transfer opera el sistema TED de Brasil a través de JD Consultores. JD provee la conectividad regulada con el SPB. El plugin conduce cada transferencia desde el cálculo de la tarifa hasta la confirmación de liquidación, para que tu equipo no llame a JD directamente.

​
Lo que el plugin gestiona por ti

  • Envía TEDs salientes a cualquier banco brasileño (TED OUT)
  • Recibe y acredita TEDs entrantes (TED IN)
  • Procesa transferencias internas instantáneas entre cuentas (P2P)
  • Calcula y aplica tarifas antes de que el cliente confirme
  • Detecta y bloquea transferencias duplicadas dentro de una ventana configurable
  • Valida días hábiles del BACEN contra el calendario bacen_holidays (seed estático para 2026–2028, refresher en vivo de ANBIMA pendiente)
  • Firma mensajes con el certificado digital de tu institución, como el BACEN exige
  • Reintenta operaciones fallidas automáticamente
  • Notifica a tu sistema a través de webhooks cuando una transferencia cambia de estado

​
Cómo funciona TED OUT

TED OUT es un flujo de confirmación previa. El cliente revisa la tarifa antes de que el plugin envíe la transferencia.

​
Paso 1 — Iniciar

Endpoint: POST /v1/transfers/initiate
1
Tu sistema llama al plugin con los detalles de la transferencia: monto, destinatario y cuenta del remitente.
2
El plugin valida la cuenta del remitente, verifica el horario de funcionamiento y ejecuta la detección de duplicados.
3
El plugin calcula la tarifa y devuelve un initiationId con los montos calculados.
4
Tu sistema muestra la tarifa al cliente para su confirmación.
La iniciación es válida por 24 horas. Si el cliente no confirma dentro de esa ventana, expira.

​
Paso 2 — Preparar firma (opcional)

Endpoint: POST /v1/transfers/signing/prepare
Usa este paso solo cuando tu tenant firma fuera del plugin (modo de firma externa). El plugin congela el payload canónico STR0008 y devuelve los bytes exactos y el hash a firmar. Tu sistema firma el payload y pasa la firma al paso de proceso. Cuando el plugin firma con tu clave local (el valor por defecto), omite este paso.

​
Paso 3 — Procesar

Endpoint: POST /v1/transfers/process
1
Tu sistema llama al plugin con el initiationId para confirmar.
2
El plugin verifica los límites diarios y mensuales y el saldo disponible.
3
El plugin reserva los fondos en Midaz (un hold) y envía el mensaje firmado a JD Consultores.
4
JD enruta la transferencia al banco de destino a través de la red SPB.
5
El plugin recibe la confirmación de liquidación de JD y finaliza los registros.
6
Tu sistema recibe un webhook con el estado final.

​
Cómo funciona TED IN

  1. Un banco externo envía un TED a tu institución a través de JD Consultores.
  2. El plugin consulta a JD cada 60 segundos (valor por defecto) para detectar nuevas transferencias entrantes.
  3. El plugin valida al destinatario contra el CRM para encontrar la cuenta correcta.
  4. El plugin acredita la cuenta en Midaz y crea un registro de transferencia completado.
  5. Tu sistema recibe un webhook que confirma el crédito.
El polling de TED IN está desactivado por defecto. Para activarlo, define JD_POLLING_ENABLED después de configurar las credenciales JD y el worker de polling.

​
Cómo funciona P2P

Las transferencias P2P mueven fondos entre dos cuentas de la misma organización. No usan la red SPB, y la liquidación es instantánea.
  1. Tu sistema llama al plugin con la cuenta del remitente, la cuenta del destinatario y el monto.
  2. El plugin calcula la tarifa, si está configurada, y la presenta para confirmación.
  3. Tras la confirmación, el plugin ejecuta la transferencia en Midaz.
  4. Ambas cuentas se actualizan de inmediato, y tu sistema recibe un webhook.

​
Modelos de despliegue

El plugin TED admite dos modelos de despliegue. La variable de entorno DEPLOYMENT_MODE selecciona el modelo.

​
SaaS (gestionado por Lerian)

En los despliegues SaaS, Lerian gestiona la integración con JD Consultores, incluyendo el mantenimiento de credenciales y certificados. Tu equipo configura solo los ajustes a nivel de negocio a través de la Admin API, como límites de transacción, tarifas y webhooks. No gestionas infraestructura ni conexiones. En modo saas, el plugin funciona como un servicio multi-tenant. El servicio de la plataforma de multi-tenancy resuelve la identidad del tenant, las credenciales JD, los secretos de webhook y ciertos ajustes en tiempo de ejecución. Este modo requiere las variables MULTI_TENANT_* y AWS_REGION, y el plugin las usa activamente.

​
BYOC (trae tus propias credenciales)

En los despliegues BYOC, tu institución provee las credenciales de JD Consultores y la clave privada RSA que firma los mensajes. Tu equipo de DevOps define estos valores a través de variables de entorno. Mantienes control total de la conexión con JD, y el plugin funciona por completo dentro de tu propia infraestructura. BYOC es el modo de despliegue por defecto (byoc). El plugin carga toda la configuración desde variables de entorno al arrancar, incluyendo credenciales JD, secretos de webhook y ajustes de tarifas.

​
Resolución de organización

El plugin identifica la organización de Midaz a partir del header obligatorio X-Organization-Id en las rutas de API con alcance de organización. Algunos procesos en segundo plano no reciben headers de solicitud, como el poller de TED IN y los workers de reconciliación. Para estos, el plugin recurre a la variable de entorno ORGANIZATION_ID.
En modo byoc, el plugin ignora las variables de multi-tenancy (MULTI_TENANT_*) y AWS_REGION.
Consulta Configuración de Bank Transfer para la lista completa de variables de entorno admitidas.

​
Integración con Midaz

Todos los movimientos financieros pasan a través del ledger de Midaz. El plugin crea una transacción de Midaz para cada transferencia:
  • TED OUT — el plugin retiene los fondos en el paso de proceso (vía pending: true), luego los debita cuando JD confirma la liquidación.
  • TED IN — el plugin acredita los fondos después de que JD valida y confirma la transferencia.
  • P2P — una única transacción de Midaz debita al remitente y acredita al destinatario de forma atómica.
Cada transferencia se corresponde con un registro de transacción en tu ledger de Midaz. Consulta Datos y reportes de Bank Transfer para los campos disponibles para la reconciliación.

​
Para desarrolladores

​
Arquitectura

El plugin usa una arquitectura Hexagonal (Puertos y Adaptadores) con CQRS. Este diseño mantiene la lógica de negocio separada de la infraestructura. Puedes agregar un nuevo adaptador, como un proveedor SPB diferente, sin un cambio en el comportamiento del núcleo.
Ted Architectural Pattern

​
Detección de duplicados

El plugin construye una huella (fingerprint) de detección de duplicados para cada transferencia. La huella cubre senderAccountId, los datos del destinatario (ISPB, agencia, cuenta, documento del titular), el monto y el propósito. El plugin almacena la huella en Redis con un TTL configurable (por defecto 300 segundos, definido por DUPLICATE_GUARD_TTL_SEC). La organización no forma parte de la huella. El aislamiento de tenant proviene del prefijo de clave de Redis. El plugin rechaza una solicitud duplicada dentro de la ventana con 409 Conflict y el código de error BTF-0012.

​
Aislamiento de datos multi-tenant

El aislamiento de tenant proviene de la resolución de base de datos por tenant en la plataforma de multi-tenancy. El plugin lee el tenantId del claim JWT o del contexto autenticado, nunca de X-Organization-Id. La caché de Redis usa prefijos de clave por tenant (tenant:{tenantId}:{key}). Las tablas de negocio usan los campos de organización de Midaz solo para la autorización de alcance de negocio dentro del tenant resuelto.

​
Observabilidad

El plugin expone métricas de Prometheus, logs JSON estructurados y trazas OpenTelemetry. También expone sondas de liveness y readiness sin autenticación para la orquestación de Kubernetes. Estas sondas importan principalmente para los despliegues BYOC.
Las sondas de liveness y readiness no requieren autenticación por diseño, para la compatibilidad con las sondas K8s. En los despliegues BYOC, restringe el acceso a estas sondas a nivel de red, por ejemplo con reglas de ingress o grupos de seguridad. Esto mantiene el estado de las dependencias internas fuera de la internet pública.