Guia de TED

Este guia explica como enviar e receber TED (Transferência Eletrônica Disponível) através da CorpX API. TED é uma modalidade de transferência interbancária do BACEN que opera em janela específica e é assíncrona por design — diferente do PIX (instantâneo) e da transferência interna (mesmo banco).

Visão Geral

TED é uma transferência entre bancos diferentes processada pelo SPB (Sistema de Pagamentos Brasileiro), com janela de envio em dias úteis (06:30–17:00) e liquidação no mesmo dia útil quando enviada dentro da janela.

Característica	PIX	TED	Internal Transfer
Janela	24/7	Dias úteis 06:30–17:00	24/7
Liquidação	Instantânea (menos de 10s)	~30min após envio	Instantânea
Bancos	Qualquer (rede PIX)	Qualquer (rede SPB)	Mesmo banco
Custo	Variável	Variável (maior que PIX)	Tipicamente zero
Limite mínimo	R$ 0,01	R$ 0,01	R$ 0,01
Limite máximo	Configurável	Sem teto BACEN	Configurável

Quando usar TED em vez de PIX?

Valores muito altos acima do limite PIX configurado para a conta
Compatibilidade com sistemas legados que ainda exigem TED
Contraparte que aceita apenas TED (ex.: alguns convênios públicos)
Boleto interbancário ou folha de pagamento corporativa em alguns ERPs

Para o dia-a-dia (pagamentos rápidos, menores que R$ 1MM, dentro/fora de horário comercial), PIX é sempre preferível — instantâneo, 24/7, tipicamente mais barato.

Banco liquidante MT Bank (para receber TED)

Quando alguém quiser enviar TED para você, instrua a contraparte a usar os dados abaixo:

Campo	Valor
Banco	MT Instituição de Pagamentos S.A.
Código Compe	681
ISPB	50871921
Tipo de conta	Conta de pagamento (informe à contraparte)
Agência	(a sua agência na MT)
Número da conta	(o seu número de conta na MT)
CPF/CNPJ do titular	(o documento titular da conta)

O código 681 é o que a contraparte vai digitar no campo "Banco" do app/internet banking dela. Não confunda com o ISPB (8 dígitos) — bancos pedem o 3 dígitos do código Compe.

Quando uma TED chega na sua conta, você recebe o webhook ted.in.received (ver Webhooks).

Janela e tempos

A TED segue a janela do BACEN — fora dela, a transação fica agendada para o próximo dia útil.

Janela	Comportamento
Dias úteis, 06:30–17:00	TED enviada dentro da janela liquida no mesmo dia útil (~30min após envio bem-sucedido)
Dias úteis, 17:00–17:30	Janela interbancária direta — não vale para clientes via PSP/MT (rejeitada)
Após 17:30 em dia útil	Agendada para D+1 útil. Status fica `PROCESSING` no nosso lado até liquidar
Fim de semana / feriado nacional	Agendada para o próximo dia útil. Polling defensivo continua até 48h

Polling defensivo do servidor

Para garantir que nenhuma TED fique "presa" mesmo se o webhook do liquidante falhar, o TEDOut.Workflow faz polling no extrato MT a cada 1 minuto por até 48 horas. Se nesse período a TED não aparece como liquidada, é marcada como FAILED (timeout). Você sempre tem o estado final consistente via GET /v1/accounts/{accountId}/transfers/ted/{tedId} ou via webhook ted.out.failed.

Custos e limites

TED OUT (enviar): tarifa fixa por operação — consulte no Backoffice → Extrato com filtro operation=FEE (GET /v1/accounts/{accountId}/statement?operation=FEE)
TED IN (receber): tarifa de recepção quando aplicável
Mínimo: R$ 0,01
Máximo: sem teto BACEN; CorpX permite até o limite operacional da conta (configurável via Policies)

Tarifas exatas variam por contrato — consulte o seu acordo comercial.

1. Enviar TED

Endpoint: POST /v1/accounts/{accountId}/ted/out

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/ted/out" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ted-001" \
  -d '{
    "value": 5000.00,
    "bankCode": "001",
    "branch": "1234",
    "account": "56789",
    "accountType": "CHECKING",
    "taxNumber": "12345678900",
    "holderName": "JOAO DA SILVA",
    "description": "Pagamento de fornecedor NF 12345",
    "identifier": "fornecedor-acme-2026-05"
  }'

Campos

Campo	Tipo	Obrigatório	Descrição
`value`	number	Sim	Valor em reais (positivo, máx. 2 casas decimais)
`bankCode`	string	Sim	Código Compe do banco destino (3 dígitos, ex.: `001` Banco do Brasil, `237` Bradesco, `341` Itaú). Aceita também ISPB de 8 dígitos.
`branch`	string	Sim	Agência destino (só dígitos)
`account`	string	Sim	Conta destino (só dígitos, sem o dígito verificador final)
`accountType`	string	Não	`CHECKING` (default), `SAVINGS`, `PAYMENT` ou `SALARY`
`taxNumber`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) do titular destinatário
`holderName`	string	Sim	Nome completo do titular destinatário
`description`	string	Não	Mensagem livre (ex.: número da NF)
`identifier`	string	Não	Identificador do integrador para correlação. Gerado automaticamente se omitido

Resposta (202 Accepted)

{
  "tedId": "ted-fornecedor-acme-2026-05",
  "workflowId": "ted-out-ted-fornecedor-acme-2026-05",
  "runId": "019e1234-...",
  "idempotencyKey": "ted-001",
  "identifier": "fornecedor-acme-2026-05",
  "status": "PROCESSING",
  "amount": 5000.00,
  "destination": {
    "bankCode": "001",
    "branch": "1234",
    "account": "56789",
    "accountType": "CHECKING",
    "taxNumber": "12345678900",
    "holderName": "JOAO DA SILVA"
  },
  "description": "Pagamento de fornecedor NF 12345",
  "info": "TED é assíncrona — status final converge via webhook ou polling defensivo (48h max)."
}

O tedId é único da CorpX (ted-{identifier}) e é a chave para consultar status e correlacionar com webhooks.

2. Consultar status

Endpoint: GET /v1/accounts/{accountId}/transfers/ted/{tedId}

curl "https://tenant.api.corpx.com/v1/accounts/{accountId}/transfers/ted/ted-fornecedor-acme-2026-05" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

Resposta (200)

{
  "tedId": "ted-fornecedor-acme-2026-05",
  "accountId": "773107de-...",
  "status": "COMPLETED",
  "amount": 5000.00,
  "identifier": "fornecedor-acme-2026-05",
  "description": "Pagamento de fornecedor NF 12345",
  "partnerId": "fornecedor-acme-2026-05",
  "createdAt": "2026-05-23T09:00:00Z",
  "updatedAt": "2026-05-23T09:32:15Z"
}

Estados

Status	Significado
`PROCESSING`	TED aceita pelo liquidante; aguardando liquidação BACEN
`COMPLETED`	TED liquidada no banco destino (terminal)
`FAILED`	TED rejeitada, expirada ou timeout 48h (terminal)

Webhooks TED

A forma recomendada de acompanhar TEDs é assinando os webhooks — você é notificado em tempo real sem precisar fazer polling.

Eventos disponíveis

Evento	Quando
`ted.out.requested`	Imediatamente após o POST ser aceito (status `PROCESSING`)
`ted.out.confirmed`	Liquidação confirmada pelo liquidante (terminal — sucesso)
`ted.out.failed`	Liquidação rejeitada/expirada ou timeout 48h (terminal — falha)
`ted.in.received`	TED recebida na sua conta (originada por terceiro)
`ted.payment`	DEPRECATED — alias de `ted.out.confirmed`. Será removido em v3.0

Payload `ted.out.requested`

{
  "eventType": "ted.out.requested",
  "eventId": "ted-fornecedor-acme-2026-05-requested",
  "data": {
    "tedId": "ted-fornecedor-acme-2026-05",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "partnerId": "",
    "amount": 5000.00,
    "destination": {
      "bankCode": "001",
      "branch": "1234",
      "account": "56789",
      "accountType": "CHECKING",
      "taxNumber": "12345678900",
      "holderName": "JOAO DA SILVA"
    },
    "description": "Pagamento de fornecedor NF 12345"
  }
}

Payload `ted.out.confirmed`

{
  "eventType": "ted.out.confirmed",
  "eventId": "ted-fornecedor-acme-2026-05-confirmed",
  "data": {
    "tedId": "ted-fornecedor-acme-2026-05",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "partnerId": "fornecedor-acme-2026-05",
    "amount": 5000.00,
    "destination": { ... },
    "description": "Pagamento de fornecedor NF 12345"
  }
}

Payload `ted.out.failed`

{
  "eventType": "ted.out.failed",
  "eventId": "ted-fornecedor-acme-2026-05-failed",
  "data": {
    "tedId": "ted-fornecedor-acme-2026-05",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "partnerId": "fornecedor-acme-2026-05",
    "amount": 5000.00,
    "destination": { ... },
    "description": "Pagamento de fornecedor NF 12345",
    "errorReason": "invalid_bank_code",
    "error": "invalid_bank_code"
  }
}

Payload `ted.in.received`

{
  "eventType": "ted.in.received",
  "eventId": "ted-in-abc123def",
  "data": {
    "transactionId": "abc123def",
    "identifier": "TED-MT-9876",
    "partnerTxId": "abc123def",
    "accountId": "773107de-...",
    "tenantId": "tenant-suaempresa",
    "amount": 1200.00,
    "description": "Pagamento recebido",
    "receivedAt": "2026-05-23T14:15:22Z",
    "payer": {
      "name": "EMPRESA XYZ LTDA",
      "document": "98765432000110",
      "bankCode": "237",
      "bankIspb": "60746948",
      "branch": "0001",
      "account": "123456",
      "accountNumber": "123456"
    }
  }
}

Dedup

Cada webhook tem eventId único e determinístico. Use o eventId na sua base para dedup em caso de re-entrega (acontece em retries do nosso dispatcher quando seu endpoint demora a responder 2xx).

Erros comuns

Código HTTP	`errorCode`	Quando
400	`invalid_bank_code`	`bankCode` não é Compe (3 dígitos) nem ISPB (8 dígitos) válido
400	`invalid_tax_number`	`taxNumber` não tem 11 (CPF) nem 14 (CNPJ) dígitos
400	`invalid_account_type`	`accountType` fora de `CHECKING\|SAVINGS\|PAYMENT\|SALARY`
400	`invalid_identifier`	`identifier` com caracteres não-ASCII ou tamanho inválido
400	`missing_fields`	`value`, `branch`, `account`, `holderName` ou `taxNumber` ausente
403	`forbidden`	Usuário não tem role no tenant da conta
503	`temporal_unavailable`	Orquestrador interno indisponível (raro; aguarde e tente novamente)
503	`partner_unavailable`	Banco liquidante indisponível
404	`not_found`	`tedId` não encontrado no GET de status

Erros no workflow (status final `FAILED`)

`errorReason`	Quando
`insufficient_funds`	Saldo insuficiente na conta de origem
`invalid_bank_code`	Banco destino não existe no SPB
`outside_banking_hours`	Tentativa de TED fora da janela aceita pelo banco liquidante
`bank_unreachable`	Erro transitório no banco destino
`limit_exceeded`	Limite operacional atingido
`timeout aguardando confirmação do parceiro (>48h)`	Polling defensivo expirou sem liquidação

Reconciliação

A CorpX faz polling defensivo a cada minuto por até 48h após enviar uma TED, mesmo que o webhook do liquidante chegue normalmente. Isso garante que estado interno e estado real do banco estejam sempre alinhados.

Para reconciliar do seu lado:

Tempo real: assine os webhooks ted.out.{requested,confirmed,failed} e ted.in.received
Lookup pontual: GET /v1/accounts/{accountId}/transfers/ted/{tedId}
Extrato: GET /v1/accounts/{accountId}/statement (TEDs aparecem com operation=TED)
Timeline detalhada: GET /v1/accounts/{accountId}/transactions/timeline?tedId={tedId}

Deprecação de `ted.payment`

O evento ted.payment (catálogo legado v1) é mantido como alias de ted.out.confirmed para compatibilidade. Ambos são disparados juntos no mesmo terminal.

Novos integradores: assinem ted.out.confirmed (mais descritivo, alinhado com boleto.paid, pix.out.completed)
Integradores legados: podem continuar com ted.payment até a v3.0 (data a ser anunciada)
Migração: desassinar ted.payment + assinar ted.out.confirmed — payloads são idênticos

Visão Geral​

Quando usar TED em vez de PIX?​

Banco liquidante MT Bank (para receber TED)​

Janela e tempos​

Polling defensivo do servidor​

Custos e limites​

1. Enviar TED​

Campos​

Resposta (202 Accepted)​

2. Consultar status​

Resposta (200)​

Estados​

Webhooks TED​

Eventos disponíveis​

Payload ted.out.requested​

Payload ted.out.confirmed​

Payload ted.out.failed​

Payload ted.in.received​

Dedup​

Erros comuns​

Erros no workflow (status final FAILED)​

Reconciliação​

Deprecação de ted.payment​