Receber (TED IN)

O TED IN permite que sua instituição receba transferências de qualquer banco brasileiro de forma automática. Nenhuma ação da sua equipe é necessária — o plugin cuida da detecção, validação e crédito. Quando um cliente em outro banco envia uma TED para a sua instituição, os fundos aparecem na conta do destinatário em minutos.

Como funciona

Um cliente em outro banco inicia uma transferência TED endereçada a uma das contas da sua instituição
A cada 60 segundos (padrão JD_POLL_INTERVAL_SECONDS), o plugin consulta a rede JD SPB em busca de novas transferências recebidas
A conta do destinatário é validada no seu CRM usando o número de documento presente na mensagem de transferência
O valor é creditado automaticamente na conta do destinatário (menos a tarifa de recebimento, se configurada)

Prazo de detecção e processamento

O que seu cliente experimenta após o banco de origem enviar a transferência:

Tempo	O que acontece
T+0s	Banco de origem submete a transferência à rede BACEN
T+60s	Plugin detecta a transferência; status muda para `RECEIVED`
T+32s	Conta do destinatário é localizada e confirmada; status muda para `PROCESSING`
T+35s	Valor é creditado na conta do destinatário; status muda para `COMPLETED`
T+36s	Notificação via webhook é enviada ao seu sistema

SLA típico: Menos de 1 minuto a partir do momento em que o banco de origem envia a transferência.

Estados da transferência

Estado	O que significa para o destinatário
`RECEIVED`	Transferência detectada na rede; em processamento
`PROCESSING`	Conta do destinatário confirmada; crédito sendo aplicado
`COMPLETED`	Fundos chegaram na conta do destinatário
`FAILED`	O crédito não pôde ser aplicado (ex: rejeição do Midaz), ou um chargeback reverteu um crédito já concluído

Tarifa de recebimento (cashin)

Sua organização pode cobrar uma tarifa opcional sobre transferências recebidas. Quando habilitada, a tarifa é deduzida do valor antes do crédito — o destinatário recebe o valor líquido. O valor e a configuração da tarifa são definidos por organização por meio do Fees Engine. Fórmula: valor creditado = valor da transferência − tarifa Exemplo: uma transferência de R

1.000,00 com tarifa de R

2,50 resulta em R$ 997,50 creditados na conta do destinatário. Isso é o oposto do TED OUT, onde a tarifa é adicionada ao valor e o remetente paga mais.

O que acontece quando o destinatário não é encontrado

Se o número de documento na transferência recebida não puder ser associado a uma conta no seu CRM, a transferência é automaticamente devolvida ao banco de origem. O cliente remetente recebe seu dinheiro de volta. Nenhuma intervenção manual é necessária e nenhum fundo permanece sem contabilização. A mensagem de entrada é registrada como uma transferência recebida não-entregável (no armazenamento undeliverable_incoming_transfers) e uma devolução (devolução STR0010) é despachada ao banco de origem. Esse caminho não cria um registro de transferência creditada marcado como FAILED.

Consultar transferências recebidas

Use o endpoint Listar Transferências para recuperar todas as transferências recebidas. Filtre por type=TED_IN para visualizar apenas as transferências recebidas. Endpoint: GET /v1/transfers Resposta (campos principais):

{
  "items": [
    {
      "transferId": "019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e",
      "type": "TED_IN",
      "status": "COMPLETED",
      "amount": 5000.00,
      "feeAmount": 0.00,
      "totalAmount": 5000.00,
      "createdAt": "2026-01-21T10:15:00-03:00",
      "updatedAt": "2026-01-21T10:15:30-03:00"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "totalCount": 150,
    "hasNextPage": true
  }
}

Para opções completas de parâmetros de consulta, consulte a referência Listar Transferências.

Endpoints operacionais

Dois endpoints de operador controlam o loop de polling do TED IN. Foram desenhados para scripts e runbooks, não para tráfego de usuário final.

Endpoint	Propósito
`POST /v1/transfers/ted-in/poll`	Dispara manualmente o poller do JD que normalmente roda em um cron de 60s. Útil após uma janela de incidente ou para validar a conectividade com o JD. É tenant-scoped, mas não requer `X-Organization-Id` porque o tenant é resolvido a partir do contexto autenticado. A rota requer `X-Idempotency` para retentativas seguras; retentativas com a mesma chave reproduzem a resposta em cache em vez de ler novamente a fila destrutiva do JD.
`POST /v1/transfers/ted-in/replay`	Reprocessa linhas de backlog TED IN persistidas e não processadas que já foram obtidas do JD. Isso não lê o JD novamente. A rota requer `X-Organization-Id` para o escopo de organização Midaz e `X-Idempotency` para retentativas seguras; o tenant continua sendo resolvido a partir do contexto autenticado.

Para o body da requisição, resposta, códigos de status e códigos de erro, consulte a especificação OpenAPI do TED (operações triggerTEDInPoller e replayTEDInPoller).

Três caminhos distintos de dead-letter

O plugin usa três armazenamentos de falha separados. Eles não são intercambiáveis e devem ser monitorados de forma independente:

JD parse failures — armazenadas em jd_incoming_parse_failures. A mensagem chegou do JD mas não pôde ser interpretada (XML malformado, tipo de mensagem desconhecido). Requer triagem manual.
Transferências de entrada não-entregáveis — armazenadas em undeliverable_incoming_transfers. O parsing foi bem-sucedido, mas o crédito não pôde ser aplicado (ex: conta do destinatário não encontrada). Pode gerar uma devolução automática ao banco de origem.
Webhook DLQ — a fila de retry para entregas de webhook de saída que falharam, exposta via /v1/webhooks/dlq. Não está relacionada à ingestão de TED IN; este é o canal de eventos de saída para os clientes integradores.

Webhooks

Configure um webhook para receber notificações em tempo real quando transferências chegarem. O evento transfer_incoming.completed é disparado assim que uma transferência é creditada. Consulte Webhooks para detalhes de configuração e estrutura do payload.

Reconciliação

Para reconciliação contábil e financeira, cada registro de transferência inclui os seguintes campos:

Campo	Uso
`controlNumber`	Número de controle do JD SPB — único por transferência, usado para reconciliação interbancária
`transferId`	Identificador interno da Lerian
`createdAt`	Timestamp de detecção da transferência
`completedAt`	Timestamp de crédito dos fundos

O histórico de transferências é mantido por 5 anos, conforme exigido pelas regulamentações do BACEN.

Garantias de processamento

O plugin é projetado para que nenhuma transferência seja perdida e nenhuma seja creditada duas vezes:

Sem créditos duplicados — cada mensagem de transferência carrega um número de sequência único; o plugin rejeita qualquer tentativa de processar a mesma mensagem mais de uma vez
Retry automático em caso de falha — erros transitórios (como uma interrupção momentânea do serviço) são tentados novamente com backoff exponencial antes que qualquer estado de falha seja registrado
Dead-letter queue para problemas irresolvíveis — se uma transferência não puder ser processada após todas as tentativas, ela é movida para uma dead-letter queue para revisão manual, garantindo que nada seja descartado silenciosamente

​Como funciona

​Prazo de detecção e processamento

​Estados da transferência

​Tarifa de recebimento (cashin)

​O que acontece quando o destinatário não é encontrado

​Consultar transferências recebidas

​Endpoints operacionais

​Três caminhos distintos de dead-letter

​Webhooks

​Reconciliação

​Garantias de processamento