Receber (TED IN)

O TED IN deixa a sua instituição receber transferências de qualquer banco brasileiro automaticamente. O seu time não faz nada. O plugin detecta, valida e credita cada transferência. Quando um cliente de outro banco envia um TED para a sua instituição, os fundos chegam à conta do destinatário em minutos.

Como funciona

Um cliente de outro banco começa uma transferência TED para uma das contas da sua instituição
A cada 60 segundos (padrão JD_POLL_INTERVAL_SECONDS), o plugin consulta a rede do JD SPB em busca de novas transferências de entrada
O plugin procura a conta do destinatário no seu CRM pelo número do documento que vem na mensagem da transferência
O plugin credita a conta do destinatário automaticamente, menos a tarifa de cashin, se você configurou uma

Linha do tempo de detecção e processamento

As etapas abaixo mostram o que acontece depois que o banco de origem envia a transferência:

Etapa	O que acontece
Envio	O banco de origem envia a transferência para a rede do SPB
Detecção	O plugin busca a transferência no próximo ciclo de polling. O status passa a `RECEIVED`
Validação	O plugin confirma a conta do destinatário. O status passa a `PROCESSING`
Crédito	O plugin credita a conta do destinatário. O status passa a `COMPLETED`
Notificação	O plugin envia o webhook para o seu sistema

Tempo típico: o crédito é concluído dentro de um ciclo de polling. Com o intervalo padrão de 60 segundos, os fundos chegam em cerca de um minuto.

Estados da transferência

Estado	O que significa para o destinatário
`RECEIVED`	O plugin detectou a transferência na rede e começou a processar
`PROCESSING`	O plugin confirmou a conta do destinatário e aplica o crédito
`COMPLETED`	Os fundos chegaram à conta do destinatário
`FAILED`	O plugin não conseguiu aplicar o crédito (por exemplo, uma rejeição do Midaz), ou um chargeback estornou um crédito concluído

Tarifa de recebimento (cashin)

A sua organização pode cobrar uma tarifa nas transferências de entrada. Quando você habilita a cobrança, o plugin desconta a tarifa do valor antes de creditar o destinatário. O destinatário recebe o valor líquido. Você define o valor e a configuração da tarifa por organização pelo Fees Engine. Fórmula: credited amount = transfer amount − fee Exemplo: uma transferência de R

1.000,00 com uma tarifa de R

2,50 credita R$ 997,50 na conta do destinatário. É o oposto do TED OUT, onde o plugin soma a tarifa por cima e o remetente paga mais.

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

Se o plugin não consegue casar o número do documento da transferência recebida com uma conta no seu CRM, ele devolve a transferência ao banco de origem automaticamente. O cliente que enviou recebe o dinheiro de volta. O seu time não faz nada, e nenhum fundo fica sem contabilização. O plugin registra a mensagem recebida como uma transferência de entrada não entregável no armazenamento undeliverable_incoming_transfers. Depois, despacha uma devolução (retorno STR0010) ao banco de origem. Esse caminho não cria um registro de transferência creditada com status FAILED.

Consultar as transferências recebidas

Use o endpoint List Transfers para recuperar todas as transferências de entrada. Filtre por type=TED_IN para ver 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 todas as opções de parâmetros de consulta, veja a referência List Transfers.

Endpoints operacionais

Três endpoints de operador controlam o laço de polling do TED IN. Eles servem a scripts e runbooks, não ao tráfego de usuário final.

Endpoint	Finalidade
`POST /v1/transfers/ted-in/poll`	Dispara manualmente o poller da JD que normalmente roda em um cron de 60s. Use depois de uma janela de incidente ou para validar a conectividade com a JD. A rota tem escopo de tenant, mas não exige `X-Organization-Id`, porque resolve o tenant a partir do contexto autenticado. Ela exige `X-Idempotency` para novas tentativas seguras. Uma nova tentativa com a mesma chave repete a resposta em cache em vez de ler de novo a fila destrutiva da JD.
`POST /v1/transfers/ted-in/replay`	Reprocessa as linhas de backlog de TED IN persistidas e não processadas que o plugin já buscou na JD. Essa rota não lê a JD de novo. Ela exige `X-Organization-Id` para o escopo de organização do Midaz e `X-Idempotency` para novas tentativas seguras. Ela ainda resolve o tenant a partir do contexto autenticado.
`POST /v1/transfers/ted-in/resume`	Limpa a trava fail-closed de recebimento e rearma um poller que a recuperação automática não consegue reviver — um filho multi-tenant em pânico ou um poller single-tenant que ultrapassou o teto rígido de pânico. Tem privilégio maior que o `/poll` porque reabre o consumo de leitura destrutiva da JD. O resume nunca contorna a barreira do caminho do dinheiro: se a trava atual ainda não tem uma lacuna de conciliação durável, a requisição é recusada com `409`. Verifique antes as lacunas pendentes com Listar as lacunas de conciliação do TED IN e, se quiser, passe `{ "acknowledge": true, "note": "..." }` para marcar a lacuna como resolvida na mesma chamada. Um poller saudável e sem trava retorna `resumed: false`, e a rota é um no-op idempotente e seguro.

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

Três caminhos distintos de dead-letter

O plugin usa três armazenamentos de falha separados. Eles não são intercambiáveis, e você deve monitorar cada um de forma independente:

Falhas de parsing da JD: o plugin as guarda em jd_incoming_parse_failures. A mensagem chegou da JD, mas o plugin não conseguiu interpretá-la (XML malformado, tipo de mensagem desconhecido). Esse armazenamento precisa de triagem manual.
Transferências de entrada não entregáveis: o plugin as guarda em undeliverable_incoming_transfers. O parsing funcionou, mas o plugin não conseguiu aplicar o crédito (por exemplo, não achou a conta do destinatário). Esse caminho pode disparar uma devolução automática ao banco de origem.
DLQ de webhooks: a fila de novas tentativas das entregas de webhook de saída que falharam, em /v1/webhooks/dlq. Não tem relação com a ingestão do TED IN. É o canal de eventos de saída para os clientes que integram.

Webhooks

Configure um webhook para receber notificações em tempo real quando as transferências chegam. O evento transfer_incoming.completed dispara assim que o plugin credita uma transferência. Veja Webhooks para a configuração e os detalhes do payload de cada evento.

Conciliação

Para a conciliação contábil e financeira, cada registro de transferência traz estes campos:

Campo	Uso
`controlNumber`	Número de controle do JD SPB — único por transferência, usado na conciliação interbancária
`transferId`	Identificador interno da Lerian
`createdAt`	Timestamp de quando o plugin detectou a transferência
`completedAt`	Timestamp de quando o plugin creditou os fundos

O plugin persiste os registros de transferência para conciliação e auditoria.

Garantias de processamento

O plugin garante que nunca perde uma transferência e nunca credita a mesma 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 duas vezes.
Nova tentativa automática em caso de falha: o plugin repete os erros transitórios (como uma interrupção momentânea de serviço) com backoff exponencial antes de registrar qualquer estado de falha.
Fila de dead-letter para problemas sem solução: se o plugin não consegue processar uma transferência depois de todas as novas tentativas, ele move a transferência para uma fila de dead-letter, para revisão manual. O plugin nunca descarta uma transferência silenciosamente.

Visão geral

Integração

Console

Receber (TED IN)

Como funciona

Linha do tempo de detecção e processamento

Estados da transferência

Tarifa de recebimento (cashin)

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

Consultar as transferências recebidas

Endpoints operacionais

Três caminhos distintos de dead-letter

Webhooks

Conciliação

Garantias de processamento

​Como funciona

​Linha do tempo de detecção e processamento

​Estados da transferência

​Tarifa de recebimento (cashin)

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

​Consultar as transferências recebidas

​Endpoints operacionais

​Três caminhos distintos de dead-letter

​Webhooks

​Conciliação

​Garantias de processamento

Como funciona

Linha do tempo de detecção e processamento

Estados da transferência

Tarifa de recebimento (cashin)

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

Consultar as transferências recebidas

Endpoints operacionais

Três caminhos distintos de dead-letter

Webhooks

Conciliação

Garantias de processamento