Skip to main content
O plugin Bank Transfer opera o sistema TED do Brasil por meio da JD Consultores. A JD fornece a conectividade regulada com o SPB. O plugin conduz cada transferência desde o cálculo da tarifa até a confirmação de liquidação, para que seu time não chame a JD diretamente.

​
O que o plugin gerencia para você

  • Envia TEDs de saída para qualquer banco brasileiro (TED OUT)
  • Recebe e credita TEDs recebidos (TED IN)
  • Processa transferências internas instantâneas entre contas (P2P)
  • Calcula e aplica tarifas antes de o cliente confirmar
  • Detecta e bloqueia transferências duplicadas dentro de uma janela configurável
  • Valida dias úteis do BACEN contra o calendário bacen_holidays (seed estática para 2026–2028, refresher em tempo real da ANBIMA pendente)
  • Assina mensagens com o certificado digital da sua instituição, conforme o BACEN exige
  • Refaz operações com falha automaticamente
  • Notifica seu sistema via webhooks quando uma transferência muda de status

​
Como o TED OUT funciona

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

Endpoint: POST /v1/transfers/initiate
1
Seu sistema chama o plugin com os detalhes da transferência: valor, destinatário e conta do remetente.
2
O plugin valida a conta do remetente, verifica os horários de funcionamento e executa a detecção de duplicatas.
3
O plugin calcula a tarifa e retorna um initiationId com os valores calculados.
4
Seu sistema exibe a tarifa ao cliente para confirmação.
A iniciação é válida por 24 horas. Se o cliente não confirmar dentro dessa janela, ela expira.

​
Etapa 2 — Preparar assinatura (opcional)

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

​
Etapa 3 — Processar

Endpoint: POST /v1/transfers/process
1
Seu sistema chama o plugin com o initiationId para confirmar.
2
O plugin verifica os limites diários e mensais e o saldo disponível.
3
O plugin reserva fundos no Midaz (um hold) e envia a mensagem assinada para a JD Consultores.
4
A JD encaminha a transferência para o banco de destino pela rede SPB.
5
O plugin recebe a confirmação de liquidação da JD e finaliza os registros.
6
Seu sistema recebe um webhook com o status final.

​
Como o TED IN funciona

  1. Um banco externo envia um TED para sua instituição por meio da JD Consultores.
  2. O plugin consulta a JD a cada 60 segundos (padrão) para detectar novas transferências recebidas.
  3. O plugin valida o destinatário no CRM para encontrar a conta correta.
  4. O plugin credita a conta no Midaz e cria um registro de transferência concluída.
  5. Seu sistema recebe um webhook que confirma o crédito.
O polling de TED IN está desativado por padrão. Para ativá-lo, defina JD_POLLING_ENABLED depois de configurar as credenciais JD e o worker de polling.

​
Como o P2P funciona

Transferências P2P movem fundos entre duas contas da mesma organização. Elas não usam a rede SPB, e a liquidação é instantânea.
  1. 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 configurada, e a apresenta para confirmação.
  3. Após a confirmação, o plugin executa a transferência no Midaz.
  4. Ambas as contas são atualizadas imediatamente, e seu sistema recebe um webhook.

​
Modelos de deployment

O plugin TED suporta dois modelos de deployment. A variável de ambiente DEPLOYMENT_MODE seleciona o modelo.

​
SaaS (gerenciado pela Lerian)

Nos deployments SaaS, a Lerian gerencia a integração com a JD Consultores, incluindo a manutenção de credenciais e certificados. Sua equipe configura apenas as definições em nível de negócio via Admin API, como limites de transação, tarifas e webhooks. Você não gerencia infraestrutura ou conexões. No modo saas, o plugin funciona como um serviço multi-tenant. O serviço da plataforma de multi-tenancy resolve a identidade do tenant, as credenciais JD, os segredos de webhook e determinadas definições em tempo de execução. Esse modo exige as variáveis MULTI_TENANT_* e AWS_REGION, e o plugin as usa ativamente.

​
BYOC (traga suas próprias credenciais)

Nos deployments BYOC, sua instituição fornece as credenciais da JD Consultores e a chave privada RSA que assina as mensagens. Sua equipe de DevOps define esses valores por meio de variáveis de ambiente. Você mantém controle total da conexão com a JD, e o plugin funciona inteiramente dentro da sua própria infraestrutura. BYOC é o modo de deployment padrão (byoc). O plugin carrega toda a configuração de variáveis de ambiente no boot, incluindo credenciais JD, segredos de webhook e definições de tarifas.

​
Resolução de organização

O plugin identifica a organização Midaz a partir do 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 de TED IN e os workers de reconciliação. Para esses, o plugin recorre à variável de ambiente ORGANIZATION_ID.
No modo byoc, o plugin ignora as variáveis de multi-tenancy (MULTI_TENANT_*) e AWS_REGION.
Consulte Configuração do TED para a lista completa de variáveis de ambiente suportadas.

​
Integração com o Midaz

Todas as movimentações financeiras passam pelo ledger do Midaz. O plugin cria uma transação Midaz para cada transferência:
  • TED OUT — o plugin retém os fundos na etapa de processo (via pending: true), depois os debita quando a JD confirma a liquidação.
  • TED IN — o plugin credita os fundos depois que a JD valida e confirma a transferência.
  • P2P — uma única transação Midaz debita o remetente e credita o destinatário atomicamente.
Cada transferência corresponde a um registro de transação no seu ledger Midaz. Consulte Dados e relatórios do TED para os campos disponíveis para reconciliação.

​
Para desenvolvedores

​
Arquitetura

O plugin usa uma arquitetura Hexagonal (Portas e Adaptadores) com CQRS. Esse design mantém a lógica de negócio separada da infraestrutura. Você pode adicionar um novo adaptador, como um provedor SPB diferente, sem uma mudança no comportamento central.
Ted Architectural Pattern

​
Detecção de duplicatas

O plugin constrói um fingerprint de detecção de duplicatas 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 armazena o fingerprint no Redis com um TTL configurável (padrão 300 segundos, definido por DUPLICATE_GUARD_TTL_SEC). A organização não faz parte do fingerprint. O isolamento de tenant vem do prefixo da chave 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 multi-tenant

O isolamento de tenant vem da resolução de banco de dados por tenant na plataforma de multi-tenancy. O plugin lê o tenantId do claim JWT ou do contexto autenticado, nunca de X-Organization-Id. O cache Redis usa prefixos de chave por tenant (tenant:{tenantId}:{key}). As tabelas de negócio usam os campos de organização do Midaz apenas para a autorização de escopo de negócio dentro do tenant resolvido.

​
Observabilidade

O plugin expõe métricas Prometheus, logs JSON estruturados e traces OpenTelemetry. Ele também expõe probes de liveness e readiness sem autenticação para a orquestração do Kubernetes. Esses probes importam principalmente para os deployments BYOC.
Os probes de liveness e readiness não requerem autenticação por design, para a compatibilidade com os probes K8s. Nos deployments BYOC, restrinja o acesso a esses probes no nível de rede, por exemplo com regras de ingress ou security groups. Isso mantém o status das dependências internas fora da internet pública.