Skip to main content
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.

​
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)
  • Calcula e aplica as tarifas antes de o cliente confirmar
  • Detecta e bloqueia transferências duplicadas dentro de uma janela configurável
  • Valida os dias úteis do BACEN contra o calendário bacen_holidays (carga estática para 2026–2028, atualizador ANBIMA ao vivo pendente)
  • Assina as mensagens com o certificado digital da sua instituição, como o BACEN exige
  • Repete automaticamente as operações que falham
  • 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

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

​
Etapa 2: Preparar a assinatura (opcional)

Endpoint: POST /v1/transfers/signing/prepare
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

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

​
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.
O polling do TED IN vem desligado por padrão. Para ligá-lo, defina JD_POLLING_ENABLED depois de configurar as credenciais da JD e o worker de polling.

​
Como funciona o P2P

As transferências P2P movem fundos entre duas contas da mesma organização. Elas não usam a rede do SPB, e a liquidação é instantânea.
  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 aceita dois modelos de deploy. A variável de ambiente DEPLOYMENT_MODE seleciona o modelo.

​
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. No modo saas, o plugin roda como um serviço multi-tenant. O serviço de plataforma de multi-tenancy resolve a identidade do tenant, as credenciais da JD, os segredos de webhook e as definições selecionadas 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)

Em deploys BYOC, a sua instituição fornece as credenciais da JD Consultores e a chave privada RSA que assina as mensagens. O seu time de DevOps define esses valores por variáveis de ambiente. Você mantém o controle total da conexão com a JD, e o plugin roda inteiramente na sua própria infraestrutura. O BYOC é o modelo de deploy padrão (byoc). O plugin carrega toda a configuração a partir de variáveis de ambiente na inicialização, incluindo as credenciais da JD, os segredos de webhook e as definições de tarifa.

​
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. Para eles, 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.
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 depois que a JD valida e confirma a transferência.
  • P2P: uma única transação no Midaz debita o remetente e credita o destinatário de forma atômica.
Cada transferência corresponde a um registro de transação no seu ledger do Midaz. 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.
Padrão arquitetural do TED

​
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 com um TTL configurável (padrão de 300 segundos, definido por DUPLICATE_GUARD_TTL_SEC). 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 multi-tenant

O isolamento entre tenants vem da resolução de banco de dados por tenant na plataforma de multi-tenancy. 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 (tenant:{tenantId}:{key}). 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 resolvido.

​
Observabilidade

O plugin expõe métricas Prometheus, logs JSON estruturados e traces OpenTelemetry. 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.
Os probes de liveness e de readiness ficam sem autenticação por desenho, para compatibilidade com os probes do K8s. Em deploys 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.