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.

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:

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.

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}/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

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}/ted/{tedId}

curl "https://tenant.api.corpx.com/v1/accounts/{accountId}/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

Webhooks TED

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

Eventos disponíveis

Todos os eventos usam o envelope canônico de webhooks (id, type, occurredAt, schemaVersion, environment, tenantId, accountId, data) — o mesmo de PIX, boleto e transferências internas. Veja Webhooks.

Payload ted.out.requested

{
  "id": "ted-ted-fornecedor-acme-2026-05-requested",
  "type": "ted.out.requested",
  "occurredAt": "2026-05-23T09:00:00.123456789Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-fornecedor-acme-2026-05",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "identifier": "fornecedor-acme-2026-05",
    "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

{
  "id": "ted-ted-fornecedor-acme-2026-05-confirmed",
  "type": "ted.out.confirmed",
  "occurredAt": "2026-05-23T09:32:15.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-fornecedor-acme-2026-05",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "identifier": "fornecedor-acme-2026-05",
    "partnerId": "fornecedor-acme-2026-05",
    "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.failed

{
  "id": "ted-ted-fornecedor-acme-2026-05-failed",
  "type": "ted.out.failed",
  "occurredAt": "2026-05-23T09:32:15.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-fornecedor-acme-2026-05",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "identifier": "fornecedor-acme-2026-05",
    "partnerId": "fornecedor-acme-2026-05",
    "amount": 5000.00,
    "destination": { "bankCode": "001", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
    "description": "Pagamento de fornecedor NF 12345",
    "errorCode": "invalid_bank_code",
    "errorReason": "banco destino não existe no SPB",
    "error": "banco destino não existe no SPB"
  }
}

Payload ted.in.received

{
  "id": "ted-in-abc123def",
  "type": "ted.in.received",
  "occurredAt": "2026-05-23T14:15:22.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "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 id único e determinístico (ex.: ted-{tedId}-confirmed). Use o id na sua base para dedup em caso de re-entrega (acontece em retries do nosso dispatcher quando seu endpoint demora a responder 2xx). O alias legado ted.payment reusa o mesmo payload com id próprio (ted-{tedId}-payment) — diferencie pelo type para não descartar o evento canônico.

Erros comuns

Erros no workflow (status final FAILED)

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}/ted/{tedId}
• Extrato: GET /v1/accounts/{accountId}/statement (TEDs aparecem com operation=TED)
• Timeline detalhada: GET /v1/accounts/{accountId}/transactions/timeline?identifier={identifier} — a rota aceita exatamente um de identifier (o seu, o mesmo enviado na criação) ou endToEndId. Não existe filtro tedId nessa rota: mandar ?tedId= devolve 400 invalid_query

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