Skip to main content
El plugin Bank Transfer opera el riel 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 comisión hasta la confirmación de liquidación, así tu equipo no llama a JD directamente.

​
Qué resuelve el plugin por ti

  • Envía TED salientes a cualquier banco brasileño (TED OUT)
  • Recibe y acredita TED entrantes (TED IN)
  • Procesa transferencias internas instantáneas entre cuentas (P2P)
  • Calcula y aplica comisiones antes de que el cliente confirme
  • Detecta y bloquea transferencias duplicadas dentro de una ventana configurable
  • Valida los días hábiles de BACEN contra el calendario bacen_holidays (carga estática para 2026–2028; el actualizador en vivo de ANBIMA está pendiente)
  • Firma los mensajes con el certificado digital de tu institución, como exige BACEN
  • Reintenta automáticamente las operaciones fallidas
  • Avisa a tu sistema por 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 comisión 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 datos de la transferencia: monto, destinatario y cuenta del remitente.
2
El plugin valida la cuenta del remitente, revisa el horario de operación y ejecuta la detección de duplicados.
3
El plugin calcula la comisión y devuelve un initiationId con los montos calculados.
4
Tu sistema muestra la comisión al cliente para que la confirme.
La iniciación es válida por 24 horas. Si el cliente no confirma dentro de esa ventana, expira.

​
Paso 2: preparar la 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 y el hash exactos que se deben firmar. Tu sistema firma el payload y pasa la firma al paso de proceso. Cuando el plugin firma con tu clave local (lo predeterminado), 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 revisa los límites diarios y mensuales y el saldo disponible.
3
El plugin reserva fondos en Midaz (una retención) y envía el mensaje firmado a JD Consultores.
4
JD enruta la transferencia al banco de destino por la red del 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 una TED a tu institución a través de JD Consultores.
  2. El plugin sondea a JD cada 60 segundos (predeterminado) 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 completada.
  5. Tu sistema recibe un webhook que confirma el crédito.
El sondeo de TED IN está desactivado de forma predeterminada. Para activarlo, define JD_POLLING_ENABLED después de configurar las credenciales de JD y el worker de sondeo.

​
Cómo funciona P2P

Las transferencias P2P mueven fondos entre dos cuentas de la misma organización. No usan la red del 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 comisión, 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, incluido el mantenimiento de credenciales y certificados. Tu equipo configura solo ajustes de nivel de negocio a través de la Admin API, como límites de transacción, comisiones y webhooks. No gestionas infraestructura ni conexiones. En modo saas, el plugin corre como un servicio multi-tenant. El servicio de plataforma de multi-tenancy resuelve la identidad del tenant, las credenciales de JD, los secretos de webhook y ciertos ajustes en runtime. 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 mediante variables de entorno. Mantienes el control total de la conexión con JD y el plugin corre por completo en tu propia infraestructura. BYOC es el modo de despliegue predeterminado (byoc). El plugin carga toda la configuración desde variables de entorno al arrancar, incluidas las credenciales de JD, los secretos de webhook y los ajustes de comisiones.

​
Resolución de la organización

El plugin identifica la organización de Midaz a partir del header obligatorio X-Organization-Id en las rutas de API con ámbito de organización. Algunos procesos en segundo plano no reciben headers de solicitud, como el poller de TED IN y los workers de conciliación. Para esos casos, 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 TED para la lista completa de variables de entorno admitidas.

​
Integración con Midaz

Todos los movimientos financieros pasan por el ledger de Midaz. El plugin crea una transacción de Midaz por cada transferencia:
  • TED OUT: el plugin retiene los fondos en el paso de proceso (mediante pending: true) y 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 sola transacción de Midaz debita al remitente y acredita al destinatario de forma atómica.
Cada transferencia corresponde a un registro de transacción en tu ledger de Midaz. Consulta Datos e informes de TED para conocer los campos disponibles para la conciliació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 de SPB distinto, sin cambiar el comportamiento del núcleo.
Patrón arquitectónico de TED

​
Detección de duplicados

El plugin construye una huella de detección de duplicados para cada transferencia. La huella cubre senderAccountId, los datos del destinatario (ISPB, sucursal, cuenta, documento del titular), el monto y la finalidad. El plugin guarda la huella en Redis con un TTL configurable (300 segundos de forma predeterminada, definido por DUPLICATE_GUARD_TTL_SEC). La organización no forma parte de la huella. El aislamiento por tenant viene 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 por tenant viene de la resolución de base de datos por tenant en la plataforma de multi-tenancy. El plugin lee el tenantId del claim del JWT o del contexto autenticado, nunca de X-Organization-Id. El cache 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 autorización de ámbito de negocio dentro del tenant resuelto.

​
Observabilidad

El plugin expone métricas de Prometheus, logs JSON estructurados y trazas de OpenTelemetry. También expone probes de liveness y readiness sin autenticación para la orquestación de Kubernetes. Esos probes importan sobre todo en los despliegues BYOC.
Los probes de liveness y readiness no tienen autenticación por diseño, para compatibilidad con los probes de K8s. En los despliegues BYOC, restringe el acceso a esos probes en el nivel de red, por ejemplo con reglas de ingress o grupos de seguridad. Así el estado de las dependencias internas no queda en la internet pública.