Como o plugin funciona

O plugin Bank Transfer opera o trilho TED do Brasil pela JD Consultores. A JD fornece a conectividade regulada com o SPB. O plugin conduz cada transferência do cálculo da tarifa até a confirmação da liquidação, então o seu time não chama a JD diretamente. Quando outro motor de core bancário da sua instituição usa o mesmo canal JD e o mesmo ISPB, o JD Courier compartilha o canal entre os motores.

​

O que o plugin resolve para você

---

• Envia TEDs de saída para qualquer banco brasileiro (TED OUT)
• Recebe e credita os TEDs de entrada (TED IN)
• Processa transferências internas instantâneas entre contas (P2P)
• Envia TEDs para o outro core da sua instituição, e recebe os TEDs dele, pelo JD Courier (TED entre cores)
• Detecta e bloqueia transferências duplicadas dentro de uma janela configurável
• Valida os dias úteis do BACEN contra o próprio calendário de feriados embutido, de 2026 a 2028
• Assina as mensagens com o certificado digital da sua instituição, como o BACEN exige
• Concilia com a JD as transferências cujo resultado é desconhecido
• Avisa o seu sistema por webhooks quando uma transferência muda de status

​

Como funciona o TED OUT

---

O TED OUT é um fluxo de confirmação prévia. O cliente revisa a tarifa antes de o plugin enviar a transferência.

​

Etapa 1: Iniciar

Uma iniciação de TED OUT vale até o fechamento da janela de operação daquele dia. Se o cliente não a confirmar a tempo, ela expira.

​

Etapa 2: Preparar a assinatura (opcional)

Use esta etapa apenas quando o seu tenant assina fora do plugin (modo de assinatura externa). O plugin congela o payload canônico do STR0008 e retorna os bytes exatos e o hash a assinar. O seu sistema assina o payload e passa a assinatura para a etapa de processamento. Quando o plugin assina com a sua chave local (o padrão), pule esta etapa.

​

Etapa 3: Processar

​

Como funciona o TED IN

---

1. Um banco externo envia um TED para a sua instituição pela JD Consultores.
2. O plugin consulta a JD a cada 60 segundos (padrão) para detectar novas transferências de entrada.
3. O plugin valida o destinatário no CRM para achar a conta correta.
4. O plugin credita a conta no Midaz e cria um registro de transferência concluída.
5. O seu sistema recebe um webhook que confirma o crédito.

​

Como funciona o P2P

---

As transferências P2P movem fundos entre duas contas da mesma organização e do mesmo ledger do Midaz. Elas não usam a rede do SPB, e a liquidação é instantânea. O P2P entre dois ledgers vem desligado por padrão.

1. O seu sistema chama o plugin com a conta do remetente, a conta do destinatário e o valor.
2. O plugin calcula a tarifa, se houver configuração, e a mostra para confirmação.
3. Depois da confirmação, o plugin roda a transferência no Midaz.
4. As duas contas são atualizadas na hora, e o seu sistema recebe um webhook.

​

Modelos de deploy

---

O plugin TED roda em dois modelos de deploy. A variável de ambiente DEPLOYMENT_MODE (byoc por padrão, ou saas) indica o modelo. No modo saas, o plugin se recusa a iniciar a menos que PostgreSQL, Redis, MongoDB, RabbitMQ e o broker de streaming usem TLS.

​

SaaS (gerenciado pela Lerian)

Em deploys SaaS, a Lerian gerencia a integração com a JD Consultores, incluindo a manutenção de credenciais e certificados. O seu time configura apenas as definições de negócio pela Admin API, como limites de transação, tarifas e webhooks. Você não gerencia infraestrutura nem conexões.

​

BYOC (traga sua própria nuvem)

Em deploys BYOC, o plugin roda na sua própria infraestrutura. A sua instituição fornece as credenciais da JD Consultores e a chave privada RSA que assina as mensagens, e o seu time de DevOps as define por variáveis de ambiente. Você mantém o controle total da conexão com a JD.

​

Resolução da organização

O plugin identifica a organização no Midaz pelo header obrigatório X-Organization-Id nas rotas de API com escopo de organização. Alguns processos em segundo plano não recebem headers de requisição, como o poller do TED IN e os workers de conciliação. Esses processos usam a variável de ambiente ORGANIZATION_ID. Veja Configuração do TED para a lista completa de variáveis de ambiente aceitas.

​

Integração com o Midaz

---

Todas as movimentações financeiras passam pelo ledger do Midaz. O plugin cria uma transação no Midaz para cada transferência:

• TED OUT: o plugin retém os fundos na etapa de processamento (por pending: true) e depois os debita quando a JD confirma a liquidação.
• TED IN: o plugin credita os fundos quando o TED de entrada chega da JD.
• P2P: o plugin debita o remetente e credita o destinatário de forma atômica no Midaz.

Cada transferência registra a transação dela no Midaz em midazTransactionId. Um chargeback de TED IN adiciona uma transação compensatória que carrega o mesmo ID de transferência. Veja Dados e relatórios do TED para os campos disponíveis para conciliação.

​

Para desenvolvedores

---

​

Arquitetura

O plugin usa uma arquitetura Hexagonal (Ports and Adapters) com CQRS. Esse desenho mantém a lógica de negócio separada da infraestrutura. Você pode adicionar um novo adaptador, como um provedor de SPB diferente, sem mudar o comportamento central.

​

Detecção de duplicidade

O plugin monta um fingerprint de detecção de duplicidade para cada transferência. O fingerprint cobre senderAccountId, os dados do destinatário (ISPB, agência, conta, documento do titular), o valor e a finalidade. O plugin guarda o fingerprint no Redis por 300 segundos por padrão (chave do systemplane idempotency.duplicate_guard_ttl_seconds). A organização não faz parte do fingerprint. O isolamento entre tenants vem do prefixo da chave no Redis. O plugin rejeita uma requisição duplicada dentro da janela com 409 Conflict e o código de erro BTF-0012.

​

Isolamento de dados por tenant

A Lerian isola os dados de cada tenant. O plugin lê o tenantId da claim do JWT ou do contexto autenticado, nunca do X-Organization-Id. O cache do Redis usa prefixos de chave por tenant. As tabelas de negócio usam os campos de organização do Midaz apenas para autorização de escopo de negócio dentro do tenant.

​

Observabilidade

O plugin escreve logs JSON estruturados, pode exportar traces e métricas OpenTelemetry e pode servir métricas Prometheus. Ele também expõe probes de liveness e de readiness sem autenticação para a orquestração no Kubernetes. Esses probes importam principalmente em deploys BYOC.