Saltar al contenido principal
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. Cuando otro motor de core bancario de tu institución usa el mismo canal JD y el mismo ISPB, JD Courier comparte el canal entre los motores.

​
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)
  • Envía TED al otro core de tu institución, y recibe sus TED, por JD Courier (TED entre cores)
  • Detecta y bloquea transferencias duplicadas dentro de una ventana configurable
  • Valida los días hábiles de BACEN contra su calendario de feriados integrado, de 2026 a 2028
  • Firma los mensajes con el certificado digital de tu institución, como exige BACEN
  • Concilia con JD las transferencias cuyo resultado es desconocido
  • 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.
Una iniciación de TED OUT es válida hasta el cierre de la ventana de operación de ese día. Si el cliente no la confirma a tiempo, 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 lee el estado final con Get Transfer. Consulta Webhooks para ver los eventos de TED OUT.

​
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 y el mismo ledger de Midaz. No usan la red del SPB y la liquidación es instantánea. El P2P entre dos ledgers viene desactivado por defecto.
  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 corre en dos modelos de despliegue. La variable de entorno DEPLOYMENT_MODE (byoc de forma predeterminada, o saas) indica el modelo. En modo saas, el plugin se niega a arrancar a menos que PostgreSQL, Redis, MongoDB, RabbitMQ y el broker de streaming usen TLS.

​
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.

​
BYOC (trae tu propia nube)

En los despliegues BYOC, el plugin corre en tu propia infraestructura. Tu institución provee las credenciales de JD Consultores y la clave privada RSA que firma los mensajes, y tu equipo de DevOps las define mediante variables de entorno. Mantienes el control total de la conexión con JD.

​
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. Estos procesos usan la variable de entorno ORGANIZATION_ID. 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 cuando la TED entrante llega de JD.
  • P2P: el plugin debita al remitente y acredita al destinatario de forma atómica en Midaz.
Cada transferencia registra su transacción de Midaz en midazTransactionId. Un chargeback de TED IN agrega una transacción compensatoria que lleva el mismo ID de transferencia. 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 durante 300 segundos de forma predeterminada (clave del systemplane idempotency.duplicate_guard_ttl_seconds). 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 por tenant

Lerian aísla los datos de cada tenant. 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. Las tablas de negocio usan los campos de organización de Midaz solo para autorización de ámbito de negocio dentro del tenant.

​
Observabilidad

El plugin escribe logs JSON estructurados, puede exportar trazas y métricas de OpenTelemetry y puede servir métricas de Prometheus. 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.