API Internet BankingTed

Send TED (Brazilian interbank transfer)

Sends a TED (Transferência Eletrônica Disponível) to another bank in the SPB network. **Asynchronous by design.** The POST only confirms receipt by the settlement bank (status `PROCESSING`); the final terminal state arrives via webhooks `ted.out.confirmed` or `ted.out.failed` (or via the GET status endpoint). **BACEN window:** business days 06:30–17:00 (Brazilian time). TEDs sent within the window settle the same day (~30 minutes). Outside the window, the TED is scheduled for the next business day. **Defensive polling:** the server polls the partner statement every 1 minute for up to 48 hours, ensuring convergence even if the partner webhook is delayed or lost. Settlement bank for **receiving** TEDs: MT Instituição de Pagamentos — **Compe code 681 / ISPB 50871921**. See [TED guide](/docs/guides/ted) for details.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

X-Acting-DocumentstringOptional
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN.
X-Transaction-PinstringOptional

Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).

X-Acting-IpstringOptional

Real IP of the end user, for integrator credentials calling on their behalf. This is the IP evaluated against cashoutSourceIps — without it the check would see your server’s IP. Ignored for delegated credentials, where the connection IP is already the right one.

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Request

This endpoint expects an object.
valuedoubleRequired
Amount in BRL, positive, max 2 decimals.
bankCodestringRequired

Destination bank Compe code — 3 digits (e.g. 001, 237, 341). TED does not accept ISPB: an 8-digit value is rejected with 400 invalid_bank_code. For PIX by bank account, ISPB is accepted (bankIspb).

branchstringRequired
Destination branch, digits only.
accountstringRequired

Destination account number, digits only (no final check digit).

taxNumberstringRequired

Recipient CPF (11) or CNPJ (14) digits, no punctuation.

holderNamestringRequired

Recipient legal/full name.

accountTypeenumOptionalDefaults to CHECKING
Destination account type. Defaults to CHECKING if omitted.
descriptionstringOptional

Optional free-form message (NF number, reference, etc.).

identifierstringOptional<=38 characters

Integrator correlation key forwarded to the settlement bank and echoed in TED webhooks (ted.out.*). Max 38 chars [A-Za-z0-9._-]. Distinct from the Idempotency-Key header (HTTP attempt identity). Auto-generated hex UUID (32 chars) if omitted.

Response

Idempotent retry — returns the existing TED state.

tedIdstring

Internal TED ID (format ted-{identifier}). Use to query status.

statusenum

PROCESSING when the workflow started successfully; ACCEPTED when the workflow could not be started immediately (poll later).

workflowIdstringOptional
runIdstringOptional
idempotencyKeystringOptional
identifierstringOptional
amountdoubleOptional
destinationobjectOptional
descriptionstringOptional
infostringOptional
Notes about the asynchronous nature of TED.

Errors

400
Bad Request Error
403
Forbidden Error
500
Internal Server Error
503
Service Unavailable Error