Receber (TED IN)

O TED IN deixa a sua instituição receber transferências de qualquer banco brasileiro. 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. Uma transferência que o plugin não consegue creditar nem devolver sozinho aguarda um operador.

Como funciona

Um cliente de outro banco começa uma transferência TED para uma das contas da sua instituição
Quando o polling do TED IN está ligado (JD_POLLING_ENABLED), o plugin consulta a rede do JD SPB em busca de novas transferências de entrada a cada 60 segundos (padrão JD_POLL_INTERVAL_SECONDS)
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, menos a tarifa de cashin, se você configurou uma. O plugin lança o crédito no ledger do destinatário no Midaz, conforme o roteamento do ledger daquela organização, daquele ledger e do tipo de transferência

Créditos ao cliente

O plugin também credita o destinatário em sete créditos ao cliente que o banco pagador envia como outras mensagens STR. Cada um tem o próprio tipo de transferência:

Mensagem STR	Tipo de transferência
STR0005R2	`TED_IN_STR0005`
STR0007R2	`TED_IN_STR0007`
STR0029R2	`TED_IN_STR0029`
STR0034R2	`TED_IN_STR0034`
STR0037R2	`TED_IN_STR0037`
STR0041R2 (crédito consignado do INSS)	`TED_IN_STR0041`
STR0051R2	`TED_IN_STR0051`

Cada um desses tipos precisa do próprio vínculo no roteamento do ledger. O plugin nunca os lança no vínculo de TED_IN. Um STR0041R2 cuja tarifa bancária não é zero não é creditado: o plugin o retém com o motivo CLASSIFICATION_FAILED. No modo de tarifa legacy, o plugin-fees calcula a tarifa de cada tipo pelo pacote de tarifas do próprio tipo, nunca pelo de TED_IN. Sem pacote para o tipo, o plugin credita o valor inteiro.

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. No modo de tarifa legacy, o plugin desconta a tarifa do valor antes de creditar o destinatário, e o destinatário recebe o valor líquido. No modo de tarifa native, ele desconta apenas uma tarifa que o pacote de tarifas tira do valor. Você define o valor e a configuração da tarifa por organização pelo Fees Engine. Fórmula, para uma tarifa descontada: credited amount = transfer amount − fee Exemplo: uma transferência de R

1.000,00 com uma tarifa descontada 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.

No modo de tarifa legado, uma resposta de tarifa inválida, inclusive uma tarifa igual ou superior ao valor bruto, segue fees.fail_closed_default. Com false (padrão), o plugin credita o valor bruto com tarifa zero e registra a falha da tarifa. Com true, recusa o crédito e devolve os fundos por STR0010. O caminho de tarifa nativa do ledger é separado; veja Configuração do TED.

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, a política de tenant jd_polling.auto_return_authorized decide o que acontece. Nos dois casos, o plugin não credita nada e não cria nenhum registro de transferência.

false (padrão): o plugin não devolve nada. Ele retém a mensagem com o motivo RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED. Um operador liquida os fundos fora do plugin e depois registra o resultado com Fechar o crédito não liquidado do TED IN. O fechamento não move dinheiro.
true: o plugin devolve a transferência ao banco de origem (devolução STR0010), e o cliente que enviou recebe o dinheiro de volta.

O plugin devolve a transferência ao banco de origem, independentemente do que essa política diga, nestes casos:

A conta do destinatário não existe no ledger ou corresponde a mais de uma conta no seu CRM.
O ledger recusa o crédito.
A tarifa não pode ser resolvida e fees.fail_closed_default é true.

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 os TEDs recebidos, por um tipo TED_IN_STR para ver um tipo de crédito ao cliente, e por ledgerId para ver as transferências de um ledger. 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-21T13:15:00Z",
      "updatedAt": "2026-01-21T13:15:30Z"
    }
  ],
  "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

Estes 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.
`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 poller 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.
`GET /v1/transfers/ted-in/poller`	Lê o estado do poller: habilitado, em execução, desatualizado e o motivo da parada.

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.

Devolver uma transferência recebida

Você pode devolver um TED IN concluído ao banco pagador com Return a Transfer. A requisição precisa da permissão transfers:return.

O plugin coloca uma retenção do valor creditado na conta do destinatário.
O plugin envia um STR0010 voluntário (código de motivo de devolução 70), que devolve o valor bruto do TED IN ao banco pagador.
Quando o STR liquida o STR0010, o plugin estorna o crédito original no ledger. A devolução passa a COMPLETED.

Se a devolução é recusada, o plugin cancela a retenção, e a devolução passa a REJECTED. A devolução é uma nova transferência TED_OUT sem tarifa, e o originalTransferId dela nomeia o TED IN. Observe estas regras:

Apenas um TED recebido como STR0008R2 pode ser devolvido. Um crédito ao cliente não pode, e um crédito entre cores também não (422 BTF-0118).
Um TED IN tem no máximo uma devolução ativa.
A devolução roda apenas dentro da janela de funcionamento. Em 24 de dezembro e no último dia útil do ano, a janela das devoluções fecha no máximo às 13:00.
A devolução é lançada no vínculo de TED_OUT do ledger do TED IN.
Você não pode cancelar uma devolução.

Um chargeback (STR0010R2) de um TED IN cuja devolução ainda está em andamento aguarda até a devolução terminar. Um chargeback que chega depois que a devolução saiu aguarda um operador.

Mensagens que aguardam um operador

Monitore cada uma destas filas separadamente. Elas não são intercambiáveis:

Fila	O que ela guarda	Como consultar
Mensagens retidas	Mensagens que o plugin não creditou nem devolveu. O motivo diz o porquê: por exemplo `UNRECOGNIZED_TYPE`, `ACCOUNT_NOT_OWNED`, `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED` ou `LEDGER_ROUTE_UNRESOLVED`. Uma mensagem retida por `LEDGER_ROUTE_UNRESOLVED` ou `RECIPIENT_AMBIGUOUS_ORGANIZATIONS` é liberada quando a configuração a cobre. Depois de um reparo no CRM, chame `POST /v1/transfers/ted-in/replay`. Feche as outras com Fechar o crédito não liquidado do TED IN	Listar as mensagens retidas do TED IN
Créditos não entregáveis	Créditos que o plugin não conseguiu aplicar, com o estado da devolução deles ao banco de origem	Listar os créditos não entregáveis do TED IN
Transferências retidas pela conciliação	Créditos TED IN que o ledger não conseguiu confirmar, reembolsos de chargeback que o plugin não conseguiu concluir e devoluções cujo resultado não está comprovado. O plugin tenta de novo um chargeback em `REVERSING` a cada ciclo. Feche um reembolso de chargeback em `MANUAL_REVIEW` com Resolver a conciliação da transferência, ação `RE_POST` ou `SETTLED_BY_HAND`. Para uma devolução, o código de motivo na transferência decide qual ação a fecha	Listar as transferências pendentes de conciliação
Lacunas de conciliação	Ciclos de polling cujo resultado de recebimento é desconhecido	Listar as lacunas de conciliação do TED IN
Falhas de parsing da JD	Mensagens que o plugin não conseguiu interpretar (XML malformado ou schema divergente). Nenhuma API as lê: o operador do deploy faz a triagem delas	Nenhuma

A DLQ de webhooks é um caminho diferente: ela guarda as entregas de webhook de saída que falharam, não as transferências de entrada. Veja Webhooks.

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

Sem créditos duplicados: o plugin guarda cada mensagem da JD uma vez, pelo número de sequência dela (NumCabSeq). Ele também deduplica os créditos por número de controle, ISPB do remetente e valor.
Mensagem primeiro: o plugin guarda cada mensagem antes de processá-la. Uma mensagem que ele não consegue terminar continua não processada, e o próximo ciclo de polling a processa de novo.
Filas de operador: uma mensagem que o plugin não consegue creditar nem devolver aguarda nas filas acima.

Introdução

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Receber (TED IN)

Como funciona

Créditos ao cliente

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

Devolver uma transferência recebida

Mensagens que aguardam um operador

Webhooks

Conciliação

Garantias de processamento

​Como funciona

​Créditos ao cliente

​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

​Devolver uma transferência recebida

​Mensagens que aguardam um operador

​Webhooks

​Conciliação

​Garantias de processamento

Como funciona

Créditos ao cliente

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

Devolver uma transferência recebida

Mensagens que aguardam um operador

Webhooks

Conciliação

Garantias de processamento