TED Guide

This guide explains how to send and receive TED (Transferência Eletrônica Disponível) through the CorpX API. TED is a BACEN interbank transfer that operates in a specific window and is asynchronous by design — unlike PIX (instant) and internal transfers (same bank).

Overview

TED is an interbank transfer processed by the SPB (Brazilian Payment System), with a send window on business days (06:30–17:00) and same-day settlement when sent within the window.

When to use TED instead of PIX?

• Very large amounts above the PIX limit configured for the account
• Legacy systems that still require TED
• Counterparty that only accepts TED (e.g. some public agreements)
• Interbank boletos or corporate payroll in some ERPs

For day-to-day (quick payments, less than R$ 1MM, in/out of business hours), PIX is always preferable — instant, 24/7, typically cheaper.

Settlement bank MT Bank (to receive TED)

When someone wants to send a TED to you, instruct the counterparty to use these details:

Code 681 is what the counterparty enters in the “Bank” field of their app/internet banking. Don’t confuse it with the ISPB (8 digits) — banks ask for the 3-digit Compe code.

When a TED arrives in your account, you receive the ted.in.received webhook (see Webhooks).

Window and timing

TED follows the BACEN window — outside it, the transaction is scheduled for the next business day.

Server-side defensive polling

To ensure no TED gets “stuck” even if the settlement bank’s webhook fails, the TEDOut.Workflow polls the MT statement every 1 minute for up to 48 hours. If the TED doesn’t appear as settled in that period, it’s marked FAILED (timeout). You always get the final consistent state via GET /v1/accounts/{accountId}/ted/{tedId} or via the ted.out.failed webhook.

Costs and limits

• TED OUT (send): fixed fee per operation — see Backoffice → Statement with operation=FEE filter (GET /v1/accounts/{accountId}/statement?operation=FEE)
• TED IN (receive): receiving fee when applicable
• Min: R$ 0.01
• Max: no BACEN cap; CorpX allows up to the account’s operational limit (configurable via Policies)

Exact fees vary by contract — check your commercial agreement.

1. Send a 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-yourcompany" \
  -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": "Supplier payment Invoice 12345",
    "identifier": "supplier-acme-2026-05"
  }'

Fields

Response (202 Accepted)

{
  "tedId": "ted-supplier-acme-2026-05",
  "workflowId": "ted-out-ted-supplier-acme-2026-05",
  "runId": "019e1234-...",
  "idempotencyKey": "ted-001",
  "identifier": "supplier-acme-2026-05",
  "status": "PROCESSING",
  "amount": 5000.00,
  "destination": {
    "bankCode": "001",
    "branch": "1234",
    "account": "56789",
    "accountType": "CHECKING",
    "taxNumber": "12345678900",
    "holderName": "JOAO DA SILVA"
  },
  "description": "Supplier payment Invoice 12345",
  "info": "TED is asynchronous — final status converges via webhook or defensive polling (48h max)."
}

The tedId is CorpX-unique (ted-{identifier}) and is the key to query status and correlate with webhooks.

2. Query status

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

Example request:

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

Response (200)

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

States

TED Webhooks

The recommended way to track TEDs is to subscribe to webhooks — you’re notified in real time without polling.

Available events

All events use the canonical webhook envelope (id, type, occurredAt, schemaVersion, environment, tenantId, accountId, data) — the same one used by PIX, boleto and internal transfers. See Webhooks.

Payload ted.out.requested

{
  "id": "ted-ted-supplier-acme-2026-05-requested",
  "type": "ted.out.requested",
  "occurredAt": "2026-05-23T09:00:00.123456789Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-supplier-acme-2026-05",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "identifier": "supplier-acme-2026-05",
    "partnerId": "",
    "amount": 5000.00,
    "destination": {
      "bankCode": "001",
      "branch": "1234",
      "account": "56789",
      "accountType": "CHECKING",
      "taxNumber": "12345678900",
      "holderName": "JOAO DA SILVA"
    },
    "description": "Supplier payment Invoice 12345"
  }
}

Payload ted.out.confirmed

{
  "id": "ted-ted-supplier-acme-2026-05-confirmed",
  "type": "ted.out.confirmed",
  "occurredAt": "2026-05-23T09:32:15.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "tedId": "ted-supplier-acme-2026-05",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "identifier": "supplier-acme-2026-05",
    "partnerId": "supplier-acme-2026-05",
    "amount": 5000.00,
    "destination": { "bankCode": "001", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
    "description": "Supplier payment Invoice 12345"
  }
}

Payload ted.out.failed

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

(The API returns partner reasons in Portuguese; the example above means “destination bank does not exist in the 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-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "transactionId": "abc123def",
    "identifier": "TED-MT-9876",
    "partnerTxId": "abc123def",
    "accountId": "773107de-...",
    "tenantId": "tenant-yourcompany",
    "amount": 1200.00,
    "description": "Payment received",
    "receivedAt": "2026-05-23T14:15:22Z",
    "payer": {
      "name": "EMPRESA XYZ LTDA",
      "document": "98765432000110",
      "bankCode": "237",
      "bankIspb": "60746948",
      "branch": "0001",
      "account": "123456",
      "accountNumber": "123456"
    }
  }
}

Dedup

Every webhook has a unique deterministic id (e.g. ted-{tedId}-confirmed). Use the id in your store to dedupe in case of re-delivery (happens on retries of our dispatcher when your endpoint takes long to respond 2xx). The legacy ted.payment alias reuses the same payload with its own id (ted-{tedId}-payment) — tell them apart by type so you don’t drop the canonical event.

Common errors

Workflow errors (final FAILED status)

Reconciliation

CorpX runs defensive polling every minute for up to 48h after sending a TED, even when the settlement bank’s webhook arrives normally. This guarantees that internal state and bank’s real state are always aligned.

To reconcile on your side:

• Real time: subscribe to webhooks ted.out.{requested,confirmed,failed} and ted.in.received
• Point lookup: GET /v1/accounts/{accountId}/ted/{tedId}
• Statement: GET /v1/accounts/{accountId}/statement (TEDs appear with operation=TED)
• Detailed timeline: GET /v1/accounts/{accountId}/transactions/timeline?identifier={identifier} — the route accepts exactly one of identifier (yours, the same one sent on creation) or endToEndId. There is no tedId filter on this route: sending ?tedId= returns 400 invalid_query

ted.payment deprecation

The ted.payment event (v1 legacy catalog) is kept as an alias for ted.out.confirmed for compatibility. Both are dispatched together on the same terminal.

• New integrators: subscribe to ted.out.confirmed (more descriptive, aligned with boleto.paid, pix.out.completed)
• Legacy integrators: can keep ted.payment until v3.0 (date TBA)
• Migration: unsubscribe ted.payment + subscribe ted.out.confirmed — payloads are identical